🧊 Ice Modifiers

FAQ: What is ice?

The ice is something that melts in a drink, though in Zi syntax, it means adding an ice-modifier that's temporary because it disappears – which means that the ice-modifier will last only for the next Zi command.

An ice-modifiers are passed to zi ice … to obtain described effects, additionally can be added with annexes. To see all available ice-modifiers run zi icemods.

Some ice-modifiers are highlighted and clicking on them will take you to the appropriate Wiki page for an extended explanation. You may safely assume that given ice works with both plugins and snippets unless explicitly stated otherwise.

Ice effects

Ice-modifier	Description
as	Can be as"program" (alias: as"command"), and will cause to add script/program to $PATH instead of sourcing (see pick). Can also be as"completion" – use with plugins or snippets in whose only underscore-starting _* files you are interested in. 1
id-as	Nickname a plugin or snippet, e.g. create a short handler for the long-URL snippet.
teleid	Effective remote-ID (i.e.: URL, GitHub username/repo, package name, etc.).
compile	Pattern (possible {…} expansion, like {a/*,b*}) to select additional files to compile, e.g. compile"(pure | async).zsh"forsindresorhus/pure.
nocompile	Don't try to compile pick-pointed files. If passed the exclamation mark (i.e. nocompile'!'), then do compile, but after make'…' and atclone'…' (useful if Makefile installs some scripts, to point pick'…' at the location of their installation).
service	Make the following plugin or snippet a service, which will run in the background, and only in a single Zshell instance. See #zservice topic.
reset-prompt	Reset the prompt after loading the plugin/snippet (by issuing zle .reset-prompt). Note: normally it's sufficient to precede the value of wait'…' ice with !.
bindmap	To hold ;-separated strings like Key(s)A -> Key(s)B, e.g. ^R -> ^T; ^A -> ^B. In general, bindmap'…' changes bindings (done with the bindkey builtin) the plugin does. The example would cause the plugin to map Ctrl-T instead of Ctrl-R, and Ctrl-B instead of Ctrl-A. Does not work with snippets.
trackbinds	Shadow but only bindkey calls even with zi light …, i.e. even with investigating disabled (fast loading), to allow bindmap to remap the key-binds. The same effect has the zi light -b …, i.e. additional -b option to the light-subcommand. Does not work with snippets.
wrap	Takes a ;-separated list of function names to be investigated (meaning gathering report and unloading data) once during execution. It works by wrapping the functions with an investigating-enabling and disabling snippet of code. 2
aliases	Load the plugin with the aliases mechanism enabled. Use plugins that define and use aliases in their scripts.
light-mode	Load the plugin without investigating, i.e., the same as the light command. Useful with the "for" syntax, where there is no load nor light subcommand
extract	Performs archive extraction supporting multiple formats like zip, tar.gz, etc., and OS X dmg images. 3
subst	Substitute the given string into another string when sourcing the plugin script, e.g.: zi subst'autoload → autoload -Uz' ….
autoload	Autoload the given functions (from their files). Equivalent to calling atinit'autoload the-function'. Supports renaming of the function – pass '… → new-name' or '… -> new-name', e.g.: zi autoload'fun → my-fun; fun2 → my-fun2'.

Cloning options

Ice-modifier	Description
proto	Change protocol to git,ftp,ftps,ssh, rsync, etc. The default is https. Does not work with snippets.
from	Clone plugin from a given site. Supported are from"github" (default), …"github-rel", …"gitlab", …"bitbucket", …"notabug" (short names: gh, gh-r, gl, bb, nb). Can also be a full domain name e.g: for GitHub enterprise. Does not work with snippets.
ver	Used with from"gh-r" (i.e. downloading a binary release, e.g. for use with as"program") – selects which version to download. Default is latest, can also be explicit ver"latest". Works also with regular plugins, and checkouts e.g. ver"branch", i.e. a specific version. Does not work with snippets.
bpick	Used to select which release from GitHub Releases to download, e.g. zi ice from"gh-r" as"program" bpick"*Darwin*"; zi load docker/compose. Does not work with snippets.
depth	Pass --depth to git. I.e., limit how much history to download. Does not work with snippets.
cloneopts	Pass the contents of cloneopts to git clone. Defaults to --recursive. I.e., change cloning options. Pass empty ice to disable recursive cloning. Does not work with snippets.
pullopts	Pass the contents of pullopts to git pull used when updating plugins. Does not work with snippets.
svn	Use Subversion for downloading snippets. GitHub supports the SVN protocol, which allows cloning of subdirectories as snippets, e.g. zi ice svn; zi snippet OMZP::git. Other ice pick can be used to select a file to the source (default are: *.plugin.zsh, init.zsh, *.zsh-theme). Does not work with plugins.

Selection of files (source '…')

Ice-modifier	Description
pick	Select the file to source, or the file to set as a command, when using snippet --command or the ice as"program". More below 4.
src	Specify an additional file to source after the main file or after setting up command via as"program". It is not a pattern but a plain filename.
multisrc	Allows specifying multiple files for sourcing, enumerated with spaces as the separators. More below 5.

Conditional loading

Ice-modifier	Description
wait	Postpone loading a plugin or snippet. For wait'1', loading is done 1 second after the prompt. 6.
load	A condition to check which should cause the plugin to load. 7.
unload	A condition to check to cause the plugin to unload. More below 8.
cloneonly	Don't load the plugin/snippet, only download it.
if	Load plugin/snippet only when a given condition is true. Example: 9.
has	Load plugin or snippet only when given command is available (in $PATH), e.g. zi ice has'git' ….
subscribe	Postpone loading of a plugin or snippet until the given file(s) get updated, e.g. subscribe'{~/files-*,/tmp/files-*}'.
trigger-load	Creates a function that loads the associated plugin/snippet, with an option. More below 10.

Plugin output

Ice-modifier	Description
silent	Mute plugin's or snippet's stderr & stdout. Also, skip the loaded … message under the prompt for wait, etc. loaded plugins, and completion-installation messages.
lucid	Skip loaded … message under prompt for wait, etc. loaded plugins (a subset of silent).
notify	Output given message under-prompt after successfully loading a plugin/snippet. In case of problems with the loading, output a warning message and the return code. If starts with ! it will then always output the given message. Hint: if the message is empty, then it will just notify about problems.

Completions

Ice-modifier	Description
blockf	Disallow plugin to modify fpath. Useful when a plugin wants to provide completions traditionally. Manage completions using Zi and block the plugins to expose them.
nocompletions	Skip plugin completions detection and installation. Completions can be installed anytime using: zi creinstall {plugin-name}.

Command execution after cloning, updating or loading

Ice-modifier	Description
mv	Move file after cloning or update (only for new commits). Example: mv "fzf-* -> fzf". It uses -> as a separator for old and new file names. Also works with snippets.
cp	Copy file after cloning or update (only for new commits). Example: cp "docker-c* -> dcompose". Ran after mv.
atclone	Run command after cloning, within plugin's directory, e.g. zi ice atclone"echo cloned". Ran also after downloading the snippet.
atpull	Run command after updating (only for new commits), within the plugin's directory. If starts with "!" then the command will be run before mv & cp ices and before git pull or svn update. Otherwise is run after mv & cp ices. Use the atpull'%atclone' to repeat atclone ice-modifier.
atinit	Run command after directory setup (cloning, checking, etc.) of the plugin/snippet before loading it.
atload	Run the given command within the plugin's directory after loading. Can be used with snippets. Passed code can be preceded with !, to be investigated (when using load, not light).
run-atpull	Always run the atpull hook (when updating), not exclusively for new commits.
nocd	Don't switch the current directory to the plugin's directory when evaluating the above ice-modifiers atinit'…', atload'…', etc.
make	Run the make command after cloning or updating and executing the mv, cp, atpull, atclone ice-modifiers. Can obtain argument, e.g. make"install PREFIX=/opt". If the value starts with ! then make is run before atclone and atpull ice-modifiers, e.g. make'!'.
countdown	Causes an interruptive (Ctrl-C) countdown 5…4…3…2…1…0 to be displayed before executing atclone'…', atpull'…' and make ices-modifiers.
reset	Invokes git reset --hard HEAD for plugins or svn revert for SVN snippets before pulling any new changes. This way git or svn will not report conflicts if some changes were done by e.g.: atclone'…' ice-modifier. For file snippets and gh-r plugins, it invokes rm -rf *.

Sticky-Emulation Of other shells

Ice-modifier	Description
sh, !sh	Source the plugin's (or snippet's) script with sh emulation so that also all functions declared within the file will get a sticky emulation assigned and invoked with the sh emulation set-up. The !sh version switches additional options that are rather not important from the portability perspective.
bash, !bash	The same as sh, but with the SH_GLOB option disabled, for "Bash" regular expressions to work.
ksh, !ksh	The same as sh, but emulating the ksh shell.
csh, !csh	The same as sh, but emulating the csh shell.

Footnotes

1. The third possible value is as"null" – a shorthand for pick"/dev/null" nocompletions – i.e.: it disables the default script-file sourcing and also the installation of completions. ↩

2. In summary, wrap allows to extend the investigating beyond the moment of loading of a plugin. An example use is to wrap a precmd function of a prompt (like _p9k_precmd() of powerlevel10k) or other plugins that postpones its initialization till the first prompt (like e.g.: zsh-autosuggestions). Does not work with snippets. ↩

3. If it has no value, then it works in the auto mode – it automatically extracts all files of known archive extensions IF they aren't located deeper than in a sub-directory (this is to prevent extraction of some helper archive files, typically located somewhere deeper in the tree). If no such files will be found, then it extracts all found files of known type – the type is being read by the file Unix command. If not empty, then takes the names of the files to extract. Refer to the Wiki page for further information. ↩

4. This pattern will alphabetically match and choose the first file e.g: zi ice pick"*.plugin.zsh"; zi load …. ↩

5. Example: multisrc'misc.zsh grep.zsh' and also using brace-expansion syntax: multisrc'{misc,grep}.zsh' also supports patterns. ↩

6. For wait'[[ … ]]', wait'(( … ))', loading is done when given condition is meet. For wait'!…', the prompt is reset after load. Zsh can start 80% (i.e.: 5x) faster thanks to postponed loading. Fact: when wait is used without a value, it works as wait'0'. ↩

7. It will load once, the condition can be still true, but will not trigger the second load, unless the plugin is unloaded earlier, see unload. E.g.: load'[[ $PWD = */github* ]]'. ↩

8. It will unload once, then only if loaded again e.g: unload'[[ $PWD != */github* ]]'. ↩

9. Example: zi ice if'[[ -n "$commands[otool]" ]]'; zi load … or zi ice if'[[ $OSTYPE = darwin* ]]'; zi load …. ↩

10. To use the option, precede the ice content with ! to automatically forward the call afterward, to a command of the same name as the function. Can obtain multiple functions to create – separate with ;. ↩