Skip to main content

✨ The "For" Syntax

The for syntax is the most popular, more concise, and more optimized. The single command will work the same as the classic-syntax invocation.

It allows providing common/default ices for a set of plugins or to source multiple files with the ices: src, pick, multisrc.

tip

To find more information about anything use search or just CTRL+K.

zi light-mode for \  zsh-users/zsh-autosuggestions \  z-shell/F-Sy-H \  z-shell/H-S-MW \    pick"async.zsh" src"pure.zsh" \      sindresorhus/pure

It is best presented by real-world examples:

zi wait"3" lucid for as"null" \  sbin Fakerr/git-recall \  sbin paulirish/git-open \  sbin paulirish/git-recent \  sbin davidosomething/git-my \  make"PREFIX=$ZPFX install" iwata/git-now \  make"PREFIX=$ZPFX" tj/git-extras

The above single command installs 6 plugins (git extension packages), with the base ices as"null" wait"3" lucid that are common to all of the plugins and 6 plugin-specific add-on ice-modifiers.

Load a few useful binary packages from the GitHub releases, utils:

zi for as"null" wait"2" lucid from"gh-r" \  mv"exa* -> exa" sbin ogham/exa \  mv"fd* -> fd" sbin"fd/fd" @sharkdp/fd \  sbin"fzf" junegunn/fzf
note
  • sbin'…' is an ice added by the bin-gem-node annex, it provides the command to the command line without altering $PATH.
  • If the name of the command is the same as the name of the plugin, the ice contents can be skipped.

Turbo load some plugins, without any plugin-specific ices:

zi wait lucid for \  hlissner/zsh-autopair \  urbainvaes/fzf-marks

Load two Oh-My-Zsh files as snippets, in turbo mode:

zi wait lucid for \    OMZ::lib/git.zsh \  atload"unalias grv" \    OMZ::plugins/git/git.plugin.zsh

Popular plugin set with turbo and for:

zi wait lucid light-mode for \  atinit"zicompinit; zicdreplay" \    z-shell/F-Sy-H \  atload"_zsh_autosuggest_start" \    zsh-users/zsh-autosuggestions \  blockf atpull'zi creinstall -q .' \    zsh-users/zsh-completions
SyntaxDescription
waitLoad 0 seconds (about 5 ms exactly) after prompt (turbo mode).
lucidSilence the under-prompt messages ("Loaded {name of the plugin}").
light-modeLoad the plugin in light mode. 1.
atpull'…'Execute after updating the plugin – the command in the ice will install any new completions.
atinit'…'Execute code before loading plugin.
atload'…'Execute code after loading the plugin.
zicompinitEquals to autoload compinit; compinit.
zicdreplayExecute compdef … calls by plugins. More below 2.

Oh-My-Zsh, turbo Oh-My-Zsh and the for syntax​

Without turbo mode and for​

# A.setopt prompt_subst# B.zi snippet OMZL::git.zsh# C.zi ice atload"unalias grv"zi snippet OMZP::git# D.zi for OMZL::prompt_info_functions.zsh OMZT::gnzh# E.zi snippet OMZP::colored-man-pages# F.zi ice as"completion"zi snippet OMZP::docker/_docker# G.zi ice atinit"zicompinit; zicdreplay"zi light z-shell/F-Sy-H

With turbo mode and for​

# A.setopt prompt_subst# B, C.zi wait lucid for \  OMZL::git.zsh \  atload"unalias grv" \  OMZP::git# Provide a simple prompt till the theme loads to visualize the effect.PS1="READY >"# D.zi wait'!' lucid for \  OMZL::prompt_info_functions.zsh \  OMZT::gnzh# E, F, G.zi wait lucid for \    atinit"zicompinit; zicdreplay" \    z-shell/fast-syntax-highlighting \  OMZP::colored-man-pages \    as"completion" \  OMZP::docker/_docker
info

A - Most themes use this option.

B, C - OMZ themes use this library and some others use also the plugin. It provides many aliases – atload'…' showing how to disable some of them (e.g.: to use the program rgburke/grv).

D - Set OMZ theme. Loaded separately because the theme needs the ! passed to the wait ice to reset the prompt after loading the snippet in turbo mode.

E, F, G - Some plugins:

  1. syntax-highlighting, loaded possibly early for a better user experience).
  2. example functional plugin.
  3. docker completion.

The above setup loads everything after the prompt, because of the preceding wait ice. That is called turbo mode, which shortens Zsh startup time by 50%-80%, e.g. instead of 200 ms, it'll be getting your shell started up after 40 ms.

Try both setups on the daily basis to notice the difference. The features of Zi can do much more than this simple example.

Summary​

In general, turbo mode can be optionally enabled only for a subset of plugins or for all plugins.

Syntax-highlighting plugins, like F-Sy-H or zsh-syntax-highlighting, theoretically expect to be loaded last, even after the completion initialization as compinit function.

However, in practice, you just have to ensure that such plugin is loaded after plugins that are issuing compdef – which means completions that aren't using the underscore-starting function file; the completion initialization still has to be performed before the syntax-highlighting plugin, hence the atinit'…' ice, which will load compinit right before loading the plugin, the syntax-highlighting and suggestions plugins are loaded early for a better user experience.

  1. They were recorded and compinit can be called later. compinit provides the compdef function, so it must be run before issuing the taken-over compdefs with zicdreplay.↩
  2. Then the tracking of plugin, activity report gathering, accessible via the zi report {plugin-name} subcommand) is being disabled. Note that for turbo mode, the performance gains are almost 0, so in this mode, you can load all plugins with the tracking and the light-mode ice can be removed from the command.↩