☑️ 一般概述

此概览包括以下内容：

1. Oh-My-Zsh & Prezto
2. Completions
3. Turbo mode
4. Ice modifiers

加载插件和片段

zi load z-shell/H-S-MW
zi light zsh-users/zsh-syntax-highlighting

上面的命令显示了两种加载基本插件的方式。 If you want to source local or remote files (using a direct URL), you can do so with a snippet.

zi snippet <URL>

Such lines should be added to .zshrc. Snippets are cached locally, use the -f option to download a fresh version of a snippet, or zi update {URL}. Use zi update --all to update all snippets and plugins.

Using load causes reporting to be enabled – you can track what the plugin does, view the information with zi report {plugin-name}, and then also unload the plugin with zi unload {plugin-name}.

Using light is a faster loading without tracking and reporting about the plugin but also withdrawing the ability to unload it.

Using load or light:

zi load  <repo/plugin> # Load with reporting/investigating.
zi light <repo/plugin> # Load without reporting/investigating.

带着跟踪报告加载 history-search-multi-word 插件：

zi load z-shell/H-S-MW

不带跟踪报告加载两个普通插件：

zi light zsh-users/zsh-autosuggestions
zi light z-shell/F-Sy-H

片段:

zi snippet https://gist.githubusercontent.com/hightemp/5071909/raw/

备注

In turbo mode loading, the slowdown by plugin tracking is done in the background and does not affect the user experience, i.e., loading with zi light and zi load has the same effect.

Oh-My-Zsh, Prezto

To load Oh-My-Zsh and Prezto plugins, use the snippet feature. Snippets are single files downloaded by curl, wget, etc., automatic detection of the download tool is being performed, directly from the URL:

zi snippet 'https://github.com/robbyrussell/oh-my-zsh/raw/master/plugins/git/git.plugin.zsh'
zi snippet 'https://github.com/sorin-ionescu/prezto/blob/master/modules/helper/init.zsh'

Also, for Oh-My-Zsh and Prezto, you can use OMZ:: and PZT:: shorthands:

zi snippet OMZ::plugins/git/git.plugin.zsh
zi snippet PZT::modules/helper/init.zsh

此外，GitHub 支持通过 Subversion 协议加载片段。 This allows loading snippets that are multi-file (for example, a Prezto module can consist of two or more files, e.g. init.zsh and alias.zsh).

Default files that will be sourced are: *.plugin.zsh, init.zsh, *.zsh-theme:

指向目录的URL：

zi ice svn
zi snippet PZT::modules/docker

Snippet 和性能

Using curl, wget, etc. along with Subversion allows us to almost completely avoid code dedicated to Oh-My-Zsh and Prezto, and also to other frameworks. 它提供了更好的性能，因为它对内存的占用很低，加载时间更短。

Ice 修饰符

The command zi ice provides ice modifiers for the single Zi command, i.e., zi ice <some-ice-modifier>; zi load some/plugin, after loading some/plugin the ice-modifier has to be set again.

“冰”是一种添加物，例如添加到饮料或咖啡中 —— 在 Zi 里，冰修饰符将是下一条 Zi 命令的添加物。 “冰”也是会融化的东西，所以它不会留存很久 —— 在 Zi 里，这意味着它的效果只能作用于一条命令。

Using one other ice modifier "pick" users can explicitly select the file to source:

zi ice svn pick"init.zsh"
zi snippet PZT::modules/git

