+.TH VCPROMPT 1 "February 2013" "vcprompt" "User Commands"
+vcprompt \- show version control information in shell prompt
+[-h] [-d] [-t timeout_ms] [-f format]
+Examine the current working directory, determine what version control
+system manages it, and print a short summary to stdout. You then
+configure your shell to run
+for every prompt, and your prompt will include that short summary.
+just shows the name of the version control system and the current
+This is the default because it's useful, implemented, and fast for
+almost all supported version control systems.
+You can get different information by specifying a format string with
+the -f option. See \fBFORMAT STRINGS\fR below.
+In a directory that is not under the control of a supported version
+terminates quickly and with no output.
+Print debug messages to stdout, and always end with a newline. Useful
+does not print what you thought it should print. Do not use this in
+Specify a custom format string (default: "[%n:%b] "). See \fBFORMAT
+milliseconds of attempting to analyze the working dir. Useful if you
+have slow operations (e.g. %m or %u) in your format string that are
+tolerable in small working dirs, but not in large ones. The timeout
+applies to the whole run of
+If it fires, no partial information will be printed; the entire
+uses printf-style format strings, where % followed by a single letter
+expands to some piece of information about the current working dir.
+The supported format specifiers are:
+The name of the current branch.
+The current revision number, changeset ID, or commit ID.
+A single "?" if there are any unknown (untracked) files in the working
+a single "+" if there are any uncommitted changes (modified, added, or
+removed files) in the working dir. Slow.
+A short all-lowercase name for the version control system managing the
+working dir: e.g. "cvs", "svn", "hg", "git", "fossil".
+Not all version control systems support all format specifiers. For
+example, CVS has no notion of a single revision identifier, so
+ignores %r in a CVS working dir. See the section on each version
+control system below for more details.
+Some format specifiers are slow with most or all supported version
+control systems. "Slow" generally means that it requires spawning an
+external command, like "git status" or "fossil info".
+tries hard to avoid spawning external commands, but sometimes it can't
+considers the current directory a CVS working dir if file
+(branch) is supported by reading
+if that file does not exist,
+displays the branch as "trunk".
+looks only in the current dir, not in any subdirectories, so it will
+not notice mixed-branch working dirs.
+is not supported because CVS has no global revision ID.
+are not supported because CVS has no easy way to get that
+considers the current directory a git working dir if directory
+(branch) is supported by reading file
+directly. If that file does not refer to a branch (e.g. you have
+checked out a specified commit), then
+reports the branch as "unknown".
+(revision) expands to the first 12 characters of the commit ID of
+is supported by running "git diff --no-ext-diff --quiet --exit-code",
+so it can be expensive in a large working dir.
+is supported by running "git ls-files --others --exclude-standard", so
+it can be expensive in a large working dir.
+The timeout (-t) option is useful to prevent
+from taking too long in large working dirs.
+.SH MERCURIAL (HG) SUPPORT
+considers the current directory a Mercurial (hg) working dir if
+(branch) is supported by looking for the current Mercurial bookmark (
+), or the current named branch (
+) if no bookmark is current.
+.SH SUBVERSION (SVN) SUPPORT
+currently supports Subversion up to version 1.6. It doesn't yet
+recognize Subversion 1.7 working copies. Patches are welcome!
+considers the current directory a Subversion (svn) working dir if
+is not supported because Subversion has no guaranteed way to figure
+out the branch; projects can structure their repository however they
+like, and there's no way to know which parts of the URL are just
+directories and which is the branch name. There might not even be a
+considers the current directory a Fossil working dir if either of the
+All format specifiers depend on running "fossil" commands, so every
+operation in a Fossil working dir is slow. All format specifiers except
+depend on "fossil status", so there's no harm in using lots of format
+specifiers -- however, doing so
+expensive for other version control systems.
+requires running "fossil extra", so has an extra penalty compared to
+the ther format specifiers.
+every time bash generates the prompt. For example, add
+PROMPT_COMMAND='vcprompt -f "[%b] "'
+(with your preferred format string) to
+as normal. This means that
+output will always come first.
+option, and then use command substitution in
+every time zsh generates the prompt. For example, add
+if [ -n "$PROMPT" ]; then
+ PROMPT='$(vcprompt -f "[%b] ")$ '
+file. You can of course use all of zsh's prompt escapes in
+this example just uses "$ " for the rest of the prompt.