ZINIT(1)

📦 version 3.17.1, in nixpkgs unstable

💖 ZINIT(1) — zinit, the flexible fast Zsh plugin manager 💖

okay so bestie, welcome to ZINIT(1) — the manual page for zinit, and no cap this thing is a whole era. ✨

The badges at the top are giving:

Note: The original author (https://github.com/psprint) of zinit deleted the zdharma organization randomly. 😭 This is a reliable fork / place for the continuation of the project. 🚧 For migration instructions please refer to this wiki entry: https://github.com/zdharma-continuum/zinit/wiki/%F0%9F%9A%9A-Migration-to-zdharma-continuum

🧭 Table of Contents (DocToc made this, iykyk) 🧭

Table of Contents generated with DocToc: https://github.com/thlorenz/doctoc

  • News
  • Zinit
  • Zinit Wiki
  • Quick Start
    • Install
      • Automatic Installation (Recommended)
      • Manual Installation
    • Usage
      • Introduction
      • Plugins and snippets
      • Upgrade Zinit and plugins
      • Turbo and lucid
      • Migration
      • More Examples
  • How to Use
    • Ice Modifiers
      • 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
    • Zinit Commands
      • Help
      • Loading and Unloading
      • Completions
      • Tracking of the Active Session
      • Reports and Statistics
      • Compiling
      • Other
    • Updating Zinit and Plugins
  • Completions
    • Calling compinit Without Turbo Mode
    • Calling compinit With Turbo Mode
    • Ignoring Compdefs
    • Disabling System-Wide compinit Call (Ubuntu)
  • Zinit Module
  • Hints and Tips
    • Customizing Paths
    • Non-GitHub (Local) Plugins
    • Extending Git
  • Supporting
  • Getting Help and Community

📰 News

See here. 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: https://github.com/zdharma-continuum/pm-perf-test.
  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 you to quickly familiarize yourself 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 the ability to list, (un)install and selectively disable, enable plugin’s completions. slay.
  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: https://zdharma-continuum.github.io/zinit/wiki/INTRODUCTION/#oh_my_zsh_prezto).
  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 zinit-packages repository for a growing, complete list of Zinit packages: https://github.com/zdharma-continuum/zinit-packages — and the Wiki page for an article about the feature: https://zdharma-continuum.github.io/zinit/wiki/Zinit-Packages/.
  7. Also, specialized Zinit extensions — called annexes — allow you to extend the plugin manager with new commands, URL-preprocessors (used by e.g.: zinit-annex-as-monitor annex: https://github.com/zdharma-continuum/zinit-annex-as-monitor), post-install and post-update hooks and much more. See the zdharma-continuum organization for a growing, complete list of available Zinit extensions: https://github.com/zdharma-continuum — and refer to the Wiki article for an introduction on creating your own annex: https://zdharma-continuum.github.io/zinit/wiki/Annexes/.

📚 Zinit Wiki

The information in this README is complemented by the Zinit Wiki: https://zdharma-continuum.github.io/zinit/wiki/. The README is an introductory overview of Zinit while the Wiki gives complete information with examples. Make sure to read it to get the most out of Zinit. 🫶

🌸 Quick Start

🧸 Install

The easiest way to install Zinit is to execute:

sh -c "$(curl -fsSL https://git.io/zinit-install)"

This will install Zinit in ~/.local/share/zinit/zinit.git. .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. ~/.local/share/zinit/zinit.git:

ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}/zinit/zinit.git"
mkdir -p "$(dirname $ZINIT_HOME)"
git clone https://github.com/zdharma-continuum/zinit.git "$ZINIT_HOME"

and source zinit.zsh from your .zshrc (above compinit: http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Initialization):

ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}/zinit/zinit.git"
source "${ZINIT_HOME}/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: https://zdharma-continuum.github.io/zinit/wiki/INTRODUCTION/. 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. no cap, it’s worth it.

