zsh: Version Control Information

Next: Prompt Themes, Previous: Other Directory Functions, Up: User Contributions [Contents][Index]

### 26.5 Gathering information from version control systems

In a lot of cases, it is nice to automatically retrieve information from version control systems (VCSs), such as subversion, CVS or git, to be able to provide it to the user; possibly in the user’s prompt. So that you can instantly tell which branch you are currently on, for example.

In order to do that, you may use the `vcs_info` function.

The following VCSs are supported, showing the abbreviated name by which they are referred to within the system:

Bazaar (`bzr`)

  `http://bazaar.canonical.com/`

Codeville (`cdv`)

  `http://freecode.com/projects/codeville/`

Concurrent Versioning System (`cvs`)

  `http://www.nongnu.org/cvs/`

Darcs (`darcs`)

  `http://darcs.net/`

Fossil (`fossil`)

  `http://fossil-scm.org/`

Git (`git`)

  `http://git-scm.com/`

GNU arch (`tla`)

  `http://www.gnu.org/software/gnu-arch/`

Mercurial (`hg`)

  `http://mercurial.selenic.com/`

Monotone (`mtn`)

  `http://monotone.ca/`

Perforce (`p4`)

  `http://www.perforce.com/`

Subversion (`svn`)

  `http://subversion.apache.org/`

SVK (`svk`)

  `http://svk.bestpractical.com/`

There is also support for the patch management system `quilt` (`http://savannah.nongnu.org/projects/quilt`). See `Quilt Support` below for details.

To load `vcs_info`:

    autoload -Uz vcs_info

It can be used in any existing prompt, because it does not require any specific `$psvar` entries to be available.

#### 26.5.1 Quickstart

To get this feature working quickly (including colors), you can do the following (assuming, you loaded `vcs_info` properly - see above):

    zstyle ':vcs_info:*' actionformats \
        '%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{3}|%F{1}%a%F{5}]%f '
    zstyle ':vcs_info:*' formats       \
        '%F{5}(%f%s%F{5})%F{3}-%F{5}[%F{2}%b%F{5}]%f '
    zstyle ':vcs_info:(sv[nk]|bzr):*' branchformat '%b%F{1}:%F{3}%r'
    precmd () { vcs_info }
    PS1='%F{5}[%F{2}%n%F{5}] %F{3}%3~ ${vcs_info_msg_0_}%f%# '

Obviously, the last two lines are there for demonstration. You need to call `vcs_info` from your `precmd` function. Once that is done you need a single quoted `'${vcs_info_msg_0_}'` in your prompt.

To be able to use `'${vcs_info_msg_0_}'` directly in your prompt like this, you will need to have the `PROMPT_SUBST` option enabled.

Now call the `vcs_info_printsys` utility from the command line:

    % vcs_info_printsys
    ## list of supported version control backends:
    ## disabled systems are prefixed by a hash sign (#)
    bzr
    cdv
    cvs
    darcs
    fossil
    git
    hg
    mtn
    p4
    svk
    svn
    tla
    ## flavours (cannot be used in the enable or disable styles; they
    ## are enabled and disabled with their master [git-svn -> git])
    ## they *can* be used in contexts: ':vcs_info:git-svn:*'.
    git-p4
    git-svn
    hg-git
    hg-hgsubversion
    hg-hgsvn

You may not want all of these because there is no point in running the code to detect systems you do not use. So there is a way to disable some backends altogether:

    zstyle ':vcs_info:*' disable bzr cdv darcs mtn svk tla

You may also pick a few from that list and enable only those:

    zstyle ':vcs_info:*' enable git cvs svn

If you rerun `vcs_info_printsys` after one of these commands, you will see the backends listed in the `disable` style (or backends not in the `enable` style - if you used that) marked as disabled by a hash sign. That means the detection of these systems is skipped completely. No wasted time there.

#### 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. When hooks are active the hooks name is added after a ‘+’. (See Hooks in vcs_info below.)

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 "$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` and `hg` 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.

