zinit

Note: Sebastian Gniazdowski, the original zinit dev, deleted zdharma randomly. This is a reliable fork / place for the continuation of the project.

Table of Contents generated with DocToc

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

To see the full history check the changelog.

Zinit

Zinit is a flexible and fast Zshell plugin manager that will allow you to install everything from GitHub and other sites. Its characteristics are:

1. Zinit is currently the only plugin manager out there that provides 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.

2. The plugin manager gives reports from plugin loadings describing what aliases, functions, bindkeys, Zle widgets, zstyles, completions, variables, PATH and FPATH elements a plugin has set up. This allows to quickly familiarize oneself with a new plugin and provides rich and easy to digest information which might be helpful on various occasions.

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

4. The plugin manager supports loading Oh My Zsh and Prezto plugins and libraries, however the implementation isn't framework specific and doesn't bloat the plugin manager with such code (more on this topic can be found on the Wiki, in the Introduction).

5. The system does not use $FPATH, loading multiple plugins doesn't clutter $FPATH with the same number of entries (e.g. 10, 15 or more). Code is immune to KSH_ARRAYS and other options typically causing compatibility problems.

6. Zinit supports special, dedicated packages that offload the user from providing long and complex commands. See the Zsh-Packages organization for a growing, complete list of Zinit packages and the Wiki page for an article about the feature.

7. Also, specialized Zinit extensions — called annexes — allow to extend the plugin manager with new commands, URL-preprocessors (used by e.g.: z-a-as-monitor annex), post-install and post-update hooks and much more. See the zdharma-continuum organization for a growing, complete list of available Zinit extensions and refer to the Wiki article for an introduction on creating your own annex.

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 information with examples. Make sure to read it to get the most out of Zinit.

Quick Start

Install

Automatic Installation (Recommended)

The easiest way to install Zinit is to execute:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/zdharma-continuum/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.

Manual Installation

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

mkdir ~/.zinit
git clone https://github.com/zdharma-continuum/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.

Plugins and snippets

Plugins can be loaded using load or light.

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

If you want to source local or remote files (using direct URL), you can do so with snippet.

zinit snippet <URL>

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).

Example

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

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

# Snippet
zinit snippet https://gist.githubusercontent.com/hightemp/5071909/raw/

Prompt(Theme) Example

This is powerlevel10k, pure, starship sample:

# Load powerlevel10k theme
zinit ice depth"1" # git clone depth
zinit light romkatv/powerlevel10k

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

# Load starship theme
zinit ice as"command" from"gh-r" \ # `starship` binary as command, from github release
          atclone"./starship init zsh > init.zsh; ./starship completions zsh > _starship" \ # starship setup at clone(create init.zsh, completion)
          atpull"%atclone" src"init.zsh" # pull behavior same as clone, source init.zsh
zinit light starship/starship

Upgrade Zinit and plugins

Zinit can be updated to self-update and plugins to update.

# Self update
zinit self-update

# Plugin update
zinit update

# Plugin parallel update
zinit update --parallel

# Increase the number of jobs in a concurrent-set to 40
zinit update --parallel 40

Turbo and lucid

Turbo and lucid are the most used options.

Turbo Mode Turbo mode is the key to performance. It can be loaded asynchronously, which makes a huge difference when the amount of plugins increases.

Lucid

F&A: What is ice?

ice is zinit's option command. The option melts like ice and is used only once. (more: Ice Modifiers)

Migration

Migration from Oh-My-ZSHMigration from PreztoMigration from ZgenMigration from Zplug

More Examples

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

# 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

# A glance at the new for-syntax – load all of the above
# plugins with a single command. For more information see:
# https://zdharma-continuum.github.io/zinit/wiki/For-Syntax/
zinit for \
    light-mode  zsh-users/zsh-autosuggestions \
    light-mode  zdharma-continuum/fast-syntax-highlighting \
                zdharma-continuum/history-search-multi-word \
    light-mode pick"async.zsh" src"pure.zsh" \
                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 light junegunn/fzf

# 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-continuum.github.io/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.

Also, two articles on the Wiki present an example setup here and here.

How to Use

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

Selection of Files (To Source, …)

Conditional Loading

Plugin Output

Completions

Command Execution After Cloning, Updating or Loading

Sticky-Emulation Of Other Shells

Others

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.

Command Description -h, --help, help

Loading and Unloading

Completions

Tracking of the Active Session

Reports and Statistics

Compiling

Other

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.

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 OMZP::git
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 OMZP::kubectl or asdf-vm/asdf, because these 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 investigating 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-continuum/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 investigating 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:

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, 1 second after prompt, with use of the Bin-Gem-Node annex:

zinit as"null" wait"1" lucid for \
    sbin    Fakerr/git-recall \
    sbin    cloneopts paulirish/git-open \
    sbin    paulirish/git-recent \
    sbin    davidosomething/git-my \
    sbin atload"export _MENU_THEME=legacy" \
            arzzen/git-quick-stats \
    sbin    iwata/git-now \
    make"PREFIX=$ZPFX install" \
            tj/git-extras \
    sbin"git-url;git-guclone" make"GITURL_NO_CGITURL=1" \
            zdharma-continuum/git-url

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

Supporting

Zinit is a personal, free-time project with no funding and a huge feature request backlog. If you love it, consider supporting its development via GitHub Sponsors or Patreon. Any help counts!

Getting Help and Community

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

• Visit our subreddit r/zinit.

• Or via Gitter