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.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%%F{yellow}:%r'

The doubled percent sign is explained in Oddities.

Alternatively, one can use the raw colour codes directly:

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

Normally when a variable is interpolated into a format string, the variable needs to be %-escaped. In this example we skipped that because we assume the value of ${fg[yellow]} doesn’t contain any % signs.

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):

vcsi() { vcs_info interactive; vcs_info_lastmsg }

This way, you can even define different formats for output via vcs_info_lastmsg in the ’:vcs_info:*:interactive:*’ 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.