メインコンテンツまでスキップ

🧊 Ice 修飾子

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.

いくつかのice 修飾子はハイライト表示されており、クリックすると該当するWikiページに移動し、詳しい説明が表示されます。 特に明記されていない限り、与えられたiceはプラグインとスニペットの両方で機能すると考えていただいて結構です。

Ice effects

Ice 修飾子説明
asCan 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-asNickname a plugin or snippet, e.g. create a short handler for the long-URL snippet.
teleidEffective remote-ID (i.e.: URL, GitHub username/repo, package name, etc.).
compilePattern (possible {…} expansion, like {a/*,b*}) to select additional files to compile, e.g. compile"(pure | async).zsh"forsindresorhus/pure.
nocompileDon'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).
serviceMake the following plugin or snippet a service, which will run in the background, and only in a single Zshell instance. See #zservice topic.
reset-promptReset 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 !.
bindmapTo 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.
trackbindsShadow 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.
wrapTakes 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
aliasesLoad the plugin with the aliases mechanism enabled. Use plugins that define and use aliases in their scripts.
light-modeLoad 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
extractPerforms archive extraction supporting multiple formats like zip, tar.gz, etc., and OS X dmg images. 3
substSubstitute the given string into another string when sourcing the plugin script, e.g.: zi subst'autoload → autoload -Uz' ….
autoloadAutoload 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 修飾子説明
protoChange protocol to git,ftp,ftps,ssh, rsync, etc. The default is https. Does not work with snippets.
fromClone 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.
verUsed 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.
bpickUsed 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.
depthPass --depth to git. I.e., limit how much history to download. Does not work with snippets.
cloneoptsPass 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.
pulloptsPass the contents of pullopts to git pull used when updating plugins. Does not work with snippets.
svnUse 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 修飾子説明
pickSelect the file to source, or the file to set as a command, when using snippet --command or the ice as"program". More below 4.
srcSpecify 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.
multisrcAllows specifying multiple files for sourcing, enumerated with spaces as the separators. More below 5.

Conditional loading

Ice 修飾子説明
waitPostpone loading a plugin or snippet. For wait'1', loading is done 1 second after the prompt. 6.
loadA condition to check which should cause the plugin to load. 7.
unloadA condition to check to cause the plugin to unload. More below 8.
cloneonlyDon't load the plugin/snippet, only download it.
ifLoad plugin/snippet only when a given condition is true. Example: 9.
hasLoad plugin or snippet only when given command is available (in $PATH), e.g. zi ice has'git' ….
subscribePostpone loading of a plugin or snippet until the given file(s) get updated, e.g. subscribe'{~/files-*,/tmp/files-*}'.
trigger-loadCreates a function that loads the associated plugin/snippet, with an option. More below 10.

Plugin output

Ice 修飾子説明
silentMute plugin's or snippet's stderr & stdout. Also, skip the loaded … message under the prompt for wait, etc. loaded plugins, and completion-installation messages.
lucidSkip loaded … message under prompt for wait, etc. loaded plugins (a subset of silent).
notifyOutput 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 修飾子説明
blockfDisallow plugin to modify fpath. Useful when a plugin wants to provide completions traditionally. Manage completions using Zi and block the plugins to expose them.
nocompletionsSkip plugin completions detection and installation. Completions can be installed anytime using: zi creinstall {plugin-name}.

Command execution after cloning, updating or loading

Ice 修飾子説明
mvMove 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.
cpCopy file after cloning or update (only for new commits). Example: cp "docker-c* -> dcompose". Ran after mv.
atcloneRun command after cloning, within plugin's directory, e.g. zi ice atclone"echo cloned". Ran also after downloading the snippet.
atpullRun 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.
atinitRun command after directory setup (cloning, checking, etc.) of the plugin/snippet before loading it.
atloadRun 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-atpullAlways run the atpull hook (when updating), not exclusively for new commits.
nocdDon't switch the current directory to the plugin's directory when evaluating the above ice-modifiers atinit'…', atload'…', etc.
makeRun 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'!'.
countdownCauses an interruptive (Ctrl-C) countdown 5…4…3…2…1…0 to be displayed before executing atclone'…', atpull'…' and make ices-modifiers.
resetInvokes 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 修飾子説明
sh, !shSource 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, !bashThe same as sh, but with the SH_GLOB option disabled, for "Bash" regular expressions to work.
ksh, !kshThe same as sh, but emulating the ksh shell.
csh, !cshThe 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 ;.