working directory for various version control systems. It is designed
to be small and lightweight rather than comprehensive.
-Currently, it knows how to get (and print) the current branch for CVS,
-Git, and Mercurial working copies. Eventually, I plan to add support
-for Subversion and Bazaar, and give it the (optional) ability to also
-indicate how dirty the working copy is, i.e. whether there are unknown
-files and whether there are local changes (modified/removed/added
+Currently, it has varying degrees of recognition for Mercurial, Git,
+CVS, and Subversion working copies.
-vcprompt currently has no external dependencies: it does everything with
-the standard C library. I suspect this will not last long: e.g. to
-determine anything about a Subversion working copy will probably require
-using the Subversion C API.
+vcprompt has no external dependencies: it does everything with the
+standard C library and POSIX calls. It should work on any
+POSIX-compliant system with a C99 compiler.
PROMPT='[%n@%m] [%~] $(vcprompt)'
+vcprompt prints nothing if the current directory is not managed by a
+You can customize the output of vcprompt using format strings, which can
+be specified either on the command line or in the VCPROMPT_FORMAT
+environment variable. For example:
+ VCPROMPT_FORMAT="%b" vcprompt
+Format strings use printf-like "%" escape sequences:
+ %n name of the VC system managing the current directory
+ (e.g. "cvs", "hg", "git", "svn")
+ %u ? if there are any unknown files
+ %m + if there are any uncommitted changes (added, modified, or
+ %% a single % character
+All other characters are expanded as-is.
+The default format string is
+which is notable because it works with every supported VC system. In
+fact, some features are meaningless with some systems: there is no
+single current revision with CVS, for example. (And there is no good
+way to quickly find out if there are any uncommitted changes or unknown
+files, for that matter.)
+Patches are welcome. Please follow these guidelines:
+ * Ensure that the tests pass before and after your patch.
+ If you cannot run the tests on a POSIX-compliant system,
+ that is a bug: please let me know.
+ * If at all possible, add a test whenever you fix a bug or implement a
+ feature. If you can write a test that has no dependencies (e.g. no
+ need to execute "git" or "hg" or whatever), add it to
+ tests/test-simple. Otherwise, add it to the appropriate VC-specific
+ test script, e.g. tests/test-git if it needs to be able to run git.
+ * Keep the dependencies minimal: preferably just C99 and POSIX.
+ If you need to run an external executable, make sure it makes
+ sense: e.g. it's OK to run "git" in a git working directory, but
+ *only* if we already know we are in a git working directory.
+ * Performance matters! I wrote vcprompt so that people wouldn't have
+ to spawn and initialize and entire Python or Perl interpreter every
+ time they execute a new shell command. Using system() to turn
+ around and spawn external commands -- especially ones that involve a
+ relatively large runtime penalty like Python scripts -- misses the
+ In fact, you'll find that vcprompt contains hacky little
+ reimplementations of select bits and pieces of Mercurial, git,
+ Subversion, and CVS precisely in order to avoid running external
+ commands. (And, in the case of Subversion, to avoid depending on a
+ large, complex library.)
+ * Stick with my coding style:
+ - curly braces on the same line *except* when defining a function
+ - C99 comments and variable declarations are OK, at least until
+ someone complains that their compiler cannot handle them
+vcprompt was written by Greg Ward <greg at gerg dot ca>.
+The latest version is available from either of my public Mercurial
+Copyright (c) 2009, 2010, Gregory P. Ward.
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+ 1. Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+ 2. Redistributions in binary form must reproduce the above copyright
+ notice, this list of conditions and the following disclaimer in
+ the documentation and/or other materials provided with the
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.