Introduction - Zinit Wiki (2024)

In the document below you’ll find out how to:

• use Oh My Zsh and Prezto,

• manage completions,

• use the Turbo mode,

• use the ice-mods like as"program",

and much more.

Basic Plugin Loading#

zinit load zdharma-continuum/history-search-multi-wordzinit light zsh-users/zsh-syntax-highlighting

Above commands show two ways of basic plugin loading. load causes reporting tobe enabled – you can track what plugin does, view the information with zinitreport {plugin-spec} and then also unload the plugin with zinit unload{plugin-spec}. light is a significantly faster loading without tracking andreporting, by using which user resigns of the ability to view the plugin reportand to unload it.

Oh My Zsh, Prezto#

To load Oh My Zsh and Prezto plugins, use snippet feature. Snippets are singlefiles downloaded by curl, wget, etc. (an automatic detection of the downloadtool is being performed) directly from URL. For example:

zinit snippet 'https://github.com/robbyrussell/oh-my-zsh/raw/master/plugins/git/git.plugin.zsh'zinit 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:

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

Moreover, snippets support Subversion protocol, supported also by Github. Thisallows to load snippets that are multi-file (for example, a Prezto module canconsist of two or more files, e.g. init.zsh and alias.zsh). Default filesthat will be sourced are: *.plugin.zsh, init.zsh, *.zsh-theme:

# URL points to directoryzinit ice svnzinit snippet PZT::modules/docker

Snippets and Performance#

Using curl, wget, etc. along with Subversion allows to almost completelyavoid code dedicated to Oh My Zsh and Prezto, and also to other frameworks. Thisgives profits in performance of Zinit, it is really fast and also compact(causing low memory footprint and short loading time).

Some Ice-Modifiers#

The command zinit ice provides ice-modifiers for single next command (seethe README subsectionice-modifiers). Thelogic is that "ice" is something something that’s added (e.g. to a drink or acoffee) – and in the Zinit sense this means that ice is a modifier added tothe next Zinit command, and also something that melts (so it doesn’t lastlong) – and in the Zinit use it means that the modifier lasts for only singlenext Zinit command. Using one other ice-modifier "pick" user canexplicitly select the file to source:

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

Content of ice-modifier is simply put into "…", '…', or $'…'. Noneed for ":" after ice-mod name (although it's allowed, so as the equal sign=, so e.g. pick="init.zsh" or pick=init.zsh are being correctlyrecognized) . This way editors like vim and emacs and alsozsh-users/zsh-syntax-highlighting and zdharma-continuum/fast-syntax-highlighting willhighlight 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 aliasvalue command).

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

Above command will add plugin directory to $PATH, copy file httpstat.sh intohttpstat and add execution rights (+x) to the file selected with pick,i.e. to httpstat. Other ice-mod exists, mv, which works like cp butmoves a file instead of copying it. mv is ran before cp.

atpull"…"#

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

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

If atpull starts with exclamation mark, then it will be run before git pull,and before mv. Nevertheless, atpull, mv, cp are ran only if newcommits are to be fetched. So in summary, when user runs zinit updateb4b4r07/httpstat to update this plugin, and there are new commits, what happensfirst is that git reset --hard is ran – and it restores originalhttpstat.sh, then git pull is ran and it downloads new commits (doingfast-forward), then mv is ran again so that the command is httpstat nothttpstat.sh. This way the mv ice can be used to induce a permanent changesinto the plugin's contents without blocking the ability to update it with git(or with subversion in case of snippets, more on this below at**).

Snippets-Commands#

Commands can also be added to $PATH using snippets. For example:

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

(**) Snippets also support atpull ice-mod, so it’s possible to do e.g.atpull'!svn revert'. There’s also atinit ice-mod, executed before eachloading of plugin or snippet.

Snippets-Completions#

By using the as'' ice-mod with value completion you can point the snippetsubcommand directly to a completion file, e.g.:

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

Completion Management#

Zinit allows to disable and enable each completion in every plugin. Tryinstalling a popular plugin that provides completions:

zinit ice blockfzinit light zsh-users/zsh-completions

First command (the blockf ice) will block the traditional method of addingcompletions. Zinit uses own method (based on symlinks instead of adding anumber of directories to $fpath). Zinit will automatically installcompletions of a newly downloaded plugin. To uninstall the completions andinstall them again, you would use:

zinit cuninstall zsh-users/zsh-completions # uninstallzinit creinstall zsh-users/zsh-completions # install

Listing Completions#

To see what completions all plugins provide, in tabular formatting and withname of each plugin, use:

zi clist

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

...atach, bitcoin-cli, bower zsh-users/zsh-completionsbundle, caffeinate, cap zsh-users/zsh-completionscask, cf, chattr zsh-users/zsh-completions...

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

...bundle, caffeinate, cap, cask, cf, chattr zsh-users/zsh-completionscheat, choc, cmake, coffee, column, composer zsh-users/zsh-completionsconsole, dad, debuild, dget, dhcpcd, diana zsh-users/zsh-completions...

Enabling and Disabling Completions#

Completions can be disabled, so that e.g. original Zsh completion will be used.The commands are very basic, they only need completion name:

$ zi cdisable cmakeDisabled cmake completion belonging to zsh-users/zsh-completions$ zi cenable cmakeEnabled cmake completion belonging to zsh-users/zsh-completions

That’s all on completions. There’s one more command, zinit csearch, thatwill search all plugin directories for available completions, and show ifthey are installed:

This sums up to complete control over completions.

Subversion for Subdirectories#

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

zinit ice svnzinit 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):zinit ice svn; zinit snippet PZT::modules/docker