`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` and `hg` 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 the `rebase` command and from the and `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).

In `branchformat` these replacements are done:

`%b`

  The branch 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 (`applied-string`).

`%u`

  The number of unapplied patches (`unapplied-string`).

`%n`

  The number of applied patches.

`%c`

  The number of unapplied patches.

`%a`

  The number of all patches.

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

#### 26.5.3 Oddities

If you want to use the `%b` (bold off) prompt expansion in `formats`, which expands `%b` itself, use `%%b`. That will cause the `vcs_info` expansion to replace `%%b` with `%b`, so that zsh’s prompt expansion mechanism can handle it. Similarly, to hand down `%b` from `branchformat`, use `%%%%b`. Sorry for this inconvenience, but it cannot be easily avoided. Luckily we do not clash with a lot of prompt expansions and this only needs to be done for those.

#### 26.5.4 Quilt Support

Quilt is not a version control system, therefore this is not implemented as a backend. It can help keeping track of a series of patches. People use it to keep a set of changes they want to use on top of software packages (which is tightly integrated into the package build process - the Debian project does this for a large number of packages). Quilt can also help individual developers keep track of their own patches on top of real version control systems.

The `vcs_info` integration tries to support both ways of using quilt by having two slightly different modes of operation: ‘addon’ mode and ‘standalone’ mode).

For ‘addon’ mode to become active `vcs_info` must have already detected a real version control system controlling the directory. If that is the case, a directory that holds quilt’s patches needs to be found. That directory is configurable via the ‘`QUILT_PATCHES`’ environment variable. If that variable exists its value is used, otherwise the value ‘`patches`’ is assumed. The value from `$QUILT_PATCHES` can be overwritten using the ``quilt-patches'` style. (Note: you can use `vcs_info` to keep the value of `$QUILT_PATCHES` correct all the time via the `post-quilt` hook).

When the directory in question is found, quilt is assumed to be active. To gather more information, `vcs_info` looks for a directory called ‘.pc’; Quilt uses that directory to track its current state. If this directory does not exist we know that quilt has not done anything to the working directory (read: no patches have been applied yet).

If patches are applied, `vcs_info` will try to find out which. If you want to know which patches of a series are not yet applied, you need to activate the `get-unapplied` style in the appropriate context.

`vcs_info` allows for very detailed control over how the gathered information is presented (see the below sections, Styles and Hooks in vcs_info), all of which are documented below. Note there are a number of other patch tracking systems that work on top of a certain version control system (like `stgit` for git, or `mq` for hg); the configuration for systems like that are generally configured the same way as the quilt support.

If the quilt support is working in ‘addon’ mode, the produced string is available as a simple format replacement (`%Q` to be precise), which can be used in `formats` and `actionformats`; see below for details).

If, on the other hand, the support code is working in ‘standalone’ mode, `vcs_info` will pretend as if `quilt` were an actual version control system. That means that the version control system identifier (which otherwise would be something like ‘svn’ or ‘cvs’) will be set to ‘`-quilt-`’. This has implications on the used style context where this identifier is the second element. `vcs_info` will have filled in a proper value for the "repository’s" root directory and the string containing the information about quilt’s state will be available as the ‘misc’ replacement (and `%Q` for compatibility with ‘addon’ mode).

What is left to discuss is how ‘standalone’ mode is detected. The detection itself is a series of searches for directories. You can have this detection enabled all the time in every directory that is not otherwise under version control. If you know there is only a limited set of trees where you would like `vcs_info` to try and look for Quilt in ‘standalone’ mode to minimise the amount of searching on every call to `vcs_info`, there are a number of ways to do that:

Essentially, ‘standalone’ mode detection is controlled by a style called ‘`quilt-standalone`’. It is a string style and its value can have different effects. The simplest values are: ‘`always`’ to run detection every time `vcs_info` is run, and ‘`never`’ to turn the detection off entirely.

If the value of `quilt-standalone` is something else, it is interpreted differently. If the value is the name of a scalar variable the value of that variable is checked and that value is used in the same ‘always’/‘never’ way as described above.

