Source

vcprompt / vcprompt.1

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

.SH NAME
vcprompt \- version control information in your 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 must
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
[git:master]
[hg:default]
[svn:trunk]
[cvs:trunk]
[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.

If the current directory is not under version control,
.B vcprompt
prints nothing and exits.

.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.
.IP -F
List features built-in to this
.B vcprompt
binary and terminate (mainly for testing).

.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.

.B %b
(branch) is supported by reading
.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".

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

.B %p
is not yet implemented.

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

.B %m
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

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

.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.

.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
!

.B %p
is implemented by reading MQ internals.

.B %u
and
.B %m
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
.B %u
can be considerably more expensive than just
.B %m.

.SH SUBVERSION (SVN) SUPPORT

.B vcprompt
considers the current directory a Subversion (svn) working dir if
directory
.I .svn
exists.
.B vcprompt
currently supports Subversion up to version 1.8.

.B %b
is supported by parsing the repository URL corresponding to the root
of your working copy: if we're in a checkout of
.I .../trunk
then branch is "trunk"; if we're in a checkout of
.I .../branches/FOO
then branch is "FOO"; otherwise the branch is unknown.

.B %r
reports the same as "Last Changed Rev" from "svn info" in the root of
your working copy (not necessarily the current directory), i.e. the
last revision in which this directory was changed.

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

.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.

.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.

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

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

.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 a single run of "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 other 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.

.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