Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Version control information in your prompt
Python
tag: v0.0.3

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
bin
tests/repositories
.gitignore
.gitmodules
LICENSE
MANIFEST
README
setup.py
tests.py

README

========
vcprompt
========

Version control information in your prompt (or anywhere!).

Heavily inspired by Greg Ward's vcprompt_

.. _vcprompt: http://vc.gerg.ca/hg/vcprompt/



Installing
----------

``vcprompt`` has no dependencies outside of the Python stdlib, so you can simply
use it as a standalone script::

    curl -s http://github.com/xvzf/vcprompt/raw/master/bin/vcprompt >> ~/bin/vcprompt && chmod 755 ~/bin/vcprompt


Next, you'll want to add it to your prompt.

For bash::

    PS1='\u@\h:\w $(vcprompt)\$'


For zsh you need to enable PROMPT_SUBST first::

    setopt prompt_subst
    PS1='[%n@%m] [%~] $(vcprompt)'




Usage
-----

``vcprompt`` takes two optional arguments: ``--path`` and ``--format``.


path
~~~~

The ``--path`` argument can be used to specify a path to begin searching
for an existing VCS repository.

If not given, the value defaults to ``.``.


formatting
~~~~~~~~~~

The ``--path`` allows the output of ``vcprompt`` to be formatted in a
specific way.

The formatting arguments are:

* ``%s`` - the VCS system in use
* ``%r`` - the current revision or hash if no revision number is
  present (e.g. Git)
* ``%h`` - the current hash or revision number if no hash is present
  (i.e. Subversion, CVS, Bazaar)
* ``%b`` - the current branch (if applicable)
* ``%i`` - the status of the repository (see below)

If not given, the formatting string defaults to ``%s:%b``, that is the
current system and the branch. For example::

    git:master


The status indicators for the ``%i`` argument will use the underlying
status codes from the VCS (e.g. ``git status --short``, ``hg status``).

Consult the man pages for the VCS you are using for the full documentation.




Notes
-----

* When using the ``%i`` formatting argument with Git, you must have at
  least Git 1.7.0. Support for earlier versions may be added in the future

* The ``%i`` formatting argument has not and probably will not be implemented
  for Fossil because Fossil doesn't provide a simple interface for getting this
  information.

  Currently Fossil requires at least two external calls (``changes`` and
  ``extra``), just to get the status of a repository. Beyond this the
  output still has to be parsed and translated into usable (and preferably)
  one letter strings.

* The ``%i`` argument is slow as molasses on darcs. On average it takes
  just under a second. This is due to darcs taking a little while to work
  out if new files exist, but haven't been added, to your repository.



Requirements
------------

* Python 2.5+



Testing
-------

To run the tests, you have to initialize the submodule::

    # clone repo
    $ git clone git://github.com/xvzf/vcprompt.git
    $ cd vcprompt

    # init submodules
    $ git submodule update --init
    $ nosetests || python tests.py



TODO
----

- Only test VCSes which are available on the system
- More complete support and tests for CVS, Darcs
Something went wrong with that request. Please try again.