New: You can request a feature when donating, even fancy or advanced ones get implemented this way. There are reports about what is being done with the money received.

The project undergoes a name change from Zplugin to Zinit.

Please report any observed issues.

Table of Contents generated with DocToc

• News
• Zinit
• Zinit Wiki
• Installation
  • Option 1 - Automatic Installation (Recommended)
  • Option 2 - Manual Installation
• Usage
  • Introduction
  • Example Usage
  • Ice Modifiers
  • Zinit Commands
  • Updating Zinit and Plugins
  • Using Oh My Zsh Themes
• Completions
  • Calling compinit Without Turbo Mode
  • Calling compinit With Turbo Mode
  • Ignoring Compdefs
  • Disabling System-Wide compinit Call (Ubuntu)
• Zinit Module
  • Motivation
  • Installation
  • Measuring Time of sources
  • Debugging
• Hints and Tips
  • Customizing Paths
  • Non-GitHub (Local) Plugins
  • Extending Git
  • Preinstalling Plugins
• Getting Help and Community

News

Here are the new features and updates added to zinit in the last 90 days.

• 21-01-2020

  • A few tips for the project rename following the field reports (the issues created by users):
    • the ZPLGM hash is now ZINIT,
    • the annexes are moved under zinit-zsh organization (it needs a logo, soon a poll about selecting one will start! you can submit your own proposal – just open an issue).

• 19-01-2020

  • The name has been changed to Zinit based on the results of the poll.
  • In general, you don't have to do anything after the name change.
  • Only a run of zinit update --all might be necessary.
  • You might also want to rename your zplugin calls in zshrc to zinit.
  • Zinit will reuse ~/.zplugin directory if it exists, otherwise it'll create ~/.zinit.

• 15-01-2020

  • There's a new function, zpextract, which unpacks the given file. It supports many formats (notably also dmg images) – if there's a format that's unsupported please don't hesitate to make a request for it to be added. A few facts:
    • the function is available only at the time of the plugin/snippet installation,
    • it's to be used within atclone and atpull ices,
    • it has an optional --move option which moves all the files from a subdirectory up one level,
    • one other option --norm prevents the archive from being deleted upon unpacking.
  • snippets now aren't re-downloaded unless they're newer on the HTTP server; use this with the --norm option of zpextract to prevent unnecessary updates; for example, the firefox-dev package uses this option for this purpose,
  • GitHub doesn't report proper Last-Modified HTTP server for the files in the repositories so the feature doesn't yet work with such files.

• 13-12-2019

  • The packages have been disconnected from NPM registry and now live only on Zsh Packages organization. Publishing to NPM isn't needed.

  • There are two interesting packages, any-gem and any-node. They allow to install any Gem(s) or Node module(s) locally in a newly created plugin directory. For example:

    zinit pack param='GEM -> rails' for any-gem
    zinit pack param='MOD -> doctoc' for any-node
    # To have the command in zshrc, add an id-as'' ice so that
    # Zinit knows that the package is already installed
    # (also: the Unicode arrow is allowed)
    zinit id-as=jekyll pack param='GEM → jekyll' for any-gem
    

    The binaries will be exposed without altering the PATH via shims (Bin-Gem-Node annex is needed). Shims are correctly removed when deleting a plugin with zinit delete ….

• 11-12-2019

  • Zinit now supports installing special-Zsh NPM packages! Bye-bye the long and complex ice-lists! Check out the Wiki for an introductory document on the feature.

• 25-11-2019

  • A new subcommand run that executes a command in the given plugin's directory. It has an -l option that will reuse the previously provided plugin. So that it's possible to do:

    zplg run my/plugin ls
    zplg run -l cat \*.plugin.zsh
    zplg run -l pwd
    

• 07-11-2019

  • Added a prefix-char: @ that can be used before plugins if their name collides with one of the ice-names. For example sharkdp/fd collides with the sh ice (which causes the plugin to be loaded with the POSIX sh emulation applied). To load it, do e.g.:

    zinit as"null" wait"2" lucid from"gh-r" for \
        mv"exa* -> exa" sbin"exa"  ogham/exa \
        mv"fd* -> fd" sbin"fd/fd"  @sharkdp/fd \
        sbin"fzf" junegunn/fzf-bin
    

    i.e.: precede the plugin name with @. Note: sbin'' is an ice added by the z-a-bin-gem-node annex, it provides the command to the command line without altering $PATH.

    See the Zinit Wiki for more information on the for-syntax.

• 06-11-2019

  • A new syntax, called for-syntax. Example:

     zinit as"program" atload'print Hi!' for \
         atinit'print First!' zdharma/null \
         atinit'print Second!' svn OMZ::plugins/git
    

    The output:

    First!
    Hi!
    Second!
    Hi!
    

    And also:

    % print -rl $path | egrep -i '(/git|null)'
    /root/.zinit/snippets/OMZ::plugins/git
    /root/.zinit/plugins/zdharma---null
    

    To load in light mode, use a new light-mode ice. More examples and information can be found on the Zinit Wiki.

