✨ The "For" Syntax

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

It allows providing common/default ice-modifiers 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 The "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

Syntax	Description
wait	Load 0 seconds (about 5 ms exactly) after prompt (turbo mode).
lucid	Silence the under-prompt messages ("Loaded {name of the plugin}").
light-mode	Load 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.
zicompinit	Equals to autoload compinit; compinit.
zicdreplay	Execute compdef … calls by plugins. More below 2.

Oh-My-Zsh, turbo Oh-My-Zsh and the The "For" syntax

Without turbo mode and The "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 The "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.

zi-turbo '…' for …

The zi-turbo is a function to simplify wait:

zi-turbo() {
  zi depth'3' lucid ${1/#[0-9][a-c]/wait"${1}"} "${@:2}"
}

Then use the for syntax in the imposed loading order:

zi-turbo '0a' for \
  OMZL::git.zsh \
  OMZL::compfix.zsh \
  OMZL::functions.zsh \

zi-turbo '0b' for \
  OMZL::prompt_info_functions.zsh OMZL::spectrum.zsh \
  OMZL::clipboard.zsh OMZL::termsupport.zsh OMZL::directories.zsh

zi-turbo '0c' for \
  OMZP::sudo OMZP::encode64 \
    atload"unalias grv g" OMZP::git \
  OMZP::gcloud OMZP::nvm OMZP::gem OMZP::rust

zi-turbo '1a' for \
  MichaelAquilina/zsh-you-should-use

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.

Footnotes

1. 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. ↩

2. 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. ↩