The content of the ice-modifier is simply put into "…", '…', $'…'. No need for ":" after the ice-modifier name (although it's allowed: as the equal sign =, e.g. pick="init.zsh" or pick=init.zsh).

This way editors like vim and emacs and also zsh-users/zsh-syntax-highlighting and z-shell/F-Sy-H will highlight the contents of ice-modifiers.

关于 as"program"

A plugin might not be a file for sourcing, but a command to be added to $PATH. To obtain this effect, use ice-modifier as with value program (or an alias value command).

zi ice as"program" cp"httpstat.sh -> httpstat" pick"httpstat"
zi light b4b4r07/httpstat

The above command will add plugin directory to $PATH, copy file httpstat.sh into httpstat and add execution rights (+x) to the file selected with pick, i.e. to httpstat. Another ice-mod exists, mv, which works like cp but moves a file instead of copying it. mv is run before cp.

提示

The cp and mv ices (and also some other ones, like atclone) are being run when the plugin or snippet is being installed. To test them again first delete the plugin or snippet (example: zi delete PZT::modules/osx).

Ice 修饰符: atpull'…'

Copying file is safe for doing later updates – original files of the repository are unmodified and Git will report no conflicts. However, mv also can be used, if a proper atpull, an ice-modifier ran at update of the plugin:

zi ice as"program" mv"httpstat.sh -> httpstat" \
  pick"httpstat" atpull'!git reset --hard'
zi light b4b4r07/httpstat

If atpull starts with an exclamation mark, then it will be run before git pull, and before mv. Nevertheless, atpull, mv, and cp are run only if new commits are to be fetched.

So in summary, when the user runs zi update b4b4r07/httpstat to update this plugin, and there are new commits, what happens first is that git reset --hard is run – and it restores original httpstat.sh, then git pull is ran and it downloads new commits (doing fast-forward), then mv is running again so that the command is httpstat not httpstat.sh.

This way the mv ice can be used to induce permanent changes into the plugin's contents without blocking the ability to update it with git or with subversion in the case of snippets.

信息

For exclamation marks to not be expanded by Zsh an interactive session, use '…' not "…" to enclose contents of atpull ice-modifier.

Ice 修饰符: subscribe'…'

Ice修饰符延迟加载加载一个插件，同时检查给定文件的修改时间。当给定文件发生变化时，它就会触发插件或片段的加载。

Copy and paste the example below to the terminal or add it to the .zshrc file and reload the shell with exec zsh.

zi ice subscribe'{~/files-*,/tmp/files-*}' id-as'z-sub' lucid \
  atload'+zi-message "{profile}I have been loaded{nl}\
  {auto}\`Zi Rocks ♥\`"' notify"Yes that is cool ♥ "
zi load z-shell/0

按照上面订阅的内容更新文件，测试 Ice 修饰符：

touch ~/files-1

该插件或片段将随着文件的更新而被 source 。

片段 as'…' program

Commands can also be added to $PATH using snippets:

zi ice mv"httpstat.sh -> httpstat" \
  pick"httpstat" as"program"
zi snippet https://github.com/b4b4r07/httpstat/blob/master/httpstat.sh

提示

Snippets also support atpull, e.g. atpull'!svn revert'. There’s also an atinit ice-modifier, executed before each loading of plugin or snippet.

片段 as'…' completion

By using the as'…' ice modifier with the value completion you can point the snippet subcommand directly to a completion file:

zi ice as"completion"
zi snippet https://github.com/docker/cli/blob/master/contrib/completion/zsh/_docker

补全管理

Zi允许在每个插件中禁用和启用每个补全。 尝试安装一个提供补全的热门插件：

zi ice blockf
zi light zsh-users/zsh-completions

The first command, the blockf ice, will block the traditional method of adding completions. Zi uses this method, based on symlinks instead of adding several directories to $fpath. Zi will automatically install completions of a newly downloaded plugin.

要卸载或安装补全：

卸载：

zi cuninstall zsh-users/zsh-completions

安装：

zi creinstall zsh-users/zsh-completions

列出可用补全

To see what completions all plugins provide, in tabular formatting and with the name of each plugin:

zi clist

This command is adapted for plugins like zsh-users/zsh-completions, which provide many completions – listing will have 3 completions per line, and a smaller number of terminal pages can be occupied like this:

To show more completions per line by providing an argument to clist, e.g.: zi clist 6, will show:

启用/禁用 - 补全

可以禁用补全功能，并使用其他补全功能，例如 Zsh 的内置补全。 The commands are very basic, they only need completion name:

Disable cmake completion:

zi cdisable cmake

Enable cmake completion:

zi cenable cmake

Command zi csearch will search all plugin directories for available completions:

对子目录的 subversion

In general, to use subdirectories of Github projects as snippets add /trunk/{path-to-dir} to the URL:

zi ice svn
zi snippet https://github.com/zsh-users/zsh-completions/trunk/src

提示

For Oh-My-Zsh and Prezto, the OMZ:: and PZT:: prefixes work without the need to add the /trunk/ infix, however, the path should point to a directory, not to a file.

zi ice svn
zi snippet PZT::modules/docker

Turbo Mode (Zsh >= 5.3)

The ice-modifier wait allows the user to postpone the loading of a plugin to the moment when the processing of .zshrc is finished and the first prompt is shown.

它就像 Windows 的逻辑 —— 启动过程中，它首先显示一个桌面，然后在后台继续加载数据。 这种做法有缺点，但肯定比 10 分钟的空白屏幕要好。 但在 Zi 中，这种方法没有任何缺点 —— 没有延迟、冻结等问题。—— 在加载插件的过程中，命令行仍然完全可用，无论以这种方法加载了多少插件。

信息

Turbo will speed up Zsh startup by 50%–80%. 例如，从 200 ms 加速到 40 ms。

备注

需要 Zsh 5.3 及以上的版本。

To use turbo mode add wait ice to the target plugin in one of the following ways:

PS1="READY > "
zi ice wait'!0'
zi load halfo/lambda-mod-zsh-theme

This sets plugin halfo/lambda-mod-zsh-theme to be loaded 0 seconds after .zshrc. It will fire up after c.a. 1 ms of showing the basic prompt READY >.

You probably won't load the prompt in such a way, however, it is a good example in which turbo mode can be observed. The exclamation mark causes Zi to reset the prompt after loading the plugin – commonly needed for themes. The same with Prezto prompts, with a longer delay:

zi ice svn silent wait'!1' atload'prompt smiley'
zi snippet PZT::modules/prompt

Using zsh-users/zsh-autosuggestions without any drawbacks:

zi ice wait lucid atload'!_zsh_autosuggest_start'
zi light zsh-users/zsh-autosuggestions

Turbo mode is the key to the performance

Turbo 模式可以异步地加载，这在插件数量增加时作用重大。 Usually used as zi ice wait'<SECONDS>'.

备注

The wait is equivalent to wait'0'.

zi ice wait
zi load z-shell/H-S-MW

2秒后加载：

zi ice wait'2'
zi load z-shell/H-S-MW

Also can be used in light and snippet:

zi ice wait
zi snippet https://gist.githubusercontent.com/hightemp/5071909/raw/

Turbo mode & lucid

Turbo and lucid are the most used options because turbo mode is verbose and may require an option for quiet and this can be achieved with the lucid.

zi ice wait lucid
zi load z-shell/H-S-MW

带有复杂命令行提示符的 Turbo 模式

For some, mostly advanced themes the initialization of the prompt is being done in a precmd-hook, i.e.; in a function that gets called before each prompt. The hook is installed by the add-zsh-hook Zsh function by adding its name to the $precmd_functions array.

To make the prompt fully initialized after turbo mode loading in the middle of the prompt the same situation as with the zsh-autosuggestions plugin, the hook should be called from atload'…' ice.

First, find the name of the hook function by examining the $precmd_functions array. For example, for the robobenklein/zinc theme, they'll be two functions: prompt_zinc_setup and prompt_zinc_precmd:

print $precmd_functions

_zsh_autosuggest_start prompt_zinc_setup prompt_zinc_precmd

Then, add them to the ice list in the atload'…' ice:

zi ice wait'!' lucid nocd \
  atload'!prompt_zinc_setup; prompt_zinc_precmd'
zi load robobenklein/zinc

The exclamation mark in atload'!…' is to track the functions allowing the plugin to be unloaded, as described here. 它可能对接下来描述的命令行多重提示符设置很有用。

Turbo 方式的总结

Autosuggestions use the precmd hook, which is being called right after processing .zshrc – precmd hooks are being called right before displaying each prompt.

Turbo mode with the empty wait ice will postpone the loading 1 ms after that, so precmd will not be called at that first prompt. 这将使自动提示在第一行提示符无法支持这些命令。

However the given atload'…' ice-modifier fixes this, it calls the same function that precmd would, right after loading autosuggestions, resulting in the same behavior of the plugin.

The ice called lucid causes the under-prompt message saying Loaded zsh-users/zsh-autosuggestions that normally appears for every Turbo-loaded plugin to not show.

Automatic condition based - load & unload

Ices load and unload allow defining when you want plugins active or inactive:

Load when in ~/tmp:

zi ice load'![[ $PWD = */tmp* ]]' unload'![[ $PWD != */tmp* ]]' \
  atload'!promptinit; prompt sprint3'
zi load z-shell/zprompts

Load when NOT in ~/tmp:

zi ice load'![[ $PWD != */tmp* ]]' unload'![[ $PWD = */tmp* ]]'
zi load russjohnson/angry-fly-zsh

Two prompts, each active in different directories. This technique can be used to have plugin-sets, e.g. by defining parameter $PLUGINS with possible values like cpp, web, admin and by setting load / unload conditions to activate different plugins on cpp, on web, etc.

备注

• The difference with wait is that load / unload are constantly active, not only till the first activation. Note that for the unloading of a plugin to work the plugin needs to be loaded with tracking, so zi load … and not zi light ….

Tracking causes a slight slowdown, however, this doesn’t influence Zsh startup time when using turbo mode.

A Glance at the prompts

提示

See: multiple prompts or more information. It contains more real-world examples of a multi-prompt setup, which is close to what the author uses in his setup.

This is powerlevel10k, pure, starship sample:

Load powerlevel10k theme:

~/.zshrc

zi ice depth"1"
zi light romkatv/powerlevel10k

Load pure theme:

will pick the async.zsh library and will source it.

~/.zshrc

zi ice pick"async.zsh" src"pure.zsh"
zi light sindresorhus/pure

Load starship theme:

• pick starship binary as a command, from the GitHub release.
• setup starship using atclone and create init.zsh and completion.
• the atpull'…' behavior same as atclone'…' and but is used when running zi update.
• src will source init.zsh.

~/.zshrc

zi ice as"command" from"gh-r" \
  atclone"./starship init zsh > init.zsh; ./starship completions zsh > _starship" \
  atpull"%atclone" src"init.zsh"
zi light starship/starship

Common use cases

Load the pure theme, with the zsh-async library that's bundled with it.

~/.zshrc

zi ice pick"async.zsh" src"pure.zsh"
zi light sindresorhus/pure

Binary release in the archive, from GitHub. After automatic unpacking, it provides the program "fzf".

~/.zshrc

zi ice from"gh-r" as"program"
zi light junegunn/fzf

One other binary release needs renaming from docker-compose-Linux-x86_64. This can be done by ice modifier: mv'{from} -> {to}'.

There are multiple packages per single version for OS X, Linux, and Windows – the ice-modifier bpick is utilized to select the Linux package – in this case - not required, Zi will grep operating system name and architecture automatically when there's no bpick.

~/.zshrc

zi ice from"gh-r" as"program" mv"docker* -> docker-compose" bpick"*linux*"
zi load docker/compose

Handle completions without loading any plugin, see the clist command. This one is to be run just once, in an interactive session.

~/.zshrc

zi creinstall %HOME/my_completions

If you are interested to try out more then check out the playground repository where users have uploaded the ~/.zshrc and other Zi configurations. Feel free to submit your ~/.zshrc configuration.

Additional examples: collection.