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.