Skip to main content

๐ŸŒ€ What can Annexes do?

  1. Add a new Zi subcommand (i.e. the command thatโ€™s placed after the function zi โ€ฆ when calling Zi).

  2. Add new ice-modifiers.

  3. Register four types of hooks:

    3.1. atclone hook โ€“ run after cloning any plugin or downloading any snippet.

    3.2. atpull hook โ€“ run after pulling new commits (i.e. updating) for any plugin/snippet.

    3.3. atinit hook โ€“ run before loading any plugin/snippet, after it has been set up (i.e. downloaded).

    3.4. atload hook โ€“ run after loading any plugin/snippet.

  4. Register hooks for generating help text, shown by the zi icemods subcommand.

Commonโ€‹

  1. z-a-bin-gem-node
  2. z-a-readurl
  3. z-a-patch-dl
  4. z-a-rust

Additionalโ€‹

  1. z-a-submods
  2. z-a-unscope
  3. z-a-test
tip

Use meta-plugins to install common annexes as a group:

zi light-mode for z-shell/z-a-meta-plugins @annexes

To install common and additional annexes:

zi light-mode for z-shell/z-a-meta-plugins @annexes+rec

How to code them?โ€‹

Below is an example body of an atclone hook taken from submods annex.

It shows how to:

  1. Obtain the arguments passed to the hook.
  2. Use an ice-modifier.
  3. It also shows a useful snippet that will trim the whitespace in array elements (see # (4) โ€ฆ in the code).
  4. Utilize the last hook argument โ€“ the pluginโ€™s/snippetโ€™s containing directory.
emulate -L zsh -o extended_glob -o warn_create_global -o typeset_silent

[[ -z "${ZI_ICE[submods]}" ]] && return 0

# (1) โ€“ get arguments
[[ "$1" = plugin ]] && \
local type="$1" user="$2" plugin="$3" id_as="$4" dir="$5" hook="$6" || \
local type="$1" url="$2" id_as="$3" dir="$4" hook="$6" # type: snippet

# (2) โ€“ we're interested only in plugins/snippets
# which have the submods'' ice in their load command
[[ -z ${ZI_ICE[submods]} ]] && return 0

local -a mods parts
local mod from

# (3) โ€“ process the submods'' ice
mods=( ${(@s.;.)ZI_ICE[submods]} )
for mod in "${mods[@]}"; do
  parts=( "${(@s:->:)mod}" )
  # (4) Remove only leading and trailing whitespace
  parts=( "${parts[@]//((#s)[[:space:]]##|[[:space:]]##(#e))/}" )

  print "\nCloning submodule: ${parts[1]} to dir: ${parts[2]}"
  from="https://github.com"
  parts[1]="${from}/${parts[1]}"
  # (5) โ€“ the use of the input argument: `$dir'
  command git -C "$dir" clone --progress "${parts[1]}" "${parts[2]}"
done

The recommended method of creating a hook is to place its body into a file that starts with a right arrow โ†’ (more information, and also a za- prefix, e.g. โ†’za-myproject-atclone-hook and then to mark it for autoloading via autoload -Uz โ†’za-myproject-atclone-hook. Then register the hook, presumably in the myproject.plugin.zsh file, with the API call:

@zi-register-annex:

@zi-register-annex myproject hook:atclone \
  โ†’za-myproject-atclone-handler \
  โ†’za-myproject-atclone-help-handler \
  "submods''" # register a new ice-modifier: submods''

The general syntax of the API call is:

@zi-register-annex {project-name} \
  {hook: \
  {name-of-the-handler-function} \
  {name-of-the-HELP-handler-function} \
  "{ice-mod1}|{ice-mod2}|โ€ฆ" < hook-type >| subcommand: < new-subcommand-name > }

The last argument, i.e. the |-separated ice list, is optional. Thatโ€™s all! After this loading the plugin myproject will set up the new ice-modifier submods that will have syntax submods'{user}/{plugin} โ€“> {output-dir}; โ€ฆ' and will clone submodules when installing the original plugin or snippet!

Example of the submods ice-modifier to load the zsh-autosuggestions plugin via the Prezto module: autosuggestions:

zi ice svn submods'zsh-users/zsh-autosuggestions -> external'
zi snippet PZT::modules/autosuggestions

Check out the project which fully implements this idea, z-a-submods. It e.g. also implements the atpull hook, i.e. supports the automatic update of the submodules. The z-a-* prefix is recommended for projects which indicate annexes.

Summaryโ€‹

There are 2 or 3 subtypes for each of the hooks:

  1. atinit or !atinit โ€“ the ! version is run before the atinit ice-modifier (i.e. before zi ice atinit'echo this!'; โ€ฆ), while the normal version runs after it.
  2. atload or !atload โ€“ analogous to the atinit case: the ! version runs before the atload ice-modifier (while the normal version runs after it).
  3. atclone or !atclone โ€“ analogous to the atinit and atload cases.
  4. atpull, !atpull, or %atpull โ€“ the first two are being run only when there are new commits to be downloaded during the update. The % version is being always run, regardless of whether the update will pull any actual commits or not, and it is being run after the atpull ice-modifier.