The vcs_info feature can be configured via zstyle.
First, the context in which we are working:
:vcs_info:vcs-string:user-context:repo-root-name
is one of: git, git-svn, git-p4, hg, hg-git,
hg-hgsubversion, hg-hgsvn, darcs, bzr, cdv, mtn,
svn, cvs, svk, tla, p4 or fossil.
This is followed by ‘.quilt-quilt-mode’ in Quilt mode
(see Quilt Support for details)
and by ‘+hook-name’ while hooks are active
(see Hooks in vcs_info for details).
Currently, hooks in quilt mode don’t add the ‘.quilt-quilt-mode’ information.
This may change in the future.
is a freely configurable string, assignable by
the user as the first argument to vcs_info (see its description
below).
is the name of a repository in which you want a
style to match. So, if you want a setting specific to /usr/src/zsh,
with that being a CVS checkout, you can set repo-root-name to
zsh to make it so.
There are three special values for vcs-string: The first is named
-init-, that is in effect as long as there was no decision what VCS
backend to use. The second is -preinit-; it is used before
vcs_info is run, when initializing the data exporting variables. The
third special value is formats and is used by the vcs_info_lastmsg
for looking up its styles.
The initial value of repo-root-name is -all- and it is replaced
with the actual name, as soon as it is known. Only use this part of the
context for defining the formats, actionformats or
branchformat styles, as it is guaranteed that repo-root-name is
set up correctly for these only. For all other styles, just use '*'
instead.
There are two pre-defined values for user-context:
defaultthe one used if none is specified
commandused by vcs_info_lastmsg to lookup its styles
You can of course use ':vcs_info:*' to match all VCSs in all
user-contexts at once.
This is a description of all styles that are looked up.
formatsA list of formats, used when actionformats is not used (which is most of the time).
actionformatsA list of formats, used if there is a special action going on in your current repository; like an interactive rebase or a merge conflict.
branchformatSome backends replace %b in the formats and
actionformats styles above, not only by a branch name but also by a
revision number. This style lets you modify how that string should look.
nvcsformatsThese "formats" are set when we didn’t detect a version control system
for the current directory or vcs_info was disabled. This is useful if
you want vcs_info to completely take over the generation of your
prompt. You would do something like PS1='${vcs_info_msg_0_}' to
accomplish that.
hgrevformathg uses both a hash and a revision number to reference a specific
changeset in a repository. With this style you can format the revision
string (see branchformat) to include either or both. It’s only
useful when get-revision is true. Note, the full 40-character revision id
is not available (except when using the use-simple option) because
executing hg more than once per prompt is too slow; you may customize this
behavior using hooks.
max-exportsDefines the maximum number of
vcs_info_msg_*_ variables vcs_info will set.
enableA list of backends you want to use. Checked in the -init- context. If
this list contains an item called NONE no backend is used at all and
vcs_info will do nothing. If this list contains ALL, vcs_info
will use all known backends. Only with ALL in enable will the
disable style have any effect. ALL and NONE are case insensitive.
disableA list of VCSs you don’t want vcs_info to test for
repositories (checked in the -init- context, too). Only used if
enable contains ALL.
disable-patternsA list of patterns that are checked against $PWD. If a pattern
matches, vcs_info will be disabled. This style is checked in the
:vcs_info:-init-:*:-all- context.
Say, ~/.zsh is a directory under version control, in which you do
not want vcs_info to be active, do:
zstyle ':vcs_info:*' disable-patterns "${(b)HOME}/.zsh(|/*)"
use-quiltIf enabled, the quilt support code is active in ‘addon’ mode.
See Quilt Support for details.
quilt-standaloneIf enabled, ‘standalone’ mode detection is attempted if no VCS is active in a given directory. See Quilt Support for details.
quilt-patch-dirOverwrite the value of the $QUILT_PATCHES environment variable. See
Quilt Support for details.
quiltcommandWhen quilt itself is called in quilt support, the value of this style
is used as the command name.
check-for-changesIf enabled, this style causes the %c and %u format escapes to show
when the working directory has uncommitted changes. The strings displayed by
these escapes can be controlled via the stagedstr and unstagedstr
styles. The only backends that currently support this option are git,
hg, and bzr (the latter two only support unstaged).
For this style to be evaluated with the hg backend, the get-revision
style needs to be set and the use-simple style needs to be unset. The
latter is the default; the former is not.
With the bzr backend, lightweight checkouts only honor this style if
the use-server style is set.
Note, the actions taken if this style is enabled are potentially expensive (read: they may be slow, depending on how big the current repository is). Therefore, it is disabled by default.
check-for-staged-changesThis style is like check-for-changes, but it never checks the worktree
files, only the metadata in the .${vcs} dir. Therefore,
this style initializes only the %c escape (with stagedstr) but
not the %u escape. This style is faster than check-for-changes.
In the git backend, this style checks for changes in the index.
Other backends do not currently implement this style.
This style is disabled by default.
stagedstrThis string will be used in the %c escape if there are staged changes in
the repository.
unstagedstrThis string will be used in the %u escape if there are unstaged changes
in the repository.
commandThis style causes vcs_info to use the supplied string as the command
to use as the VCS’s binary. Note, that setting this in ’:vcs_info:*’ is
not a good idea.
If the value of this style is empty (which is the default), the used binary
name is the name of the backend in use (e.g. svn is used in an svn
repository).
The repo-root-name part in the context is always the default -all-
when this style is looked up.
For example, this style can be used to use binaries from non-default
installation directories. Assume, git is installed in /usr/bin but
your sysadmin installed a newer version in /usr/local/bin. Instead of
changing the order of your $PATH parameter, you can do this:
zstyle ':vcs_info:git:*:-all-' command /usr/local/bin/git
use-serverThis is used by the Perforce backend (p4) to decide if it should
contact the Perforce server to find out if a directory is managed
by Perforce. This is the only reliable way of doing this, but runs
the risk of a delay if the server name cannot be found. If the
server (more specifically, the host:port pair describing the
server) cannot be contacted, its name is put into the associative array
vcs_info_p4_dead_servers and is not contacted again during the session
until it is removed by hand. If you do not set this style, the p4
backend is only usable if you have set the environment variable
P4CONFIG to a file name and have corresponding files in the root
directories of each Perforce client. See comments in the function
VCS_INFO_detect_p4 for more detail.
The Bazaar backend (bzr) uses this to permit contacting the server
about lightweight checkouts, see the check-for-changes style.
use-simpleIf there are two different ways of gathering
information, you can select the simpler one by setting this style to true;
the default is to use the not-that-simple code, which is potentially a lot
slower but might be more accurate in all possible cases. This style is
used by the bzr, hg, and git backends. In the case of hg it will invoke
the external hexdump program to parse the binary dirstate cache file; this
method will not return the local revision number.
get-revisionIf set to true, vcs_info goes the extra mile to figure out the revision of
a repository’s work tree (currently for the git and hg backends,
where this kind of information is not always vital). For git, the
hash value of the currently checked out commit is available via the %i
expansion. With hg, the local revision number and the corresponding
global hash are available via %i.
get-mqIf set to true, the hg backend will look for a Mercurial Queue (mq)
patch directory. Information will be available via the ‘%m’ replacement.
get-bookmarksIf set to true, the hg backend will try to get a list of current
bookmarks. They will be available via the ‘%m’ replacement.
The default is to generate a comma-separated list of all bookmark names that refer to the currently checked out revision. If a bookmark is active, its name is suffixed an asterisk and placed first in the list.
use-prompt-escapesDetermines if we assume that the assembled
string from vcs_info includes prompt escapes. (Used by
vcs_info_lastmsg.)
debugEnable debugging output to track possible problems. Currently this style
is only used by vcs_info’s hooks system.
hooksA list style that defines hook-function names. See Hooks in vcs_info below for details.
patch-formatnopatch-formatThis pair of styles format the patch information used by the %m expando in
formats and actionformats for the git and hg backends. The value is
subject to certain %-expansions described below.
The expanded value is made available in the global backend_misc array as
${backend_misc[patches]} (also if a set-patch-format hook is used).
get-unappliedThis boolean style controls whether a backend should attempt to gather a list of unapplied patches (for example with Mercurial Queue patches).
Used by the quilt, hg, and git backends.
The default values for these styles in all contexts are:
formats" (%s)-[%b]%u%c-"
actionformats" (%s)-[%b|%a]%u%c-"
branchformat"%b:%r" (for bzr, svn, svk and hg)
nvcsformats""
hgrevformat"%r:%h"
max-exports2
enableALL
disable(empty list)
disable-patterns(empty list)
check-for-changesfalse
check-for-staged-changesfalse
stagedstr(string: "S")
unstagedstr(string: "U")
command(empty string)
use-serverfalse
use-simplefalse
get-revisionfalse
get-mqtrue
get-bookmarksfalse
use-prompt-escapestrue
debugfalse
hooks(empty list)
use-quiltfalse
quilt-standalonefalse
quilt-patch-dirempty - use $QUILT_PATCHES
quiltcommandquilt
patch-formatbackend dependent
nopatch-formatbackend dependent
get-unappliedfalse
In normal formats and actionformats the following replacements are
done:
%sThe VCS in use (git, hg, svn, etc.).
%bInformation about the current branch.
%aAn identifier that describes the action. Only makes sense in
actionformats.
%iThe current revision number or identifier. For hg
the hgrevformat style may be used to customize the output.
%cThe string from the stagedstr style if there are staged
changes in the repository.
%uThe string from the unstagedstr style if there are
unstaged changes in the repository.
%RThe base directory of the repository.
%rThe repository name. If %R is /foo/bar/repoXY, %r
is repoXY.
%SA subdirectory within a repository. If $PWD is
/foo/bar/repoXY/beer/tasty, %S is beer/tasty.
%mA "misc" replacement. It is at the discretion of the backend to decide what this replacement expands to.
The hg and git backends use this expando to display patch information.
hg sources patch information from the mq extensions; git from in-progress
rebase and cherry-pick operations and from the stgit extension. The patch-format
and nopatch-format styles control the generated string. The former is used
when at least one patch from the patch queue has been applied, and the latter
otherwise.
The hg backend displays bookmark information in this expando (in addition
to mq information). See the get-mq and get-bookmarks styles. Both
of these styles may be enabled at the same time. If both are enabled, both
resulting strings will be shown separated by a semicolon (that cannot currently
be customized).
The quilt ‘standalone’ backend sets this expando to the same value as the
%Q expando.
%QQuilt series information.
When quilt is used (either in ‘addon’ mode or as a ‘standalone’ backend),
this expando is set to the quilt series’ patch-format string.
The set-patch-format hook and nopatch-format style are honoured.
See Quilt Support below for details.
In branchformat these replacements are done:
%bThe branch name. For hg, the branch name can include a
topic name.
%rThe current revision number or the hgrevformat style for
hg.
In hgrevformat these replacements are done:
%rThe current local revision number.
%hThe current global revision identifier.
In patch-format and nopatch-format these replacements are done:
%pThe name of the top-most applied patch; may be overridden by the applied-string hook.
%uThe number of unapplied patches; may be overridden by the unapplied-string hook.
%nThe number of applied patches.
%cThe number of unapplied patches.
%aThe number of all patches (%a = %n + %c).
%gThe names of active mq guards (hg backend).
%GThe number of active mq guards (hg backend).
Not all VCS backends have to support all replacements. For nvcsformats
no replacements are performed at all, it is just a string.