vcs_info Configuration (zsh)

#### 26.5.2 Configuration ¶

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

vcs-string

  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.

user-context

  is a freely configurable string, assignable by the user as the first argument to `vcs_info` (see its description below).

repo-root-name

  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.