If the value of `quilt-standalone` is an array, the elements of that array are used as directory names under which you want the detection to be active.

If `quilt-standalone` is an associative array, the keys are taken as directory names under which you want the detection to be active, but only if the corresponding value is the string ‘`true`’.

Last, but not least, if the value of `quilt-standalone` is the name of a function, the function is called without arguments and the return value decides whether detection should be active. A ‘0’ return value is true; a non-zero return value is interpreted as false.

Note, if there is both a function and a variable by the name of `quilt-standalone`, the function will take precedence.

#### 26.5.5 Function Descriptions (Public API)

`vcs_info` [user-context]

  The main function, that runs all backends and assembles all data into `${vcs_info_msg_*_}`. This is the function you want to call from `precmd` if you want to include up-to-date information in your prompt (see `Variable description` below). If an argument is given, that string will be used instead of `default` in the user-context field of the style context.

`vcs_info_hookadd`

  Statically registers a number of functions to a given hook. The hook needs to be given as the first argument; what follows is a list of hook-function names to register to the hook. The ‘`+vi-`’ prefix needs to be left out here. See Hooks in vcs_info below for details.

`vcs_info_hookdel`

  Remove hook-functions from a given hook. The hook needs to be given as the first non-option argument; what follows is a list of hook-function names to un-register from the hook. If ‘`-a`’ is used as the first argument, `all` occurrences of the functions are unregistered. Otherwise only the last occurrence is removed (if a function was registered to a hook more than once) . The ‘`+vi-`’ prefix needs to be left out here. See Hooks in vcs_info below for details.

`vcs_info_lastmsg`

  Outputs the last `${vcs_info_msg_*_}` value. Takes into account the value of the `use-prompt-escapes` style in `':vcs_info:formats:command:-all-'`. It also only prints `max-exports` values.

`vcs_info_printsys` [user-context]

  Prints a list of all supported version control systems. Useful to find out possible contexts (and which of them are enabled) or values for the `disable` style.

`vcs_info_setsys`

  Initializes `vcs_info`’s internal list of available backends. With this function, you can add support for new VCSs without restarting the shell.

All functions named `VCS_INFO_*` are for internal use only.

#### 26.5.6 Variable Description

`${vcs_info_msg_`N`_}` (Note the trailing underscore)

  Where N is an integer, e.g., `vcs_info_msg_0_`. These variables are the storage for the informational message the last `vcs_info` call has assembled. These are strongly connected to the `formats`, `actionformats` and `nvcsformats` styles described above. Those styles are lists. The first member of that list gets expanded into `${vcs_info_msg_0_}`, the second into `${vcs_info_msg_1_}` and the Nth into `${vcs_info_msg_N-1_}`. (See the `max-exports` style above.)

All variables named `VCS_INFO_*` are for internal use only.

#### 26.5.7 Hooks in vcs_info

Hooks are places in `vcs_info` where you can run your own code. That code can communicate with the code that called it and through that, change the system’s behaviour.

For configuration, hooks change the style context:

    :vcs_info:vcs-string+hook-name:user-context:repo-root-name

To register functions to a hook, you need to list them in the `hooks` style in the appropriate context.

Example:

    zstyle ':vcs_info:*+foo:*' hooks bar baz

This registers functions to the hook ‘foo’ for all backends. In order to avoid namespace problems, all registered function names are prepended by a ‘`+vi-`’, so the actual functions called for the ‘foo’ hook are ‘`+vi-bar`’ and ‘`+vi-baz`’.

If you would like to register a function to a hook regardless of the current context, you may use the `vcs_info_hookadd` function. To remove a function that was added like that, the `vcs_info_hookdel` function can be used.

If something seems weird, you can enable the ‘debug’ boolean style in the proper context and the hook-calling code will print what it tried to execute and whether the function in question existed.

When you register more than one function to a hook, all functions are executed one after another until one function returns non-zero or until all functions have been called. Context-sensitive hook functions are executed `before` statically registered ones (the ones added by `vcs_info_hookadd`).

