.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
for understanding why
does not print what you thought it should print. Do not use this in
your shell prompt!
.IP "-f format"
Specify a custom format string (default: "[%n:%b] "). See \fBFORMAT
.IP "-t timeout"
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
.SH FORMAT STRINGS
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.
The name of the currently applied patch, if any (Mercurial + MQ only,
but it looks like this could easily be supported for git + guilt).
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".
A single "%" character.
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
.SH GIT SUPPORT
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 not yet implemented.
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.
(revision) expands to the revision number of the parent of the working
dir, or a comma-separated pair of revision numbers if a merge is
active (the working dir has two parents). If
fails to parse some of Mercurial's internal data, it might print a
short changeset ID instead of a revision number. If that happens,
please report a bug in
is implemented by reading MQ internals.
are not implemented.
.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
is not implemented (it makes no sense with Subversion).
are not implemented.
.SH CVS SUPPORT
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.
is not implemented (it makes no sense with CVS).
are not supported because CVS has no easy way to get that
.SH FOSSIL SUPPORT
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.
is not implemented.
requires running "fossil extra", so has an extra penalty compared to
the ther format specifiers.
.SH CONFIGURING BASH
Set shell variable
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.
.SH CONFIGURING ZSH
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.