• 03-11-2019

  • A new value for the as'' ice – null. Specifying as"null" is like specifying pick"/dev/null" nocompletions, i.e.: it disables the sourcing of the default script file of a plugin or snippet and also disables the installation of completions.

• 30-10-2019

  • A new ice trigger-load'' – create a function that loads given plugin/snippet, with an option (to use it, precede the ice content with !) to automatically forward the call afterwards. Example use:

    # Invoking the command `crasis' will load the plugin that
    # provides the function `crasis', and it will be then
    # immediately invoked with the same arguments
    zinit ice trigger-load'!crasis'
    zinit load zdharma/zinit-crasis
    

• 22-10-2019

  • A new ice countdown – causes an interruptable (by Ctrl-C) countdown 5…4…3…2…1…0 to be displayed before running the atclone'', atpull'' and make ices.

• 21-10-2019

  • The times command has a new option -m – it shows the moments of the plugin load times – i.e.: how late after loading Zinit a plugin has been loaded.

• 20-10-2019

  • The zinit completion now completes also snippets! The command snippet, but also delete, recall, edit, cd, etc. all receive such completing.
  • The ice subcommand can now be skipped – just pass in the ices, e.g.:

    zinit atload"zicompinit; zicdreplay" blockf
    zinit light zsh-users/zsh-completions
    

  • The compile command is able to compile snippets.
  • The plugins that add their subdirectories into $fpath can be now blockf-ed – the functions located in the dirs will be correctly auto-loaded.

• 12-10-2019

  • Special value for the id-as'' ice – auto. It sets the plugin/snippet ID automatically to the last component of its spec, e.g.:

    zinit ice id-as"auto"
    zinit load robobenklein/zinc
    

    will load the plugin as id-as'zinc'.

• 14-09-2019

  • There's a Vim plugin which extends syntax highlighting of zsh scripts with coloring of the Zinit commands. Project homepage.

• 13-09-2019

  • New ice aliases which loads plugin with the aliases mechanism enabled. Use for plugins that define and use aliases in their scripts.

• 11-09-2019

  • New ice-mods sh,bash,ksh,csh that load plugins (and snippets) with the sticky emulation feature of Zsh – all functions defined within the plugin will automatically switch to the desired emulation mode before executing and switch back thereafter. In other words it is now possible to load e.g. bash plugins with Zinit, provided that the emulation level done by Zsh is sufficient, e.g.:

    zinit ice bash pick"bash_it.sh" \
            atinit"BASH_IT=${ZINIT[PLUGINS_DIR]}/Bash-it---bash-it" \
            atclone"yes n | ./install.sh"
    zinit load Bash-it/bash-it
    

    This script loads correctly thanks to the emulation, however it isn't functional because it uses type -t … to check if a function exists.

• 10-09-2019

  • A new ice-mod reset'' that ivokes git reset --hard (or the provided command) before git pull and atpull'' ice. It can be used it to implement altering (i.e. patching) of the plugin's files inside the atpull'' ice – git will report no conflicts when doing pull, and the changes can be then again introduced by the atpull'' ice.

  • Three new Zinit annexes (i.e. extensions):

    • z-a-man

      Generates man pages and code-documentation man pages from plugin's README.md and source files (the code documentation is obtained from Zshelldoc).

    • z-a-test

      Runs tests (if detected test target in a Makefile or any *.zunit files) on plugin installation and non-empty update.

    • z-a-patch-dl

      Allows easy download and applying of patches, to e.g. aid building a binary program equipped in the plugin.

  • A new variable is being recognized by the installation script: $ZPLG_BIN_DIR_NAME. It configures the directory within $ZPLG_HOME to which Zinit should be cloned.

To see the full history check the changelog.

Zinit

Zinit is an elastic and fast Zshell plugin manager that will allow you to install everything from GitHub and other sites.

Zinit is currently the only plugin manager out there that has Turbo mode which yields 50-80% faster Zsh startup! (i.e.: the shell will start up to 5 times faster!). Check out a speed comparison with other popular plugin managers here.

Zinit gives reports from plugin load describing what aliases, functions, bindkeys, Zle widgets, zstyles, completions, variables, PATH and FPATH elements a plugin has set up.

Supported is unloading of plugin and ability to list, (un)install and selectively disable, enable plugin's completions.

The system does not use $FPATH, loading multiple plugins doesn't clutter $FPATH with the same number of entries (e.g. 10). Code is immune to KSH_ARRAYS. Completion management functionality is provided to allow user to call compinit only once in .zshrc.

Zinit Wiki