You may pass data between functions via an associative array, `user_data`. For example:

    +vi-git-myfirsthook(){
        user_data[myval]=$myval
    }
    +vi-git-mysecondhook(){
        # do something with ${user_data[myval]}
    }

There are a number of variables that are special in hook contexts:

`ret`

  The return value that the hooks system will return to the caller. The default is an integer ‘zero’. If and how a changed `ret` value changes the execution of the caller depends on the specific hook. See the hook documentation below for details.

`hook_com`

  An associated array which is used for bidirectional communication from the caller to hook functions. The used keys depend on the specific hook.

`context`

  The active context of the hook. Functions that wish to change this variable should make it local scope first.

`vcs`

  The current VCS after it was detected. The same values as in the enable/disable style are used. Available in all hooks except `start-up`.

Finally, the full list of currently available hooks:

`start-up`

  Called after starting `vcs_info` but before the VCS in this directory is determined. It can be used to deactivate `vcs_info` temporarily if necessary. When `ret` is set to `1`, `vcs_info` aborts and does nothing; when set to `2`, `vcs_info` sets up everything as if no version control were active and exits.

`pre-get-data`

  Same as `start-up` but after the VCS was detected.

`gen-hg-bookmark-string`

  Called in the Mercurial backend when a bookmark string is generated; the `get-revision` and `get-bookmarks` styles must be true.

  This hook gets the names of the Mercurial bookmarks that `vcs_info` collected from ‘hg’.

  If a bookmark is active, the key `${hook_com[hg-active-bookmark]}` is set to its name. The key is otherwise unset.

  When setting `ret` to non-zero, the string in `${hook_com[hg-bookmark-string]}` will be used in the `%m` escape in `formats` and `actionformats` and will be available in the global `backend_misc` array as `${backend_misc[bookmarks]}`.

`gen-applied-string`

  Called in the `git` (with `stgit` or during rebase or merge), and `hg` (with `mq`) backends and in `quilt` support when the `applied-string` is generated; the `use-quilt` zstyle must be true for `quilt` (the `mq` and `stgit` backends are active by default).

  This hook gets the names of all applied patches which `vcs_info` collected so far in the opposite order, which means that the first argument is the top-most patch and so forth.

  When setting `ret` to non-zero, the string in `${hook_com[applied-string]}` will be used in the `%m` escape in `formats` and `actionformats`; it will be available in the global `backend_misc` array as `$backend_misc[patches]}`; and it will be available as `%p` in the `patch-format` and `nopatch-format` styles.

`gen-unapplied-string`

  Called in the `git` (with `stgit` or during rebase), and `hg` (with `mq`) backend and in `quilt` support when the `unapplied-string` is generated; the `get-unapplied` style must be true.

  This hook gets the names of all unapplied patches which `vcs_info` collected so far in the opposite order, which mean that the first argument is the patch next-in-line to be applied and so forth.

  When setting `ret` to non-zero, the string in `${hook_com[unapplied-string]}` will be available as `%u` in the `patch-format` and `nopatch-format` styles.

`gen-mqguards-string`

  Called in the `hg` backend when `guards-string` is generated; the `get-mq` style must be true (default).

  This hook gets the names of any active `mq` guards.

  When setting `ret` to non-zero, the string in `${hook_com[guards-string]}` will be used in the `%g` escape in the `patch-format` and `nopatch-format` styles.

`no-vcs`

  This hooks is called when no version control system was detected.

  The ‘`hook_com`’ parameter is not used.

`post-backend`

  Called as soon as the backend has finished collecting information.

  The ‘`hook_com`’ keys available are as for the `set-message` hook.

`post-quilt`

  Called after the `quilt` support is done. The following information is passed as arguments to the hook: 1. the quilt-support mode (‘addon’ or ‘standalone’); 2. the directory that contains the patch series; 3. the directory that holds quilt’s status information (the ‘.pc’ directory) or the string `"-nopc-"` if that directory wasn’t found.

  The ‘hook_com’ parameter is not used.

