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:
default
the one used if none is specified
command
used 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.
formats
A list of formats, used when actionformats is not used (which is most of the time).
actionformats
A list of formats, used if there is a special action going on in your current repository; like an interactive rebase or a merge conflict.
branchformat
Some 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.
nvcsformats
These "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.
hgrevformat
hg
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-exports
Defines the maximum number of
vcs_info_msg_*_
variables vcs_info
will set.
enable
A 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.
disable
A 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-patterns
A 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-quilt
If enabled, the quilt
support code is active in ‘addon’ mode.
See Quilt Support for details.
quilt-standalone
If enabled, ‘standalone’ mode detection is attempted if no VCS is active in a given directory. See Quilt Support for details.
quilt-patch-dir
Overwrite the value of the $QUILT_PATCHES
environment variable. See
Quilt Support for details.
quiltcommand
When quilt
itself is called in quilt support, the value of this style
is used as the command name.
check-for-changes
If 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-changes
This 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.
stagedstr
This string will be used in the %c
escape if there are staged changes in
the repository.
unstagedstr
This string will be used in the %u
escape if there are unstaged changes
in the repository.
command
This 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-server
This 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-simple
If 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-revision
If 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-mq
If set to true, the hg
backend will look for a Mercurial Queue (mq
)
patch directory. Information will be available via the ‘%m
’ replacement.
get-bookmarks
If 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-escapes
Determines if we assume that the assembled
string from vcs_info
includes prompt escapes. (Used by
vcs_info_lastmsg
.)
debug
Enable debugging output to track possible problems. Currently this style
is only used by vcs_info
’s hooks system.
hooks
A list style that defines hook-function names. See Hooks in vcs_info below for details.
patch-format
nopatch-format
This 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-unapplied
This 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-exports
2
enable
ALL
disable
(empty list)
disable-patterns
(empty list)
check-for-changes
false
check-for-staged-changes
false
stagedstr
(string: "S")
unstagedstr
(string: "U")
command
(empty string)
use-server
false
use-simple
false
get-revision
false
get-mq
true
get-bookmarks
false
use-prompt-escapes
true
debug
false
hooks
(empty list)
use-quilt
false
quilt-standalone
false
quilt-patch-dir
empty - use $QUILT_PATCHES
quiltcommand
quilt
patch-format
backend dependent
nopatch-format
backend dependent
get-unapplied
false
In normal formats
and actionformats
the following replacements are
done:
%s
The VCS in use (git, hg, svn, etc.).
%b
Information about the current branch.
%a
An identifier that describes the action. Only makes sense in
actionformats
.
%i
The current revision number or identifier. For hg
the hgrevformat
style may be used to customize the output.
%c
The string from the stagedstr
style if there are staged
changes in the repository.
%u
The string from the unstagedstr
style if there are
unstaged changes in the repository.
%R
The base directory of the repository.
%r
The repository name. If %R
is /foo/bar/repoXY
, %r
is repoXY
.
%S
A subdirectory within a repository. If $PWD
is
/foo/bar/repoXY/beer/tasty
, %S
is beer/tasty
.
%m
A "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.
%Q
Quilt 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:
%b
The branch name. For hg
, the branch name can include a
topic name.
%r
The current revision number or the hgrevformat
style for
hg
.
In hgrevformat
these replacements are done:
%r
The current local revision number.
%h
The current global revision identifier.
In patch-format
and nopatch-format
these replacements are done:
%p
The name of the top-most applied patch; may be overridden by the applied-string
hook.
%u
The number of unapplied patches; may be overridden by the unapplied-string
hook.
%n
The number of applied patches.
%c
The number of unapplied patches.
%a
The number of all patches (%a = %n + %c
).
%g
The names of active mq
guards (hg
backend).
%G
The 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.