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:
retThe 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_comAn associated array which is used for bidirectional communication from the caller to hook functions. The used keys depend on the specific hook.
contextThe active context of the hook. Functions that wish to change this variable should make it local scope first.
vcsThe 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-upCalled 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-dataSame as start-up but after the VCS was detected.
gen-hg-bookmark-stringCalled 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-stringCalled 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-stringCalled 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-stringCalled 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-vcsThis hooks is called when no version control system was detected.
The ‘hook_com’ parameter is not used.
post-backendCalled as soon as the backend has finished collecting information.
The ‘hook_com’ keys available are as for the set-message hook.
post-quiltCalled 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-formatCalled 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-formatCalled 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-quiltThis 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-formatThis 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-messageCalled 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.