The information in this README is complemented by the Zinit wiki. The README is an introductory overview of Zinit while the wiki gives a complete and in-depth information with examples. Make sure to read it to get the most out of Zinit.

Installation

Option 1 - Automatic Installation (Recommended)

The easiest way to install Zinit is to execute:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/zdharma/zinit/master/doc/install.sh)"

This will install Zinit in ~/.zinit/bin. .zshrc will be updated with three lines of code that will be added to the bottom. The lines will be sourcing zinit.zsh and setting up completion for command zinit. After installing and reloading the shell compile Zinit with zinit self-update.

Option 2 - Manual Installation

To manually install Zinit clone the repo to e.g. ~/.zinit/bin:

mkdir ~/.zinit
git clone https://github.com/zdharma/zinit.git ~/.zinit/bin

and source it from .zshrc (above compinit):

source ~/.zinit/bin/zinit.zsh

If you place the source below compinit, then add those two lines after the source:

autoload -Uz _zinit
(( ${+_comps} )) && _comps[zinit]=_zinit

Various paths can be customized, see section Customizing Paths.

After installing and reloading the shell compile Zinit with zinit self-update.

Usage

Introduction

Click here to read the introduction to Zinit. It explains basic usage and some of the more unique features of Zinit such as the Turbo mode. If you're new to Zinit we highly recommend you read it at least once.

Example Usage

After installing Zinit you can start adding some actions (load some plugins) to ~/.zshrc, at bottom. Some examples:

# Two regular plugins loaded without tracking.
zinit light zsh-users/zsh-autosuggestions
zinit light zdharma/fast-syntax-highlighting

# Plugin history-search-multi-word loaded with tracking.
zinit load zdharma/history-search-multi-word

# Load the pure theme, with zsh-async library that's bundled with it.
zinit ice pick"async.zsh" src"pure.zsh"
zinit light sindresorhus/pure

# Binary release in archive, from GitHub-releases page.
# After automatic unpacking it provides program "fzf".
zinit ice from"gh-r" as"program"
zinit load junegunn/fzf-bin

# One other binary release, it needs renaming from `docker-compose-Linux-x86_64`.
# This is done by ice-mod `mv'{from} -> {to}'. There are multiple packages per
# single version, for OS X, Linux and Windows – so ice-mod `bpick' is used to
# select Linux package – in this case this is actually not needed, Zinit will
# grep operating system name and architecture automatically when there's no `bpick'.
zinit ice from"gh-r" as"program" mv"docker* -> docker-compose" bpick"*linux*"
zinit load docker/compose

# Vim repository on GitHub – a typical source code that needs compilation – Zinit
# can manage it for you if you like, run `./configure` and other `make`, etc. stuff.
# Ice-mod `pick` selects a binary program to add to $PATH. You could also install the
# package under the path $ZPFX, see: http://zdharma.org/zinit/wiki/Compiling-programs
zinit ice as"program" atclone"rm -f src/auto/config.cache; ./configure" \
    atpull"%atclone" make pick"src/vim"
zinit light vim/vim

# Scripts that are built at install (there's single default make target, "install",
# and it constructs scripts by `cat'ing a few files). The make'' ice could also be:
# `make"install PREFIX=$ZPFX"`, if "install" wouldn't be the only, default target.
zinit ice as"program" pick"$ZPFX/bin/git-*" make"PREFIX=$ZPFX"
zinit light tj/git-extras

# Handle completions without loading any plugin, see "clist" command.
# This one is to be ran just once, in interactive session.
zinit creinstall %HOME/my_completions

# For GNU ls (the binaries can be gls, gdircolors, e.g. on OS X when installing the
# coreutils package from Homebrew; you can also use https://github.com/ogham/exa)
zinit ice atclone"dircolors -b LS_COLORS > c.zsh" atpull'%atclone' pick"c.zsh" nocompile'!'
zinit light trapd00r/LS_COLORS

You can see an extended explanation of LS_COLORS in the wiki.

# make'!...' -> run make before atclone & atpull
zinit ice as"program" make'!' atclone'./direnv hook zsh > zhook.zsh' atpull'%atclone' src"zhook.zsh"
zinit light direnv/direnv

You can see an extended explanation of direnv in the wiki.

If you're interested in more examples then check out the zinit-configs repository where users have uploaded their ~/.zshrc and Zinit configurations. Feel free to submit your ~/.zshrc there if it contains Zinit commands.

You can also check out the Gallery of Zinit Invocations for some additional examples.

Ice Modifiers

Following ice modifiers are to be passed to zinit ice ... to obtain described effects. The word ice means something that's added (like ice to a drink) – and in Zinit it means adding modifier to a next zinit command, and also something that's temporary because it melts – and this means that the modification will last only for a single next zinit command.

