vcprompt / vcprompt.1

.TH VCPROMPT 1 "February 2013" "vcprompt" "User Commands"

.SH NAME
vcprompt \- show version control information in shell prompt

.SH SYNOPSIS
.B vcprompt
[-h] [-d] [-t timeout_ms] [-f format]

.SH DESCRIPTION

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
.B vcprompt
for every prompt, and your prompt will include that short summary.

By default,
.B vcprompt
just shows the name of the version control system and the current
branch, e.g.
.nf
.in +4m
[cvs:trunk]
[git:master]
[hg:default]
[fossil:trunk]
.in -4m
.fi
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
control system,
.B vcprompt
terminates quickly and with no output.

.SH OPTIONS
.IP -d
Print debug messages to stdout, and always end with a newline. Useful
for understanding why
.B vcprompt
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
STRINGS\fR below.
.IP "-t timeout"
Terminate after
.I 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
.B vcprompt.
If it fires, no partial information will be printed; the entire
operation fails.

.SH FORMAT STRINGS

.B vcprompt
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:
.TP
.B %n
A short all-lowercase name for the version control system managing the
working dir: e.g. "cvs", "svn", "hg", "git", "fossil".
.TP
.B %b
The name of the current branch.
.TP
.B %r
The current revision number, changeset ID, or commit ID.
.TP
.B %p
The name of the currently applied patch, if any (Mercurial + MQ only,
but it looks like this could easily be supported for git + guilt).
.TP
.B %u
A single "?" if there are any unknown (untracked) files in the working
dir. Slow.
.TP
.B %m
A single "+" if there are any uncommitted changes (modified, added, or
removed files) in the working dir. Slow.
.TP
.B %%
A single "%" character.
.PP

Not all version control systems support all format specifiers. For
example, CVS has no notion of a single revision identifier, so
.B vcprompt
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".
.B vcprompt
tries hard to avoid spawning external commands, but sometimes it can't
be helped.

.SH GIT SUPPORT

.B vcprompt
considers the current directory a git working dir if directory
.I .git
exists.

Format specifier
.B %b
(branch) is supported by reading file
.I .git/HEAD
directly. If that file does not refer to a branch (e.g. you have
checked out a specified commit), then
.B vcprompt
reports the branch as "unknown".

Format specifier
.B %r
(revision) expands to the first 12 characters of the commit ID of
HEAD.

Format specifier
.B %p
is not yet implemented.

Format specifier
.B %u
is supported by running "git ls-files --others --exclude-standard", so
it can be expensive in a large working dir.

Format specifier
.B %m
is supported by running "git diff --no-ext-diff --quiet --exit-code",
so it can be expensive in a large working dir.

.SH MERCURIAL (HG) SUPPORT

.B vcprompt
considers the current directory a Mercurial (hg) working dir if
directory
.I .hg
exists.

Format specifier
.B %b
(branch) is supported by looking for the current Mercurial bookmark (
.I .hg/bookmarks.current
), or the current named branch (
.I .hg/branch
) if no bookmark is current.

Format specifier
.B %r
(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
.B vcprompt
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
.B vcprompt
!

Format specifier
.B %p
is implemented by reading MQ internals.

Format specifiers
.B %u
and
.B %m
are implemented by running "hg status", so they can be expensive in a
large working dir. Mercurial has to work harder to find unknown files
than it does to find uncommitted changes, so using
.B %u
can be considerably more expensive than just
.B %m.

.SH SUBVERSION (SVN) SUPPORT

.B vcprompt
currently supports Subversion up to version 1.6. It doesn't yet
recognize Subversion 1.7 working copies. Patches are welcome!

.B vcprompt
considers the current directory a Subversion (svn) working dir if
directory
.I .svn
exists.

Format specifier
.B %b
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
branch name.

Format specifier
.B %p
is not implemented (it makes no sense with Subversion).

Format specifiers
.B %u
and
.B %m
are not implemented.

.SH CVS SUPPORT

.B vcprompt
considers the current directory a CVS working dir if file
.I CVS/Entries
exists.

Format specifier
.B %b
(branch) is supported by reading
.I CVS/Tag;
if that file does not exist,
.B vcprompt
displays the branch as "trunk".
.B vcprompt
looks only in the current dir, not in any subdirectories, so it will
not detect mixed-branch working dirs.

Format specifier
.B %r
is not supported because CVS has no global revision ID.

Format specifier
.B %p
is not implemented (it makes no sense with CVS).

Format specifiers
.B %u
and
.B %m
are not supported because CVS has no easy way to get that
information.

.SH FOSSIL SUPPORT

.B vcprompt
considers the current directory a Fossil working dir if either of the
files
.I _FOSSIL_
or
.I .fslckout
exist.

All format specifiers depend on running "fossil" commands, so every
operation in a Fossil working dir is slow. All format specifiers except
.B %u
depend on "fossil status", so there's no harm in using lots of format
specifiers -- however, doing so
.I is
expensive for other version control systems.

Format specifier
.B %p
is not implemented.

Format specifier
.B %u
requires running "fossil extra", so has an extra penalty compared to
the ther format specifiers.

.SH CONFIGURING BASH

Use command substitution to include the output of
.B vcprompt
in your prompt. For example, add
.nf
.in +2m
if [ "$PS1" ]; then
  PS1='\\u@\\h $(vcprompt -f "[%b]")\$ '
fi
.in -2m
.fi
to
.I ~/.bashrc.
You can of course use all of bash's prompt escape sequences; the above
is just an example.

.SH CONFIGURING ZSH
Enable the
.B PROMPT_SUBST
option, and then use command substitution in
.B PROMPT
to run
.B vcprompt
every time zsh generates the prompt. For example, add
.nf
.in +2m
if [ -n "$PROMPT" ]; then
  setopt prompt_subst
  PROMPT='%n@%m $(vcprompt -f "[%b]")$ '
fi
.in -2m
.fi
to your
.I ~/.zshrc
file. You can of course use all of zsh's prompt escapes in
.B PROMPT;
this example just uses "$ " for the rest of the prompt.

.SH ENVIRONMENT
.IP VCPROMPT_FORMAT
Specifies the default format string (overridden by -f option).

.SH AUTHOR
vcprompt was written by Greg Ward <greg at gerg dot ca>.

The latest version is available from either of my public Mercurial
repositories:
.nf
.in +2m
http://hg.gerg.ca/vcprompt/
http://bitbucket.org/gward/vcprompt/
.in -2m
.fi
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.