Snippets too have completions installed by default, like plugins.

Turbo Mode (Zsh >= 5.3)#

The ice-mod wait allows the user postponing loading of a plugin to the momentwhen the processing of .zshrc is finished and the first prompt is being shown.It is like Windows – during startup, it shows desktop even though it still loadsdata in background. This has drawbacks, but is for sure better than blank screenfor 10 minutes. And here, in Zinit, there are no drawbacks of this approach – nolags, freezes, etc. –the command line is fully usable while the plugins arebeing loaded, for any number of plugins.

Zsh 5.3 or greater is required. To use this Turbo mode add wait ice to thetarget plugin in one of following ways:

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

This sets plugin halfo/lambda-mod-zsh-theme to be loaded 0 seconds afterzshrc. It will fire up after c.a. 1 ms of showing of the basic prompt READY >.You probably won't load the prompt in such a way, however it is a good examplein which Turbo can be directly observed.

The exclamation mark causes Zinit to reset the prompt after loading plugin – itis needed for themes. The same with Prezto prompts, with a longer delay:

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

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

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

Explanation: Autosuggestions uses precmd hook, which is being called rightafter processing zshrc – precmd hooks are being called right beforedisplaying each prompt. Turbo with the empty wait ice will postpone theloading 1 ms after that, so precmd will not be called at that first prompt.This makes autosuggestions inactive at the first prompt. However the givenatload ice-mod fixes this, it calls the same function that precmd would,right after loading autosuggestions, resulting in exactly the same behavior ofthe plugin.

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

A Quick Glance At The For-Syntax#

This introduction is based on the classic, two-command syntax (zinit ice …;zinit load/light/snippet …) of Zinit. However, there's also available arecently added so-called for-syntax. It is a right moment to take a glance atit, by rewriting the above autosuggestions invocation using it:

zinit wait lucid atload'_zsh_autosuggest_start' light-mode for \ zsh-users/zsh-autosuggestions

The syntax is a more concise one. The single command will work exactly the sameas the previous classic-syntax invocation. It also allows solving some typicalproblems when using Zinit, like providing common/default ices for a set ofplugins or sourcing multiplefiles. For moreinformation refer to the page dedicated to the new syntax(here).

Turbo-Loading Sophisticated Prompts#

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

To make the prompt fully initialized after Turbo loading in the middle of theprompt (the same situation as with the zsh-autosuggestions plugin), the hookshould be called from atload'' ice.

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

root@sg > ~ > print $precmd_functions < ✔ < 22:21:33_zsh_autosuggest_start prompt_zinc_setup prompt_zinc_precmd

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

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

The exclamation mark in atload'!…' is to track the functions allowing theplugin to be unloaded, as described here. Itmight be useful for the multi-prompt setup described next.

Automatic Load/Unload on Condition#

Ices load and unload allow to define when you want plugins active orunactive. For example:

# Load when in ~/tmpzinit ice load'![[ $PWD = */tmp* ]]' unload'![[ $PWD != */tmp* ]]' \ atload"!promptinit; prompt sprint3"zinit load psprint/zprompts# Load when NOT in ~/tmpzinit ice load'![[ $PWD != */tmp* ]]' unload'![[ $PWD = */tmp* ]]'zinit load russjohnson/angry-fly-zsh

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

Note that for unloading of a plugin to work the plugin needs to be loaded withtracking (so zinit load …, not zinit light …). Tracking causesslight slowdown, however this doesn’t influence Zsh startup time when usingTurbo mode.

See also Wiki on multiple prompts. It contains amore real-world examples of a multi-prompt setup, which is being close to whatthe author uses in own setup.