🧩 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 (https://github.com/romkatv/powerlevel10k), pure (https://github.com/sindresorhus/pure), starship (https://github.com/starship/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.

Usually used as zinit ice wait"<SECONDS>", let’s use the previous example:

zinit ice wait    # wait is same wait"0"
zinit load zdharma-continuum/history-search-multi-word

zinit ice wait"2" # load after 2 seconds
zinit load zdharma-continuum/history-search-multi-word

zinit ice wait    # also be used in `light` and `snippet`
zinit snippet https://gist.githubusercontent.com/hightemp/5071909/raw/

Lucid

Turbo mode is verbose, so you need an option for quiet.

You can use with lucid:

zinit ice wait lucid
zinit load zdharma-continuum/history-search-multi-word

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-ZSH

Basic

zinit snippet <URL>        # Raw Syntax with URL
zinit snippet OMZ::<PATH>  # Shorthand OMZ/ (https://github.com/ohmyzsh/ohmyzsh/raw/master/)
zinit snippet OMZL::<PATH> # Shorthand OMZ/lib/
zinit snippet OMZT::<PATH> # Shorthand OMZ/themes/
zinit snippet OMZP::<PATH> # Shorthand OMZ/plugins/

📚 Library

Okay so the Oh-My-Zsh Library Sample — importing the clipboard (https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/clipboard.zsh) and termsupport (https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/termsupport.zsh) — is literally right here and it's so clean 💅

# Raw Syntax
zinit snippet https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/clipboard.zsh
zinit snippet https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/termsupport.zsh

# OMZ Shorthand Syntax
zinit snippet OMZ::lib/clipboard.zsh
zinit snippet OMZ::lib/termsupport.zsh

# OMZL Shorthand Syntax
zinit snippet OMZL::clipboard.zsh
zinit snippet OMZL::termsupport.zsh

🎀 Theme 🎀

To use themes made for Oh My Zsh, you might want to first source the git library from over there, bestie.

Then you can use the themes as snippets: zinit snippet <file path or GitHub URL>. Some themes need not only Oh My Zsh's Git library but the Git plugin too (an error about current_branch may appear 😭). Load that Git plugin as a single-file snippet straight from OMZ.

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

You might want to suppress the completions the git plugin gives you by running zinit cdclear -q (-q is for quiet) — see below Ignoring Compdefs 👀.

To summarize:

## Oh My Zsh Setting
ZSH_THEME="robbyrussell"

## Zinit Setting
# Must Load OMZ Git library
zinit snippet OMZL::git.zsh

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

setopt promptsubst

# Load Prompt
zinit snippet OMZT::robbyrussell

🌍 External Theme Sample: NicoSantangelo/Alpharized (https://github.com/nicosantangelo/Alpharized)

## Oh My Zsh Setting
ZSH_THEME="alpharized"

## Zinit Setting
# Must Load OMZ Git library
zinit snippet OMZL::git.zsh

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

setopt promptsubst

# Load Prompt
zinit light NicoSantangelo/Alpharized

😭 F&A: Error occurs when loading OMZ's theme.

If the git library won't be loaded, then errors like the following will appear:

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

🧩 Plugin 🧩

If it consists of a single file, you can just load it. Easy.

## Oh-My-Zsh Setting
plugins=(
  git
  dotenv
  rake
  rbenv
  ruby
)

## Zinit Setting
zinit snippet OMZP::git
zinit snippet OMZP::dotenv
zinit snippet OMZP::rake
zinit snippet OMZP::rbenv
zinit snippet OMZP::ruby

Use zinit ice svn if multiple files require an entire subdirectory. Like gitfast (https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/gitfast), osx (https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/osx):

zinit ice svn
zinit snippet OMZP::gitfast

zinit ice svn
zinit snippet OMZP::osx

Use zinit ice as"completion" to directly add single-file completion snippets. Like docker (https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/docker), fd (https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/fd):

zinit ice as"completion"
zinit snippet OMZP::docker/_docker

zinit ice as"completion"
zinit snippet OMZP::fd/_fd

You can see an extended explanation of the Oh-My-Zsh setup in the Wiki (https://zdharma-continuum.github.io/zinit/wiki/Example-Oh-My-Zsh-setup/) ✨

🔄 Migration from Prezto 🔄

Basic 🌱

zinit snippet <URL>        # Raw Syntax with URL
zinit snippet PZT::<PATH>  # Shorthand PZT/ (https://github.com/sorin-ionescu/prezto/tree/master/)
zinit snippet PZTM::<PATH> # Shorthand PZT/modules/

Modules 📦

Importing the environment (https://github.com/sorin-ionescu/prezto/tree/master/modules/environment) and terminal (https://github.com/sorin-ionescu/prezto/tree/master/modules/terminal) — Prezto Modules Sample:

## Prezto Setting
zstyle ':prezto:load' pmodule 'environment' 'terminal'

## Zinit Setting
# Raw Syntax
zinit snippet https://github.com/sorin-ionescu/prezto/blob/master/modules/environment/init.zsh
zinit snippet https://github.com/sorin-ionescu/prezto/blob/master/modules/terminal/init.zsh

# PZT Shorthand Syntax
zinit snippet PZT::modules/environment
zinit snippet PZT::modules/terminal

# PZTM Shorthand Syntax
zinit snippet PZTM::environment
zinit snippet PZTM::terminal

Use zinit ice svn if multiple files require an entire subdirectory. Like docker (https://github.com/sorin-ionescu/prezto/tree/master/modules/docker), git (https://github.com/sorin-ionescu/prezto/tree/master/modules/git):

zinit ice svn
zinit snippet PZTM::docker

zinit ice svn
zinit snippet PZTM::git

Use zinit ice as"null" if there don't exist *.plugin.zsh, init.zsh, *.zsh-theme* files in the module. Like archive (https://github.com/sorin-ionescu/prezto/tree/master/modules/archive):

zinit ice svn as"null"
zinit snippet PZTM::archive

Use zinit ice atclone"git clone <repo> <location>" if the module has an external module. Like completion (https://github.com/sorin-ionescu/prezto/tree/master/modules/completion):

zplugin ice svn blockf \ # use blockf to prevent any unnecessary additions to fpath, as zinit manages fpath
            atclone"git clone --recursive https://github.com/zsh-users/zsh-completions.git external"
zplugin snippet PZTM::completion

🤔 F&A: What is zstyle?

Read the zstyle (http://zsh.sourceforge.net/Doc/Release/Zsh-Modules.html#The-zsh_002fzutil-Module) doc (more: What does zstyle do? (https://unix.stackexchange.com/questions/214657/what-does-zstyle-do)).

🔄 Migration from Zgen 🔄

Oh My Zsh 💖

More reference: check Migration from Oh-My-ZSH

# Load ohmyzsh base
zgen oh-my-zsh
zinit snippet OMZL::<ALL OF THEM>

# Load ohmyzsh plugins
zgen oh-my-zsh <PATH>
zinit snippet OMZ::<PATH>

Prezto 💖

More reference: check Migration from Prezto

# Load Prezto
zgen prezto
zinit snippet PZTM::<COMMENT's List> # environment terminal editor history directory spectrum utility completion prompt

# Load prezto plugins
zgen prezto <modulename>
zinit snippet PZTM::<modulename>

# Load a repo as Prezto plugins
zgen pmodule <reponame> <branch>
zinit ice ver"<branch>"
zinit load <repo/plugin>

# Set prezto options
zgen prezto <modulename> <option> <value(s)>
zstyle ':prezto:<modulename>:' <option> <values(s)> # Set original prezto style

General 🌈

location: refer Selection of Files

zgen load <repo> [location] [branch]

zinit ice ver"[branch]"
zinit load <repo>

🔄 Migration from Zplug 🔄

Basic 🌱

zplug <repo/plugin>, tag1:<option1>, tag2:<option2>

zinit ice tag1"<option1>" tag2"<option2>"
zinit load <repo/plugin>

⚖️ Tag comparison ⚖️

  • as => as
  • use => pick, src, multisrc
  • ignore => None
  • from => from
  • at => ver
  • rename-to => mv, cp
  • dir => Selection(pick, ...) with rename
  • if => if
  • hook-build => atclone, atpull
  • hook-load => atload
  • frozen => None
  • on => None
  • defer => wait
  • lazy => autoload
  • depth => depth

✨ More Examples ✨

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

# 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: https://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

And there's way more coming, don't you worry 💖

# 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

There's a whole extended explanation of LS_COLORS over in the Wiki if you wanna go deeper, bestie 💖 (https://zdharma-continuum.github.io/zinit/wiki/LS_COLORS-explanation/)

# 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

And there's an extended explanation of direnv in the Wiki too 🌸 (https://zdharma-continuum.github.io/zinit/wiki/Direnv-explanation/)

If you're an examples girlie (same), go check out the zinit-configs repository (https://github.com/zdharma-continuum/zinit-configs) — that's where users have uploaded their ~/.zshrc and their whole Zinit setups. Like, actually feel free to submit (https://github.com/zdharma-continuum/zinit-configs/issues/new?template=request-to-add-zshrc-to-the-zinit-configs-repo.md) your ~/.zshrc there if it's got Zinit commands in it 👑

Also!! There's the Gallery of Zinit Invocations (https://zdharma-continuum.github.io/zinit/wiki/GALLERY/) for some extra examples, and two articles on the Wiki showing example setups — one here (https://zdharma-continuum.github.io/zinit/wiki/Example-Minimal-Setup/) and one here (https://zdharma-continuum.github.io/zinit/wiki/Example-Oh-My-Zsh-setup/). Slay.

💅 How to Use

🧊 Ice Modifiers

Okay so the following ice modifiers are the ones you pass (https://zdharma-continuum.github.io/zinit/wiki/Alternate-Ice-Syntax/) to zinit ice ... to get the effects described. And like — the word "ice" literally means something you add, like ice to a drink 🥤, and in Zinit it means adding a modifier to the next zinit command. It's also temporary because ice melts — so the modification only lasts for a single next zinit command. Periodt.

Some Ice-modifiers are highlighted, and clicking on them takes you to the appropriate Wiki page for the extended explanation ✨

You may safely assume a given ice works with both plugins and snippets unless it's explicitly stated otherwise 🫶

🧬 Cloning Options

📂 Selection of Files (To Source, ...)

⏳ Conditional Loading

🤫 Plugin Output

  • silent
  • lucid
  • notify

🎀 Completions

  • blockf
  • nocompletions

🏃‍♀️ Command Execution After Cloning, Updating or Loading

🐚 Sticky-Emulation Of Other Shells

  • sh, !sh
  • bash, !bash
  • ksh, !ksh
  • csh, !csh

✨ Others

🔥 Order of Execution

So here's the order of execution of the related Ice-mods, and yes it's a whole choreography, keep up bestie:

atinit -> atpull! -> make'!!' -> mv -> cp -> [compile, unless nocompile is set] -> make! -> atclone/atpull -> make -> cmake -> [compile when nocompile'!'] -> (plugin script loading) -> src -> multisrc -> atload

Compilation runs in one of two phases, and this part is important so like, pay attention 🙈

By default the pick-pointed files are compiled early — right after cp, and before the atclone/atpull hooks run — so files already present in the repository (or moved into place by mv/cp) get compiled automatically. A file that's created by an atclone or atpull hook does not exist yet at that point, so the default compile just skips it, no cap.

Passing the bang form nocompile'!' disables the early compile and defers compilation to a second phase that runs after make'' and atclone''/atpull'', once the generated file actually exists (see the nocompile ice).

Bare nocompile disables compilation entirely. And make'!!' is the extra-early make phase before mv/cp/extract and the default compile phase 🫶

🛠 Zinit Commands

These are the commands you pass to zinit ... to get the described effects 💫

❓ Help

  • -h, --help, help
  • man

🔄 Loading and Unloading

  • load {plg-spec}
  • light [-b] {plg-spec}
  • unload [-q] {plg-spec}
  • snippet [-f] {url}

🎀 Completions

  • clist [columns], completions [columns]
  • cdisable {cname}
  • cenable {cname}
  • creinstall [-q] [-Q] {plg-spec}
  • cuninstall {plg-spec}
  • csearch
  • compinit
  • cclear
  • cdlist
  • cdreplay [-q]
  • cdclear [-q]

👀 Tracking of the Active Session

  • dtrace, dstart
  • dstop
  • dunload
  • dreport
  • dclear

📊 Reports and Statistics

  • times [-s] [-m]
  • zstatus
  • report {plg-spec}\|--all
  • loaded [keyword], list [keyword]
  • ls
  • status {plg-spec}\|URL\|--all
  • recently [time-spec]
  • bindkeys

🏗 Compiling

  • compile {plg-spec}\|--all
  • uncompile {plg-spec}\|--all
  • compiled

🌈 Other

  • self-update
  • update [-q] [-r] {plg-spec}\|URL\|--all
  • ice <ice specification>
  • delete {plg-spec}\|URL\|--clean\|--all
  • cd {plg-spec}
  • edit {plg-spec}

⬆️ Updating Zinit and Plugins

To update Zinit, just drop zinit self-update in the command line. Easy 💅

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

Some plugins require you to perform an action each time they're updated. One way you can do this is with 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 info 🫶

The ice modifiers for any plugin or snippet are stored in their directory in a ._zinit subdirectory, which means the plugin doesn't have to be loaded to be correctly updated. Iconic behaviour honestly. There's one other file created there too — .zinit_lstupd — and it holds the log of the new commits pulled in during the last update 📝

🌸 COMPLETIONS 🌸

okay bestie, this is the part where everyone gets confused, so let's go slowly 💅

✨ Calling compinit Without Turbo Mode ✨

So if you're not using Turbo mode at all, you can just call compinit like a normal person, i.e. autoload compinit; compinit. Two things tho: do it after all your plugins are loaded, and before you maybe call zinit cdreplay. Order matters, bestie, don't come for me 😭

Now, the cdreplay subcommand exists so you can re-play all the catched compdef calls. And what's a compdef call? It's how you define a completion for a command. Like, compdef _git git literally means "the git command should be completed by a _git function". Iconic, honestly.

The compdef function is provided by the compinit call. But since compinit should be called later — after all the plugins load — Zinit ships its own compdef function that catches (i.e. records in an array) the arguments of the call, so your loaded plugins can just freely call compdef without dying. Then cdreplay (compdef-replay) can be used, after compinit has been called (and the original compdef function becomes available), to execute all the detected compdef calls. To summarize:

ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}/zinit/zinit.git"
source "${ZINIT_HOME}/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')

The whole point? You get to call compinit once. And the performance gains are huge — like, example shell startup time with double compinit: 0.980 sec, with cdreplay and a single compinit: 0.156 sec. That's not a glow-up, that's a whole transformation 💖

✨ Calling compinit With Turbo Mode ✨

If you're loading completions with the wait'' Turbo mode, then you can add atinit'zicompinit' to your syntax-highlighting plugin (which should be the last one loaded, as their docs state — that's the two projects, z-sy-h at https://github.com/zsh-users/zsh-syntax-highlighting & f-sy-h at https://github.com/zdharma-continuum/fast-syntax-highlighting), or atload'zicompinit' to your last completion-related plugin.

So what's zicompinit? It's just a function that runs autoload compinit; compinit, made for convenience. You're welcome 🫶

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 a normal compinit call, except it happens in the atinit or atload hook of the last related plugin, using the helper functions (zicompinit, zicdreplay & zicdclear — see below for what that last one does). To summarize:

ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share/zinit}"
source "${ZINIT_HOME}/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 ✨

Lowkey wanna ignore the compdefs some plugin or snippet brings? Then place their load commands before the commands that load your other plugins/snippets, and issue zinit cdclear (or zicdclear, designed to be used in hooks like atload''):

ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}/zinit/zinit.git"
source "${ZINIT_HOME}/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

And the cdreplay is important if you use plugins like OMZP::kubectl or asdf-vm/asdf, because those plugins call compdef. Don't skip it bestie, your completions will simply not exist 😭

✨ Disabling System-Wide compinit Call (Ubuntu) ✨

On Ubuntu, users might get surprised that e.g. their completions work even though they never called compinit in their .zshrc. That's because the function is being called in /etc/zshrc. Rude, honestly.

To disable this call — which is needed to avoid the slowdown, and honestly if you load 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 🦋

Heads up: the module is now hosted in its own repository (https://github.com/zdharma-continuum/zinit-module). It moved out, it's got main character energy now, respect it 💅

🌈 Hints and Tips 🌈

✨ Customizing Paths ✨

The following variables can be set to custom values, before sourcing Zinit. And listen — the previous global variables like $ZPLG_HOME have been removed so they don't pollute the namespace. There's a single $ZINIT hash instead of 8 string variables. So please update your dotfiles, bestie, this is not optional 🙈

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

Here's every field, no gatekeeping:

  • ZINIT[BIN_DIR] — Where Zinit code resides, e.g.: ~/.local/share/zinit/zinit.git
  • ZINIT[HOME_DIR] — Where Zinit should create all working directories, e.g.: ~/.local/share/zinit
  • ZINIT[MAN_DIR] — Directory where plugins can store their manpages (atclone"cp -vf myplugin.1 $ZINIT[MAN_DIR]/man1"). If overridden, this directory will not necessarily be used by man (See #8). Default: $ZPFX/man
  • 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
  • ZINIT[OPTIMIZE_OUT_DISK_ACCESSES] — If set to 1, then Zinit will skip checking if a Turbo-loaded object exists on the disk. By default Zinit skips Turbo for non-existing objects (plugins or snippets) to install them before the first prompt — without any delays, during the normal processing of zshrc. This option can give a performance gain of about 10 ms out of 150 ms (i.e.: Zsh will start up in 140 ms instead of 150 ms).
  • ZINIT[NO_ALIASES] — If set to 1, then Zinit will not set aliases such as zi or zini

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

✨ Non-GitHub (Local) Plugins ✨

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

But if the user name is not _local, then Zinit will create the repository on GitHub too and set up the correct repository origin. Fancy ✨

✨ 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 a 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 (https://github.com/zdharma-continuum/zinit-annex-bin-gem-node):

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 (~/.local/share/zinit/polaris by default). Obsessed with this whole setup honestly 🎀

👑 Supporting 👑

Zinit is a personal, free-time project with no funding and a huge feature request backlog (https://github.com/zdharma-continuum/zinit/issues). If you love it, consider supporting its development via GitHub Sponsors [pending]. Any help counts! Fr fr, even the tiniest bit 🫶

🧚 Getting Help and Community 🧚

Do you need help or wish to get in touch with other Zinit users? Bestie, come hang out:

and that's the whole page, you made it to the end!! 🥳 this was the ZINIT(1) manpage, and the little footer vibe down there is just the source/version + date situation — consider this your cute lil sign-off from me to you. go forth and have the fastest shell on the block 💖✨💅

📦 where this page comes from