`set-branch-format`

  Called before ‘`branchformat`’ is set. The only argument to the hook is the format that is configured at this point.

  The ‘`hook_com`’ keys considered are ‘`branch`’ and ‘`revision`’. They are set to the values figured out so far by `vcs_info` and any change will be used directly when the actual replacement is done.

  If `ret` is set to non-zero, the string in `${hook_com[branch-replace]}` will be used unchanged as the ‘`%b`’ replacement in the variables set by `vcs_info`.

`set-hgrev-format`

  Called before a ‘`hgrevformat`’ is set. The only argument to the hook is the format that is configured at this point.

  The ‘`hook_com`’ keys considered are ‘`hash`’ and ‘`localrev`’. They are set to the values figured out so far by `vcs_info` and any change will be used directly when the actual replacement is done.

  If `ret` is set to non-zero, the string in `${hook_com[rev-replace]}` will be used unchanged as the ‘`%i`’ replacement in the variables set by `vcs_info`.

`pre-addon-quilt`

  This hook is used when `vcs_info`’s quilt functionality is active in "addon" mode (quilt used on top of a real version control system). It is activated right before any quilt specific action is taken.

  Setting the ‘`ret`’ variable in this hook to a non-zero value avoids any quilt specific actions from being run at all.

`set-patch-format`

  This hook is used to control some of the possible expansions in `patch-format` and `nopatch-format` styles with patch queue systems such as quilt, mqueue and the like.

  This hook is used in the `git`, `hg` and `quilt` backends.

  The hook allows the control of the `%p` (`${hook_com[applied]}`) and `%u` (`${hook_com[unapplied]}`) expansion in all backends that use the hook. With the mercurial backend, the `%g` (`${hook_com[guards]}`) expansion is controllable in addition to that.

  If `ret` is set to non-zero, the string in `${hook_com[patch-replace]}` will be used unchanged instead of an expanded format from `patch-format` or `nopatch-format`.

`set-message`

  Called each time before a ‘`vcs_info_msg_`N`_`’ message is set. It takes two arguments; the first being the ‘N’ in the message variable name, the second is the currently configured `formats` or `actionformats`.

  There are a number of ‘`hook_com`’ keys, that are used here: ‘`action`’, ‘`branch`’, ‘`base`’, ‘`base-name`’, ‘`subdir`’, ‘`staged`’, ‘`unstaged`’, ‘`revision`’, ‘`misc`’, ‘`vcs`’ and one ‘`miscN`’ entry for each backend-specific data field (`N` starting at zero). They are set to the values figured out so far by `vcs_info` and any change will be used directly when the actual replacement is done.

  Since this hook is triggered multiple times (once for each configured `formats` or `actionformats`), each of the ‘`hook_com`’ keys mentioned above (except for the `miscN` entries) has an ‘`_orig`’ counterpart, so even if you changed a value to your liking you can still get the original value in the next run. Changing the ‘`_orig`’ values is probably not a good idea.

  If `ret` is set to non-zero, the string in `${hook_com[message]}` will be used unchanged as the message by `vcs_info`.

If all of this sounds rather confusing, take a look at the Examples section below and also in the `Misc/vcs_info-examples` file in the Zsh source. They contain some explanatory code.

#### 26.5.8 Examples

Don’t use `vcs_info` at all (even though it’s in your prompt):

    zstyle ':vcs_info:*' enable NONE

Disable the backends for `bzr` and `svk`:

    zstyle ':vcs_info:*' disable bzr svk

Disable everything but `bzr` and `svk`:

    zstyle ':vcs_info:*' enable bzr svk

Provide a special formats for `git`:

    zstyle ':vcs_info:git:*' formats       ' GIT, BABY! [%b]'
    zstyle ':vcs_info:git:*' actionformats ' GIT ACTION! [%b|%a]'

