Next: Prompt Themes, Previous: Other Directory Functions, Up: User Contributions [Contents][Index]
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:
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.
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.
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. When hooks are active the hooks name is added after a ‘+’. (See Hooks in vcs_info below.)
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:
the one used if none is specified
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.
A list of formats, used when actionformats is not used (which is most of the time).
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.
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.
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.
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.
Defines the maximum number of vcs_info_msg_*_ variables vcs_info will set.
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.
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.
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(|/*)"
If enabled, the quilt support code is active in ‘addon’ mode. See Quilt Support for details.
If enabled, ‘standalone’ mode detection is attempted if no VCS is active in a given directory. See Quilt Support for details.
Overwrite the value of the $QUILT_PATCHES environment variable. See Quilt Support for details.
When quilt itself is called in quilt support, the value of this style is used as the command name.
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.
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.
This string will be used in the %c escape if there are staged changes in the repository.
This string will be used in the %u escape if there are unstaged changes in the repository.
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
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.
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.
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.
If set to true, the hg backend will look for a Mercurial Queue (mq) patch directory. Information will be available via the ‘%m’ replacement.
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.
Determines if we assume that the assembled string from vcs_info includes prompt escapes. (Used by vcs_info_lastmsg.)
Enable debugging output to track possible problems. Currently this style is only used by vcs_info’s hooks system.
A list style that defines hook-function names. See Hooks in vcs_info below for details.
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.
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:
" (%s)-[%b]%u%c-"
" (%s)-[%b|%a]%u%c-"
"%b:%r" (for bzr, svn, svk and hg)
""
"%r:%h"
2
ALL
(empty list)
(empty list)
false
false
(string: "S")
(string: "U")
(empty string)
false
false
false
true
false
true
false
(empty list)
false
false
empty - use $QUILT_PATCHES
quilt
backend dependent
backend dependent
false
In normal formats and actionformats the following replacements are done:
The VCS in use (git, hg, svn, etc.).
Information about the current branch.
An identifier that describes the action. Only makes sense in actionformats.
The current revision number or identifier. For hg the hgrevformat style may be used to customize the output.
The string from the stagedstr style if there are staged changes in the repository.
The string from the unstagedstr style if there are unstaged changes in the repository.
The base directory of the repository.
The repository name. If %R is /foo/bar/repoXY, %r is repoXY.
A subdirectory within a repository. If $PWD is /foo/bar/repoXY/beer/tasty, %S is beer/tasty.
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:
The branch name.
The current revision number or the hgrevformat style for hg.
In hgrevformat these replacements are done:
The current local revision number.
The current global revision identifier.
In patch-format and nopatch-format these replacements are done:
The name of the top-most applied patch (applied-string).
The number of unapplied patches (unapplied-string).
The number of applied patches.
The number of unapplied patches.
The number of all patches.
The names of active mq guards (hg backend).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
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.
An associated array which is used for bidirectional communication from the caller to hook functions. The used keys depend on the specific hook.
The active context of the hook. Functions that wish to change this variable should make it local scope first.
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:
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.
Same as start-up but after the VCS was detected.
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]}.
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.
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.
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.
This hooks is called when no version control system was detected.
The ‘hook_com’ parameter is not used.
Called as soon as the backend has finished collecting information.
The ‘hook_com’ keys available are as for the set-message hook.
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.
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.
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.
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.
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.
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.
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.maxx’. 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]