.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.
If the current directory is not under version control,
terminates quickly 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:
A short all-lowercase name for the version control system managing the
working dir: e.g. "cvs", "svn", "hg", "git", "fossil".
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 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
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 ls-files --others --exclude-standard", so
it can be slow in a large working dir.
is supported by running "git diff --no-ext-diff --quiet --exit-code",
so it can be slow in a large working dir.
.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 implemented by running "hg status", so they can be slow in a
large working dir. Mercurial has to work harder to find unknown files
than it does to find uncommitted changes, so using
can be considerably more expensive than just
.SH SUBVERSION (SVN) SUPPORT
considers the current directory a Subversion (svn) working dir if
currently supports Subversion up to version 1.7 (version 1.8
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 detect 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 a single run of "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 other format specifiers.
.SH CONFIGURING BASH
Use command substitution to include the output of
in your prompt. For example, add
if [ "$PS1" ]; then
PS1='\\u@\\h $(vcprompt -f "[%b]")\$ '
You can of course use all of bash's prompt escape sequences; the above
is just an example.
.SH CONFIGURING ZSH
option, and then use command substitution in
every time zsh generates the prompt. For example, add
if [ -n "$PROMPT" ]; then
PROMPT='%n@%m $(vcprompt -f "[%b]")$ '
file. You can of course use all of zsh's prompt escapes in
Specifies the default format string (overridden by -f option).
vcprompt was written by Greg Ward <greg at gerg dot ca>.
The latest version is available from either of my public Mercurial