All `%x` expansion in all sorts of formats (`formats`, `actionformats`, `branchformat`, you name it) are done using the ‘`zformat`’ builtin from the ‘`zsh/zutil`’ module. That means you can do everything with these `%x` items what zformat supports. In particular, if you want something that is really long to have a fixed width, like a hash in a mercurial branchformat, you can do this: `%12.12i`. That’ll shrink the 40 character hash to its 12 leading characters. The form is actually ‘`%`min`.`max`x`’. More is possible. See The zsh/zutil Module for details.

Use the quicker `bzr` backend

    zstyle ':vcs_info:bzr:*' use-simple true

If you do use `use-simple`, please report if it does ‘the-right-thing[tm]’.

Display the revision number in yellow for `bzr` and `svn`:

    zstyle ':vcs_info:(svn|bzr):*' \
           branchformat '%b%{'${fg[yellow]}'%}:%r'

If you want colors, make sure you enclose the color codes in `%{`...`%}` if you want to use the string provided by `vcs_info` in prompts.

Here is how to print the VCS information as a command (not in a prompt):

    alias vcsi='vcs_info command; vcs_info_lastmsg'

This way, you can even define different formats for output via `vcs_info_lastmsg` in the ’`:vcs_info:*:command:*`’ namespace.

Now as promised, some code that uses hooks: say, you’d like to replace the string ‘svn’ by ‘subversion’ in `vcs_info`’s `%s` `formats` replacement.

First, we will tell `vcs_info` to call a function when populating the message variables with the gathered information:

    zstyle ':vcs_info:*+set-message:*' hooks svn2subversion

Nothing happens. Which is reasonable, since we didn’t define the actual function yet. To see what the hooks subsystem is trying to do, enable the ‘`debug`’ style:

    zstyle ':vcs_info:*+*:*' debug true

That should give you an idea what is going on. Specifically, the function that we are looking for is ‘`+vi-svn2subversion`’. Note, the ‘`+vi-`’ prefix. So, everything is in order, just as documented. When you are done checking out the debugging output, disable it again:

    zstyle ':vcs_info:*+*:*' debug false

Now, let’s define the function:

    function +vi-svn2subversion() {
        [[ ${hook_com[vcs_orig]} == svn ]] && hook_com[vcs]=subversion
    }

Simple enough. And it could have even been simpler, if only we had registered our function in a less generic context. If we do it only in the ‘`svn`’ backend’s context, we don’t need to test which the active backend is:

    zstyle ':vcs_info:svn+set-message:*' hooks svn2subversion

    function +vi-svn2subversion() {
        hook_com[vcs]=subversion
    }

And finally a little more elaborate example, that uses a hook to create a customised bookmark string for the `hg` backend.

Again, we start off by registering a function:

    zstyle ':vcs_info:hg+gen-hg-bookmark-string:*' hooks hgbookmarks

And then we define the ‘`+vi-hgbookmarks`’ function:

    function +vi-hgbookmarks() {
        # The default is to connect all bookmark names by
        # commas. This mixes things up a little.
        # Imagine, there's one type of bookmarks that is
        # special to you. Say, because it's *your* work.
        # Those bookmarks look always like this: "sh/*"
        # (because your initials are sh, for example).
        # This makes the bookmarks string use only those
        # bookmarks. If there's more than one, it
        # concatenates them using commas.
        # The bookmarks returned by `hg' are available in
        # the function's positional parameters.
        local s="${(Mj:,:)@:#sh/*}"
        # Now, the communication with the code that calls
        # the hook functions is done via the hook_com[]
        # hash. The key at which the `gen-hg-bookmark-string'
        # hook looks is `hg-bookmark-string'. So:
        hook_com[hg-bookmark-string]=$s
        # And to signal that we want to use the string we
        # just generated, set the special variable `ret' to
        # something other than the default zero:
        ret=1
        return 0
    }

Some longer examples and code snippets which might be useful are available in the examples file located at Misc/vcs_info-examples in the Zsh source directory.

This concludes our guided tour through zsh’s `vcs_info`.

Next: Prompt Themes, Previous: Other Directory Functions, Up: User Contributions [Contents][Index]