vcs_info Hooks (zsh)

#### 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).

  The arguments to this hook describe applied patches in the opposite order, which means that the first argument is the top-most patch and so forth.

  When the patches’ log messages can be extracted, those are embedded within each argument after a space, so each argument is of the form ‘patch-name first line of the log message’, where patch-name contains no whitespace. The `mq` backend passes arguments of the form ‘patch name’, with possible embedded spaces, but without extracting the patch’s log message.

  When setting `ret` to non-zero, the string in `${hook_com[applied-string]}` will be available as `%p` in the `patch-format` and `nopatch-format` styles. This hook is, in concert with `set-patch-format`, responsible for `%`-escaping that value for use in the prompt. (See Oddities.)

  The `quilt` backend passes to this hook the inputs `${hook_com[quilt-patches-dir]}` and, if it has been determined, `${hook_com[quilt-pc-dir]}`.

`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` in order, which means that the first argument is the patch next-in-line to be applied and so forth.

  The format of each argument is as for `gen-applied-string`, above.

  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. This hook is, in concert with `set-patch-format`, responsible for `%`-escaping that value for use in the prompt. (See Oddities.)

  The `quilt` backend passes to this hook the inputs `${hook_com[quilt-patches-dir]}` and, if it has been determined, `${hook_com[quilt-pc-dir]}`.

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

  This hook is, in concert with the `gen-applied-string` or `gen-unapplied-string` hooks if they are defined, responsible for `%`-escaping the final `patch-format` value for use in the prompt. (See Oddities.)

  The `quilt` backend passes to this hook the inputs `${hook_com[quilt-patches-dir]}` and, if it has been determined, `${hook_com[quilt-pc-dir]}`.

`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 Examples and also in the `Misc/vcs_info-examples` file in the Zsh source. They contain some explanatory code.