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.