Some Ice-modifiers are highlighted and clicking on them will take you to the appropriate wiki page for an extended explanation.

You may safely assume a given ice works with both plugins and snippets unless explicitly stated otherwise.

Cloning Options

Modifier	Description
proto	Change protocol to git,ftp,ftps,ssh, rsync, etc. Default is https. Does not work with snippets.
from	Clone plugin from 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.
ver	Used 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 explicitly ver"latest". Works also with regular plugins, checkouts e.g. ver"abranch", i.e. a specific version. Does not work with snippets.
bpick	Used to select which release from GitHub Releases to download, e.g. zini ice from"gh-r" as"program" bpick"*Darwin*"; zini load docker/compose. Does not work with snippets.
depth	Pass --depth to git, i.e. limit how much of history to download. Does not work with snippets.
cloneopts	Pass the contents of cloneopts to git clone. Defaults to --recursive i.e. Change cloning options. Does not work with snippets.
svn	Use Subversion for downloading snippet. GitHub supports SVN protocol, this allows to clone subdirectories as snippets, e.g. zinit ice svn; zinit snippet OMZ::plugins/git. Other ice pick can be used to select file to source (default are: *.plugin.zsh, init.zsh, *.zsh-theme). Does not work with plugins.

Selection of Files (To Source, …)

Modifier	Description
pick	Select the file to source, or the file to set as command (when using snippet --command or the ice as"program"); it is a pattern, alphabetically first matched file is being chosen; e.g. zinit ice pick"*.plugin.zsh"; zinit load ….
src	Specify additional file to source after sourcing main file or after setting up command (via as"program"). It is not a pattern but a plain file name.
multisrc	Allows to specify multiple files for sourcing, enumerated with spaces as the separators (e.g. multisrc'misc.zsh grep.zsh') and also using brace-expansion syntax (e.g. multisrc'{misc,grep}.zsh'). Supports patterns.

Conditional Loading

Modifier	Description
wait	Postpone loading a plugin or snippet. For wait'1', loading is done 1 second after prompt. For wait'[[ ... ]]', wait'(( ... ))', loading is done when given condition is meet. For wait'!...', prompt is reset after load. Zsh can start 80% (i.e.: 5x) faster thanks to postponed loading. Fact: when wait is used without value, it works as wait'0'.
load	A condition to check which should cause plugin to load. It will load once, the condition can be still true, but will not trigger second load (unless plugin is unloaded earlier, see unload below). E.g.: load'[[ $PWD = */github* ]]'.
unload	A condition to check causing plugin to unload. It will unload once, then only if loaded again. E.g.: unload'[[ $PWD != */github* ]]'.
cloneonly	Don't load the plugin / snippet, only download it
if	Load plugin or snippet only when given condition is fulfilled, for example: zinit ice if'[[ -n "$commands[otool]" ]]'; zinit load ....
has	Load plugin or snippet only when given command is available (in $PATH), e.g. zinit ice has'git' ...
subscribe / on-update-of	Postpone loading of a plugin or snippet until the given file(s) get updated, e.g. subscribe'{~/files-*,/tmp/files-*}'
trigger-load	Creates a function that loads the associated plugin/snippet, with an option (to use it, precede the ice content with !) to automatically forward the call afterwards, to a command of the same name as the function. Can obtain multiple functions to create – sparate with ;.

Plugin Output

Modifier	Description
silent	Mute plugin's or snippet's stderr & stdout. Also skip Loaded ... message under prompt for wait, etc. loaded plugins, and completion-installation messages.
lucid	Skip Loaded ... message under prompt for wait, etc. loaded plugins (a subset of silent).
notify	Output 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

Modifier	Description
blockf	Disallow plugin to modify fpath. Useful when a plugin wants to provide completions in traditional way. Zinit can manage completions and plugin can be blocked from exposing them.
nocompletions	Don't detect, install and manage completions for this plugin. Completions can be installed later with zinit creinstall {plugin-spec}.

Command Execution After Cloning, Updating or Loading

Modifier	Description
mv	Move file after cloning or after update (then, only if new commits were downloaded). Example: mv "fzf-* -> fzf". It uses -> as separator for old and new file names. Works also with snippets.
cp	Copy file after cloning or after update (then, only if new commits were downloaded). Example: cp "docker-c* -> dcompose". Ran after mv.
atclone	Run command after cloning, within plugin's directory, e.g. zinit ice atclone"echo Cloned". Ran also after downloading snippet.
atpull	Run command after updating (only if new commits are waiting for download), within plugin's directory. If starts with "!" then command will be ran before mv & cp ices and before git pull or svn update. Otherwise it is ran after them. Can be atpull'%atclone', to repeat atclone Ice-mod.
atinit	Run command after directory setup (cloning, checking it, etc.) of plugin/snippet but before loading.
atload	Run command after loading, within plugin's directory. Can be also used with snippets. Passed code can be preceded with !, it will then be tracked (if using load, not light).
run-atpull	Always run the atpull hook (when updating), not only when there are new commits to be downloaded.
nocd	Don't switch the current directory into the plugin's directory when evaluating the above ice-mods atinit'',atload'', etc.
make	Run make command after cloning/updating and executing mv, cp, atpull, atclone Ice mods. Can obtain argument, e.g. make"install PREFIX=/opt". If the value starts with ! then make is ran before atclone/atpull, e.g. make'!'.
countdown	Causes an interruptable (by Ctrl-C) countdown 5…4…3…2…1…0 to be displayed before executing atclone'',atpull'' and make ices
reset	Invokes 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 in e.g.: atclone'' ice. For file snippets and gh-r plugins it invokes rm -rf *.

