vcs_info Examples (zsh)

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