Sticky-Emulation Of Other Shells

Modifier	Description
sh, !sh	Source 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 – when invoked they'll execute also with the sh emulation set-up. The !sh version switches additional options that are rather not important from the portability perspective.
bash, !bash	The same as sh, but with the SH_GLOB option disabled, so that Bash regular expressions work.
ksh, !ksh	The same as sh, but emulating ksh shell.
csh, !csh	The same as sh, but emulating csh shell.

Others

Modifier	Description
as	Can be as"program" (also the 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. 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.
id-as	Nickname a plugin or snippet, to e.g. create a short handler for long-url snippet.
compile	Pattern (+ possible {...} expansion, like {a/*,b*}) to select additional files to compile, e.g. compile"(pure|async).zsh" for sindresorhus/pure.
nocompile	Don'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).
service	Make following plugin or snippet a service, which will be ran in background, and only in single Zshell instance. See zservices-organization page.
reset-prompt	Reset 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 !.
bindmap	To 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.
trackbinds	Shadow but only bindkey calls even with zinit light ..., i.e. even with tracking disabled (fast loading), to allow bindmap to remap the key-binds. The same effect has zinit light -b ..., i.e. additional -b option to the light-subcommand. Does not work with snippets.
wrap-track	Takes a ;-separated list of function names that are to be tracked (meaning gathering report and unload data) once during execution. It works by wrapping the functions with a tracking-enabling and disabling snippet of code. In summary, wrap-track allows to extend the tracking beyond the moment of loading of a plugin. Example use is to wrap-track a precmd function of a prompt (like _p9k_precmd() of powerlevel10k) or other plugin that postpones its initialization till the first prompt (like e.g.: zsh-autosuggestions). Does not work with snippets.
aliases	Load the plugin with the aliases mechanism enabled. Use with plugins that define and use aliases in their scripts.
light-mode	Load the plugin without the tracking, i.e.: as if it would be loaded with the light command. Useful for the for-syntax, where there is no load nor light subcommand

Order of Execution

Order of execution of related Ice-mods: atinit -> atpull! -> make'!!' -> mv -> cp -> make! -> atclone/atpull -> make -> (plugin script loading) -> src -> multisrc -> atload.

Zinit Commands

Following commands are passed to zinit ... to obtain described effects.

Help

Command	Description
-h, --help, help	Usage information.
man	Manual.

Loading and Unloading

Command	Description
load {plg-spec}	Load plugin, can also receive absolute local path.
light [-b] {plg-spec}	Light plugin load, without reporting/tracking. -b – track bindkey-calls only. There's also light-mode ice which can be used to induce the no-tracking (i.e.: light) loading, regardless of the command used.
unload [-q] {plg-spec}	Unload plugin loaded with zinit load .... -q – quiet.
snippet [-f] {url}	Source local or remote file (by direct URL). -f – don't use cache (force redownload).

Completions

Command	Description
clist [columns], completions [columns]	List completions in use, with columns completions per line. zpl clist 5 will for example print 5 completions per line. Default is 3.
cdisable {cname}	Disable completion cname.
cenable {cname}	Enable completion cname.
creinstall [-q] {plg-spec}	Install completions for plugin, can also receive absolute local path. -q – quiet.
cuninstall {plg-spec}	Uninstall completions for plugin.
csearch	Search for available completions from any plugin.
compinit	Refresh installed completions.
cclear	Clear stray and improper completions.
cdlist	Show compdef replay list.
cdreplay [-q]	Replay compdefs (to be done after compinit). -q – quiet.
cdclear [-q]	Clear compdef replay list. -q – quiet.

Tracking of the Active Session

Command	Description
dtrace, dstart	Start tracking what's going on in session.
dstop	Stop tracking what's going on in session.
dunload	Revert changes recorded between dstart and dstop.
dreport	Report what was going on in session.
dclear	Clear report of what was going on in session.

Reports and Statistics

Command	Description
times [-s] [-m]	Statistics on plugin load times, sorted in order of loading. -s – use seconds instead of milliseconds. -m – show plugin loading moments.
zstatus	Overall Zinit status.
report {plg-spec}|--all	Show plugin report. --all – do it for all plugins.
loaded [keyword], list [keyword]	Show what plugins are loaded (filter with 'keyword').
ls	List snippets in formatted and colorized manner. Requires tree program.
status {plg-spec}|URL|--all	Git status for plugin or svn status for snippet. --all – do it for all plugins and snippets.
recently [time-spec]	Show plugins that changed recently, argument is e.g. 1 month 2 days.
bindkeys	Lists bindkeys set up by each plugin.

Compiling

Command	Description
compile {plg-spec}|--all	Compile plugin. --all – compile all plugins.
uncompile {plg-spec}|--all	Remove compiled version of plugin. --all – do it for all plugins.
compiled	List plugins that are compiled.

Other

Command	Description
self-update	Updates and compiles Zinit.
update [-q] [-r] {plg-spec}|URL|--all	Git update plugin or snippet. --all – update all plugins and snippets. -q – quiet. -r | --reset – run git reset --hard / svn revert before pulling changes.
ice <ice specification>	Add ice to next command, argument is e.g. from"gitlab".
delete {plg-spec}|URL|--clean|--all	Remove plugin or snippet from disk (good to forget wrongly passed ice-mods). --all – purge. --clean – delete plugins and snippets that are not loaded.
cd {plg-spec}	Cd into plugin's directory. Also support snippets if fed with URL.
edit {plg-spec}	Edit plugin's file with $EDITOR.
glance {plg-spec}	Look at plugin's source (pygmentize, {,source-}highlight).
stress {plg-spec}	Test plugin for compatibility with set of options.
changes {plg-spec}	View plugin's git log.
create {plg-spec}	Create plugin (also together with GitHub repository).
srv {service-id} [cmd]	Control a service, command can be: stop,start,restart,next,quit; next moves the service to another Zshell.
recall {plg-spec}|URL	Fetch saved ice modifiers and construct zinit ice ... command.
env-whitelist [-v] [-h] {env..}	Allows to specify names (also patterns) of variables left unchanged during an unload. -v – verbose.
module	Manage binary Zsh module shipped with Zinit, see zinit module help.
add-fpath|fpath [-f|--front] {plg-spec} [subdirectory]	Adds given plugin (not yet snippet) directory to $fpath. If the second argument is given, it is appended to the directory path. If the option -f/--front is given, the directory path is prepended instead of appended to $fpath. The {plg-spec} can be absolute path, i.e.: it's possible to also add regular directories.
run [-l] [plugin] {command}	Runs the given command in the given plugin's directory. If the option -l will be given then the plugin should be skipped – the option will cause the previous plugin to be reused.

Updating Zinit and Plugins

To update Zinit issue zinit self-update in the command line.

To update all plugins and snippets, issue zinit update. If you wish to update only a single plugin/snippet instead issue zinit update NAME_OF_PLUGIN. A list of commits will be shown:

Some plugins require performing an action each time they're updated. One way you can do this is by using the atpull ice modifier. For example, writing zinit ice atpull'./configure' before loading a plugin will execute ./configure after a successful update. Refer to Ice Modifiers for more information.

The ice modifiers for any plugin or snippet are stored in their directory in a ._zinit subdirectory, hence the plugin doesn't have to be loaded to be correctly updated. There's one other file created there, .zinit_lstupd – it holds the log of the new commits pulled-in in the last update.

Using Oh My Zsh Themes

To use themes created for Oh My Zsh you might want to first source the git library there:

zinit snippet http://github.com/ohmyzsh/ohmyzsh/raw/master/lib/git.zsh
# Or using OMZ:: shorthand:
zinit snippet OMZ::lib/git.zsh

If the library will not be loaded, then similar to following errors will be appearing:

........:1: command not found: git_prompt_status
........:1: command not found: git_prompt_short_sha

Then you can use the themes as snippets (zinit snippet {file path or GitHub URL}). Some themes require not only Oh My Zsh's Git library, but also Git plugin (error about current_branch function can be appearing). Load this Git-plugin as single-file snippet directly from OMZ:

zinit snippet OMZ::plugins/git/git.plugin.zsh

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

Most themes require promptsubst option (setopt promptsubst in zshrc), if it isn't set, then prompt will appear as something like: ... $(build_prompt) ....

You might want to suppress completions provided by the git plugin by issuing zinit cdclear -q (-q is for quiet) – see below Ignoring Compdefs.

To summarize:

# Load OMZ Git library
zinit snippet OMZ::lib/git.zsh

# Load Git plugin from OMZ
zinit snippet OMZ::plugins/git/git.plugin.zsh
zinit cdclear -q # <- forget completions provided up to this moment

setopt promptsubst

# Load theme from OMZ
zinit snippet OMZ::themes/dstufft.zsh-theme

# Load normal GitHub plugin with theme depending on OMZ Git library
zinit light NicoSantangelo/Alpharized

See also the Wiki page: Example Oh My Zsh Setup.

Completions

Calling compinit Without Turbo Mode

With no Turbo mode in use, compinit can be called normally, i.e.: as autoload compinit; compinit. This should be done after loading of all plugins and before possibly calling zinit cdreplay.

The cdreplay subcommand is provided to re-play all catched compdef calls. The compdef calls are used to define a completion for a command. For example, compdef _git git defines that the git command should be completed by a _git function.

The compdef function is provided by compinit call. As it should be called later, after loading all of the plugins, Zinit provides its own compdef function that catches (i.e.: records in an array) the arguments of the call, so that the loaded plugins can freely call compdef. Then, the cdreplay (compdef-replay) can be used, after compinit will be called (and the original compdef function will become available), to execute all detected compdef calls. To summarize:

source ~/.zinit/bin/zinit.zsh

zinit load "some/plugin"
...
compdef _gnu_generic fd  # this will be intercepted by Zinit, because as the compinit
                         # isn't yet loaded, thus there's no such function `compdef'; yet
                         # Zinit provides its own `compdef' function which saves the
                         # completion-definition for later possible re-run with `zinit
                         # cdreplay' or `zicdreplay' (the second one can be used in hooks
                         # like atload'', atinit'', etc.)
...
zinit load "other/plugin"

autoload -Uz compinit
compinit

zinit cdreplay -q   # -q is for quiet; actually run all the `compdef's saved before
                    #`compinit` call (`compinit' declares the `compdef' function, so
                    # it cannot be used until `compinit' is ran; Zinit solves this
                    # via intercepting the `compdef'-calls and storing them for later
                    # use with `zinit cdreplay')

This allows to call compinit once. Performance gains are huge, example shell startup time with double compinit: 0.980 sec, with cdreplay and single compinit: 0.156 sec.

Calling compinit With Turbo Mode

If you load completions using wait'' Turbo mode then you can add atinit'zicompinit' to syntax-highlighting plugin (which should be the last one loaded, as their (2 projects, z-sy-h & f-sy-h) documentation state), or atload'zicompinit' to last completion-related plugin. zicompinit is a function that just runs autoload compinit; compinit, created for convenience. There's also zicdreplay which will replay any caught compdefs so you can also do: atinit'zicompinit; zicdreplay', etc. Basically, the whole topic is the same as normal compinit call, but it is done in atinit or atload hook of the last related plugin with use of the helper functions (zicompinit,zicdreplay & zicdclear – see below for explanation of the last one). To summarize:

source ~/.zinit/bin/zinit.zsh

# Load using the for-syntax
zinit wait lucid for \
    "some/plugin"
zinit wait lucid for \
    "other/plugin"

zinit wait lucid atload"zicompinit; zicdreplay" blockf for \
    zsh-users/zsh-completions

Ignoring Compdefs

If you want to ignore compdefs provided by some plugins or snippets, place their load commands before commands loading other plugins or snippets, and issue zinit cdclear (or zicdclear, designed to be used in hooks like atload''):

source ~/.zinit/bin/zinit.zsh
zinit snippet OMZ::plugins/git/git.plugin.zsh
zinit cdclear -q # <- forget completions provided by Git plugin

zinit load "some/plugin"
...
zinit load "other/plugin"

autoload -Uz compinit
compinit
zinit cdreplay -q # <- execute compdefs provided by rest of plugins
zinit cdlist # look at gathered compdefs

The cdreplay is important if you use plugins like OMZ::plugins/kubectl/kubectl.plugin.zsh or asdf-vm/asdf, because those plugins call compdef.

Disabling System-Wide compinit Call (Ubuntu)

On Ubuntu users might get surprised that e.g. their completions work while they didn't call compinit in their .zshrc. That's because the function is being called in /etc/zshrc. To disable this call – what is needed to avoid the slowdown and if user loads any completion-equipped plugins, i.e. almost on 100% – add the following lines to ~/.zshenv:

# Skip the not really helping Ubuntu global compinit
skip_global_compinit=1

Zinit Module

Motivation

The module is a binary Zsh module (think about zmodload Zsh command, it's that topic) which transparently and automatically compiles sourced scripts. Many plugin managers do not offer compilation of plugins, the module is a solution to this. Even if a plugin manager does compile plugin's main script (like Zinit does), the script can source smaller helper scripts or dependency libraries (for example, the prompt geometry-zsh/geometry does that) and there are very few solutions to that, which are demanding (e.g. specifying all helper files in plugin load command and tracking updates to the plugin – in Zinit case: by using compile ice-mod).

Installation

Without Zinit

To install just the binary Zinit module standalone (Zinit is not needed, the module can be used with any other plugin manager), execute:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/zdharma/zinit/master/doc/mod-install.sh)"

This script will display what to add to ~/.zshrc (2 lines) and show usage instructions.

With Zinit

Zinit users can build the module by issuing following command instead of running above mod-install.sh script (the script is for e.g. zgen users or users of any other plugin manager):

zinit module build

This command will compile the module and display instructions on what to add to ~/.zshrc.

Measuring Time of sources

Besides the compilation-feature, the module also measures duration of each script sourcing. Issue zpmod source-study after loading the module at top of ~/.zshrc to see a list of all sourced files with the time the sourcing took in milliseconds on the left. This feature allows to profile the shell startup. Also, no script can pass-through that check and you will obtain a complete list of all loaded scripts, like if Zshell itself was tracking this. The list can be surprising.

Debugging

To enable debug messages from the module set:

typeset -g ZPLG_MOD_DEBUG=1

Hints and Tips

Customizing Paths

Following variables can be set to custom values, before sourcing Zinit. The previous global variables like $ZPLG_HOME have been removed to not pollute the namespace – there's single $ZINIT hash instead of 8 string variables. Please update your dotfiles.

declare -A ZINIT  # initial Zinit's hash definition, if configuring before loading Zinit, and then:

Hash Field	Description
ZINIT[BIN_DIR]	Where Zinit code resides, e.g.: "~/.zinit/bin"
ZINIT[HOME_DIR]	Where Zinit should create all working directories, e.g.: "~/.zinit"
ZINIT[PLUGINS_DIR]	Override single working directory – for plugins, e.g. "/opt/zsh/zinit/plugins"
ZINIT[COMPLETIONS_DIR]	As above, but for completion files, e.g. "/opt/zsh/zinit/root_completions"
ZINIT[SNIPPETS_DIR]	As above, but for snippets
ZINIT[ZCOMPDUMP_PATH]	Path to .zcompdump file, with the file included (i.e. its name can be different)
ZINIT[COMPINIT_OPTS]	Options for compinit call (i.e. done by zicompinit), use to pass -C to speed up loading
ZINIT[MUTE_WARNINGS]	If set to 1, then mutes some of the Zinit warnings, specifically the plugin already registered warning

There is also $ZPFX, set by default to ~/.zinit/polaris – a directory where software with Makefile, etc. can be pointed to, by e.g. atclone'./configure --prefix=$ZPFX'.

Non-GitHub (Local) Plugins

Use create subcommand with user name _local (the default) to create plugin's skeleton in $ZINIT[PLUGINS_DIR]. It will be not connected with GitHub repository (because of user name being _local). To enter the plugin's directory use cd command with just plugin's name (without _local, it's optional).

If user name will not be _local, then Zinit will create repository also on GitHub and setup correct repository origin.

Extending Git

There are several projects that provide git extensions. Installing them with Zinit has many benefits:

• all files are under $HOME – no administrator rights needed,
• declarative setup (like Chef or Puppet) – copying .zshrc to different account brings also git-related setup,
• easy update by e.g. zinit update --all.

Below is a configuration that adds multiple git extensions, loaded in Turbo mode, two seconds after prompt:

zinit ice wait"2" lucid as"program" pick"bin/git-dsf"
zinit light zdharma/zsh-diff-so-fancy

zinit ice wait"2" lucid as"program" pick"git-now"
zinit light iwata/git-now

zinit ice wait"2" lucid as"program" pick"$ZPFX/bin/git-alias" make"PREFIX=$ZPFX" nocompile
zinit light tj/git-extras

zinit ice wait"2" lucid as"program" atclone'perl Makefile.PL PREFIX=$ZPFX' atpull'%atclone' \
            make'install' pick"$ZPFX/bin/git-cal"
zinit light k4rthik/git-cal

Target directory for installed files is $ZPFX (~/.zinit/polaris by default).

Preinstalling Plugins

If you create a Docker image that uses Zinit, or want to install Turbo-loaded plugins before the shell starts interactively, you can invoke the zinit-scheduler function in such a way, that it:

• installs plugins without waiting for the prompt (i.e. it's script friendly),
• installs all plugins instantly, without respecting the wait'' argument.

To accomplish this, use burst argument and call @zinit-scheduler function. Example Dockerfile entry:

RUN zsh -i -c -- '@zinit-scheduler burst || true'

An example Dockerfile can be found here.

Getting Help and Community

Do you need help or wish to get in touch with other Zinit users?

• Visit our subreddit r/zinit.

• Chat with us in our IRC channel. Connect to chat.freenode.net:6697 (SSL) or chat.freenode.net:6667 and join #zinit. Following is a quick access via Webchat

• Or via Gitter