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

News
Zinit
Zinit Wiki
Quick Start
- Install
  - Automatic Installation (Recommended)
  - Manual Installation
- Usage
How to Use
Completions
Zinit Module
Hints and Tips
Supporting
Getting Help and Community

News

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

16-07-2020
- A new ice null which works exactly the same as as"null", i.e.: it makes the plugin a null-one ↔ without any scripts sourced (by default, unless src'' or multisrc'' are given) and compiled, and without any completions searched / installed. Example use case:
```
zi null sbin"vims" for MilesCranmer/vim-stream
```
  instead of:
```
zi as"null" sbin"vims" for MilesCranmer/vim-stream
```
  .
- A new annex Unscope :) It's goal is: to allow the usage of the unscoped — i.e.: given without any GitHub user name — plugin IDs. Basically it allows to specify, e.g.: zinit load zsh-syntax-highlighting instead of zinit load zsh-users/zsh-syntax-highlighting. It'll automatically send a request to the GitHub API searching for the best candidate (max. # of stars and of forks). It also has an embedded, static database of short nicknames for some of the plugins out there (requests for addition are welcomed), e.g.: vi-reg for zsh-vi-more/evil-registers.
- A fresh and elastic hook-based architecture has been implemented and deployed — the code is much cleaner and the development will be easier, i.e.: quicker :).
- Set of small improvements: a) silent'' mutes the Snippet not loaded error message, b) much shorter lag/pause after a plugin installation or update, c) the 256 color palette is being now used for plugin IDs, if available, d) if possible (a UTF-8 locale is needed to be set), the Unicode three-dots … will be used instead of ... in the messages, e) nicer snippet IDs in the installation and update messages, f) the annexes can be now loaded in any order without influencing their operation in any way (there have been some issues with Patch-Dl and As-Monitor annexes), g) compile'' can now obtain multiple patterns separated via semicolon (;).
25-06-2020
- Ability to call the autoloaded function at the moment of loading it by autoload'#fun', i.e.: by prefixing it with the hash sigh (#). So that it's possible to invoke e.g.:
```
zinit autoload'#manydots-magic' for knu/zsh-manydots-magic
```
  instead of:
```
zinit autoload'manydots-magic' atload'manydots-magic' for \
    knu/zsh-manydots-magic
```
20-06-2020
- The Bin-Gem-Node annex now has an explicit Cygwin support — it creates additional, extra shim files — Windows batch scripts that allow to run the shielded applications from e.g.: Windows run dialog — if the ~/.zinit/polaris/bin directory is being added to the Windows PATH environment variable, for example (it is a good idea to do so, IMHO). The Windows shims (shims are command-wrapper scripts that are in general created with the sbin'' ice of the annex) have the same name as the standard ones (which are also being created, normally) plus the .cmd extension. You can test the feature by e.g.: installing Firefox from the Zinit package via:
```
zinit pack=bgn for firefox
```
- All cURL progress bars are now guaranteed to be single line — this is being done by a wrapper script.
- I thought that I'll share an interesting function-type that I'm using within Zinit - a function that outputs messages with theming and colors easily available:
```
typeset -gA COLORS=(
    col-error  $'\e[31m'
    col-file   $'\e[38;5;110m'
    col-url    $'\e[38;5;45m'
    col-meta   $'\e[38;5;221m'
    col-meta2  $'\e[38;5;154m'
    col-data   $'\e[38;5;82m'
    col-data2  $'\e[38;5;50m'
    col-rst    $'\e[0m'
    col-can-be-empty ""
)

m() {
    builtin emulate -LR zsh -o extendedglob
    if [[ $1 = -* ]] { local opt=$1; shift } else { local opt }
    local msg=${(j: :)${@//(#b)([\[\{]([^\]\}]##)[\]\}])/${COLORS[col-$match[2]]-$match[1]}}}
    builtin print -Pr ${opt:#--} -- $msg
}
```
  Usage is as follows:
```
m "{error}ERROR:{rst} The {meta}data{rst} has the value: {data}value{rst}"
```
  Effect:
  
  The function is available in the atinit'', atload'', etc. hooks.
17-06-2020
- ziextract and extract'' now support Windows installers — currently the installer of Firefox. Let me know if any of your installers doesn't work. You can test the installer with the Firefox Developer Edition Zinit package:
```
zinit pack"bgn" for firefox-dev
```
  The above command will work on Windows (at least on Cygwin), Linux and OS X.
13-06-2020
- ziextract has a new --move2 option, which moves files two levels up after unpacking. For example, if there will be an archive file with directory structure: Pulumi/bin/{pulumi,pulumi2}, then after ziextract --move2 --auto there will be the two files moved to the top level dir: ./{pulumi,pulumi2}. To obtain the same effect using the extract'' ice, pass two exclamation marks, i.e.: extract'!!'. A real-world example — it uses z-a-as-monitor and z-a-bin-gem-node annexes to download a Zip package that has the files inside two-level nested directory tree:
```
zi id-as`pulumi` as`monitor|null` mv`pulumi pulumi_` extract`!` \
    dlink=`https://get.pulumi.com/releases/sdk/pulumi-%VERSION%-windows-x64.zip` \
    sbin`pulumi*` for \
        https://www.pulumi.com/docs/get-started/install/versions/
```
12-06-2020
- New options to update: -s/--snippets and -l/--plugins — they're limiting the update --all to only plugins or snippets. Example:
```
zinit update --plugins
```
  Work also with -p/--parallel.
15-05-2020
- The autoload'' ice can now rename the autoloaded functions, i.e.: load a function from a file func-A as a function func-B via: autoload'func-A -> func-B; …'.
- Also, an alternate autoloading method - via: eval "func-file() { $( — has been exposed — in order to use it, precede the ice contents with an exclamation mark, i.e.: autoload'!func-file'. The rename mode uses this method by default.

  12-05-2020

 A new feature — ability to substitute stringA → stringB in plugin source body before executing by subst'A -> B'. Works also for any nested source commands. Example — renaming the dl'' ice into a dload'' ice in the Patch-Dl annex:

dload''" for zdharma-continuum/z-a-patch-dl ">
zinit subst"dl'' -> dload''" for zdharma-continuum/z-a-patch-dl
 
 A new ice autoload'' which invokes autoload -Uz … on the given files/functions. Example — a plugin that converts cd ... into cd ../.. that lacks proper setup in any *.plugin.zsh file:

zinit as=null autoload=manydots-magic atload=manydots-magic for \
    knu/zsh-manydots-magic
 
 
  09-05-2020

 The from'gh-r' downloading of the binary files from GitHub releases can now download multiple files — if you specify multiple bpick'' ices or separate the patterns with a semicolon (;). Example:

krew" bpick"*.yaml" bpick"*.tar.gz" for \ kubernetes-sigs/krew ">
zinit from"gh-r" as"program" mv"krew-* -> krew" bpick"*.yaml" bpick"*.tar.gz" for \
kubernetes-sigs/krew
 
 A new ice opts'' which takes options to sticky-set during sourcing of the plugin. This means that thee options will be also set for all of the functions that the plugin defines — during their execution (only). The option list is space separated. Example:

# Suppose the example test plugin has the following in test.plugin.zsh:
#
# print $options[kshglob] $options[shglob]
#
# Then:

zinit opts"kshglob noshglob" for zdharma-continuum/test

# Outputs:
on off

# Can mix with the standard emulation-ices: sh, bash, ksh, csh, zsh (the
# default one)

zinit sh opts"kshglob" for zdharma-continuum/test

# Outputs `on' for the SH_GLOB, because sh-emulation sets this option
on on
 
 
  07-05-2020

 A new from'' value is available — cygwin. It'll cause to download a package from the Cygwin repository — from a random mirror, and then unpack it. Example use:

gzip" for gzip ">
# Install gzip and expose it through Bin-Gem-Node annex's sbin'' ice
zinit from"cygwin" sbin"usr/bin/gzip.exe -> gzip" for gzip
 
 
  16-04-2020

Turbo plugins will now get gracefully preinstalled first before the prompt (i.e.: within zshrc processing) and then loaded still as Turbo plugins.
 
  15-04-2020

 The …/name.plugin.zsh and …/init.zsh can be now skipped from single-file (non-svn) snippet URLs utilizing the OMZ::…, etc. shorthands. Example:

# Instead of: zinit for OMZP::ruby/ruby.plugin.zsh
zinit for OMZP::ruby
# Instead of: zinit for PZTM::rails/init.zsh
zinit for PZTM::rails
# Instead of: zinit for OMZT::gnzh.zsh-theme
zinit for OMZT::gnzh
 
 New prefixes OMZP:: = OMZ::/plugins/, OMZT:: = OMZ::/themes/, OMZL:: = OMZ::lib/, PZTM:: = PZT::modules/, for both svn and single-file snippets. Example use:

zinit for OMZP::ruby/ruby.plugin.zsh
zinit svn for OMZP::ruby
 (instead of:

zinit for OMZ::plugins/ruby/ruby.plugin.zsh
zinit svn for OMZ::plugins/ruby
 ).
 
 
  12-04-2020

A new document on the Wiki is available — about the bindmap'' ice.
If id-as'' will have no value, then it'll work as id-as'auto'.
 
  07-04-2020

 A new feature — param'' ice that defines params for the time of loading of the plugin or snippet. E.g.:

# Equivalent of `local myparam=1 myparam2=1' right before loading of the plugin
zinit param'myparam → 1; myparam2 -> 1' for zdharma-continuum/null
# Equivalent of `local myparam myparam2' before loading of the plugin
zinit param'myparam; myparam2' for zdharma-continuum/null
 
 The atinit'' ice can now be investigated — if it'll be prepended with !, i.e.: atinit'!…'.
 
 
  01-04-2020

As a user noticed, Subversion isn't distributed with Xcode Command Line Tools anymore. Here's a helpful snippet that installs Subversion with use of Zinit.
 
  27-02-2020

An important fix has been pushed — due to a bug Turbo has been disabled for non-for syntax invocations of Zinit. Issue zinit self-update to resolve the mistake.

If you haven't updated yesterday, please restrain from running zinit update immediately after self-update. Support for reloading Zinit after self-update has been pushed yesterday and after pulling this feature, you'll be able to freely invoke self-update and update.
 
 
  26-02-2020

From now on zinit self-update reloads Zinit for the current session (after updating the plugin manager), and zinit update --all/-p/--parallel detects that self-update has been run in another session and also reloads Zinit right before performing the update. This way the update code is always the newest and consistent.
 
  26-02-2020

If the loaded object (plugin or snippet) is not already installed when loading, then Turbo gets automatically disabled for this single loading of the object — it'll be installed before prompt, not after it and also immediately (without waiting the number of seconds given to wait''), i.e.: during the normal processing of zshrc, which intuitively is the expected behavior.
The additional disk accesses for the checks cost about 10 ms out of 150 ms (i.e.: the Zsh startup time increases from 140 ms to 150 ms). If you want, you may disable the feature by setting $ZINIT[OPTIMIZE_OUT_DISK_ACCESSES] to 1.
A bug in Turbo has been fixed that was delaying the objects' loadings, especially when there were no keystrokes issued.
 
  20-02-2020

 A new feature - parallel updates of all plugins and snippets — Zinit runs series of spawned concurrent-job groups of size 15 to speed up the update process. To activate, pass -p/--parallel to update, e.g.:

zinit update -p
zinit update --parallel
# Increase the number of jobs in a concurrent-set to 40
zinit update --parallel 40
 See demos: asciicast1, asciicast2.
 
 A new article is available on the Wiki — about the extract ice.
 
 
  19-02-2020
 The project has a fresh, new subreddit r/zinit. You can also visit the old subreddit r/zplugin.
 
  09-02-2020
 Note that the ice extract can handle files with spaces — to encode such a name use the non-breaking space (Right Alt + Space) in place of the in-filename spaces :).
 
  07-02-2020

A new ice extract which extracts:

all files with recognized archive extensions like zip, tar.gz, etc.,
if no such files will be found, then: all files with recognized archive types (examined with the file command),
OR, IF GIVEN — the given files, e.g.: extract'file1.zip file2.tgz',
the automatic searching for archives ignores files in sub-sub-directories and located deeper,
 
It has a ! flag — i.e.: extract'!…' — it'll cause the files to be moved one directory-level up upon unpacking,
and also a - flag — i.e.: extract'-…' — it'll prevent removal of the archive after unpacking; useful to allow comparing timestamps with the server in case of snippet-downloaded file,
the flags can be combined, e.g.: extract'!-',
also, the function ziextract has a new option --auto, which causes the automatic behavior identical to the empty extract ice.
 
  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 zdharma-continuum organization.
 
 
  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, ziextract, 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 ziextract 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.:

exa" sbin"exa" ogham/exa \ mv"fd* -> fd" sbin"fd/fd" @sharkdp/fd \ sbin"fzf" junegunn/fzf-bin ">
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-continuum/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-continuum---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-continuum/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 a flexible and fast Zshell plugin manager that will allow you to install everything from GitHub and other sites. Its characteristics are:

 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.
 
 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.
 
 Supported is unloading of plugin and ability to list, (un)install and selectively disable, enable plugin's completions.
 
 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).
 
 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.
 
 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.
 
 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:

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 ">
# 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"

"
, 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/ (http://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
Importing the clipboard and termsupport Oh-My-Zsh Library Sample:

# 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 created for Oh My Zsh you might want to first source the git library there.
Then you can use the themes as snippets (zinit snippet
). Some themes require not only Oh My Zsh's Git library, but also Git plugin (error about current_branch may appear). Load this Git-plugin as single-file snippet directly from OMZ.
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:

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

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

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

## 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, 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, 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 Oh-My-Zsh setup in the Wiki

 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 and 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, git:

zinit ice svn
zinit snippet PZTM::docker

zinit ice svn
zinit snippet PZTM::git

Use zinit ice as"null" if don't exist *.plugin.zsh, init.zsh, *.zsh-theme* files in module. Like archive:

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

Use zinit ice atclone"git clone


"

 if module have external module. Like 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 zstyle doc (more: 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


" zinit load

# Set prezto options zgen prezto






General
location: refer Selection of Files

">
zgen load <repo> [location] [branch]

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


 Migration from Zplug
Basic


" tag2"

" zinit load

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

zinit ice tag1"
        
         "
         tag2"
        
         "
        
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 bottom. Some examples:

{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 ">
# 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


c.zsh" atpull'%atclone' pick"c.zsh" nocompile'!' zinit light trapd00r/LS_COLORS ">
# 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.

zhook.zsh' atpull'%atclone' src"zhook.zsh" zinit light direnv/direnv ">
# 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



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. Pass empty ice to disable recursive cloning. Does not work with snippets.



pullopts


Pass the contents of pullopts to git pull used when updating plugins. 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 OMZP::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 investigated (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 investigating 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 investigated (meaning gathering report and unload data) once during execution. It works by wrapping the functions with a investigating-enabling and disabling snippet of code. In summary, wrap-track allows to extend the investigating 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 investigating, 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



extract


Performs archive extraction supporting multiple formats like zip, tar.gz, etc. and also notably OS X dmg images. If it has no value, then it works in the auto mode – it automatically extracts all files of known archive extensions IF they aren't located deeper than in a sub-directory (this is to prevent extraction of some helper archive files, typically located somewhere deeper in the tree). If no such files will be found, then it extracts all found files of known type – the type is being read by the file Unix command. If not empty, then takes names of the files to extract. Refer to the Wiki page for further information.



subst


Substitute the given string into another string when sourcing the plugin script, e.g.: zinit subst'autoload → autoload -Uz' ….



autoload


Autoload the given functions (from their files). Equvalent to calling atinit'autoload the-function'. Supports renaming of the function – pass '… → new-name' or '… -> new-name', e.g.: zinit autoload'fun → my-fun; fun2 → my-fun2'.



 
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/investigating. -b – investigate bindkey-calls only. There's also light-mode ice which can be used to induce the no-investigating (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). The URL can use the following shorthands: PZT:: (Prezto), PZTM:: (Prezto module), OMZ:: (Oh My Zsh), OMZP:: (OMZ plugin), OMZL:: (OMZ library), OMZT:: (OMZ theme), e.g.: PZTM::environment, OMZP::git, etc.



 
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] [-Q] {plg-spec}


Install completions for plugin, can also receive absolute local path. -q – quiet. -Q - quiet all.



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 investigating what's going on in session.



dstop


Stop investigating 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



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




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


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


 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

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. Pass empty ice to disable recursive cloning. Does not work with snippets.
`pullopts`	Pass the contents of `pullopts` to `git pull` used when updating plugins. 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 OMZP::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.

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.

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 `;`.

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.

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}`.

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 investigated (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 *`.

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.

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 investigating 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 investigated (meaning gathering report and unload data) once during execution. It works by wrapping the functions with a investigating-enabling and disabling snippet of code. In summary, `wrap-track` allows to extend the investigating 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 investigating, 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
`extract`	Performs archive extraction supporting multiple formats like `zip`, `tar.gz`, etc. and also notably OS X `dmg` images. If it has no value, then it works in the auto mode – it automatically extracts all files of known archive extensions IF they aren't located deeper than in a sub-directory (this is to prevent extraction of some helper archive files, typically located somewhere deeper in the tree). If no such files will be found, then it extracts all found files of known type – the type is being read by the `file` Unix command. If not empty, then takes names of the files to extract. Refer to the Wiki page for further information.
`subst`	Substitute the given string into another string when sourcing the plugin script, e.g.: `zinit subst'autoload → autoload -Uz' …`.
`autoload`	Autoload the given functions (from their files). Equvalent to calling `atinit'autoload the-function'`. Supports renaming of the function – pass `'… → new-name'` or `'… -> new-name'`, e.g.: `zinit autoload'fun → my-fun; fun2 → my-fun2'`.

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

Command	Description
`load {plg-spec}`	Load plugin, can also receive absolute local path.
`light [-b] {plg-spec}`	Light plugin load, without reporting/investigating. `-b` – investigate `bindkey`-calls only. There's also `light-mode` ice which can be used to induce the no-investigating (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). The URL can use the following shorthands: `PZT::` (Prezto), `PZTM::` (Prezto module), `OMZ::` (Oh My Zsh), `OMZP::` (OMZ plugin), `OMZL::` (OMZ library), `OMZT::` (OMZ theme), e.g.: `PZTM::environment`, `OMZP::git`, etc.

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] [-Q] {plg-spec}`	Install completions for plugin, can also receive absolute local path. `-q` – quiet. `-Q` - quiet all.
`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.

Command	Description
`dtrace, dstart`	Start investigating what's going on in session.
`dstop`	Stop investigating 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.

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.

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.

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

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

[bug]: Choosing version track such as Nightly as the version to stay on
Describe the bug

Hello, I have something like this (which I think there's redundant keywords in it):

zi ice lucid cloneonly from"gh-r" bpick"*linux-gnu.gz" mv"rust-analyzer-* -> rust-analyzer" fbin"rust-analyzer" zi light "rust-lang/rust-analyzer"

The problem is if there's a Nighly update, the Release version is updated once to the Nightly version and now it hasn't updated to a newer Nightly version. How can I make sure it either updates to a newer Nightly, or only updates to stable Releases?

Steps to reproduce

Add above snippet to .zshrc

Reload terminal to install

Expected behavior

Update to latest Nightly, or stay on Stable

Screenshots and recordings

No response

OS / Linux distribution

Linux void 5.16.20_1 #1 SMP PREEMPT Thu Apr 14 17:43:53 UTC 2022 x86_64 GNU/Linux

Zsh version

5.8.1

Terminal emulator

foot

If using WSL on Windows, which version of WSL

No response

Additional context

No response
bug
opened by mustaqimM 26
Add a new ice named "link", enabling local snippets to be symlinked instead of copied into the cache.
Description

Add a new ice named "link", enabling local snippets to be symlinked instead of copied into the cache.

Motivation and Context

For those of us who keep our entire dotfiles in a git repo (dotbare, etc.), we often want to treat many of our rc files as snippets that can be managed by zinit. This is great for taking advantage of features such as trigger-load, if, or has ices. I used to use local plugins for this but noticed that the load times for plugins were significantly longer than snippets.

In migrating to snippets, I found that copying files from a source path into the ZINIT_SNIPPETS directory meant that I had to run zinit update [snippet] for any changes that I may make to my rc files to take effect. This ice replaces the cp command with ln, which instantly reflects changes with a new shell. I thought that snippets, in combination with symlinks, are an effective way to manage a lot of low-level rc file stuff that doesn't necessarily need to be in a separate git repository of its own.

Usage examples

Given:

$ cat ~/.dotfiles/zsh/aliases/general.zsh alias ls=' ls --color=tty --group-directories-first' alias ll='ls -lFh' alias l='ll' alias la='ll -A' alias lt='ll -t' alias lr='ll -R' alias ltr='ll -tr'

In your zshrc:

zinit light-mode is-snippet link for \ id-as'aliases-general' \ ~/.dotfiles/zsh/aliases/general.zsh \

The 'aliases-general' snippet will be symlinked in the zinit snippet dir:

~/.dotfiles/zsh/_snippets/aliases-general $ ls -l lrwxr-xr-x 26 user 27 Dec 2021 aliases-general -> ../../aliases/_general.zsh

Load times are much improved:

Plugin loading times: -104 ms 3 ms - aliases-general

How Has This Been Tested?

Tests included in PR; I've been using this for months.

Types of changes

[ ] Bug fix (non-breaking change which fixes an issue)

[x] New feature (non-breaking change which adds functionality)

[ ] Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

[x] My change requires a change to the documentation.

[x] I have updated the documentation accordingly.

[x] I have added tests to cover my changes.

[x] All new and existing tests passed.

zinit tests docs
opened by twang817 23
[bug]: commit d59f15 makes `gh-r` select i686 (32 bit) `fd` binary
Describe the bug

$ zinit wait lucid for from"gh-r" as"null" sbin"**/fd" atclone"cp -vf **/*.1 $ZPFX/man/man1" @sharkdp/fd $ fd fd:7: no such file or directory: /home/anupam/.local/share/zinit/plugins/sharkdp---fd/fd-v8.3.2-i686-unknown-linux-gnu/fd

The latest commit downloads i686 binary instead of x86_64. This has been verified on debian (sid, 20220328-962) and Fedora release 36.

Steps to reproduce

zini update

zinit for from"gh-r" as"null" sbin"**/fd" @sharkdp/fd

Run fd

Expected behavior

fd should run without any problem, like it used to

Screenshots and recordings

No response

OS / Linux distribution

linux-gnu redhat x86_64 x86_64 x86_64 x86_64

Zsh version

5.8.1

Terminal emulator

Windows Terminal

If using WSL on Windows, which version of WSL

WSL2

Additional context

No response
bug
opened by anupamsr 18
(bugfix): `gh-r` choosing wrong binary for OS
fix #160

fix zinit selecting Linux version on macOS

fix zinit not selecting musl version on musl systems

add gh-r ice unit tests on Ubuntu & macOS to verify behavior on different OSes

Signed-off-by: Vladislav Doster [email protected]
opened by vladdoster 12

Remove all unicode emojis / symbols from file names

Describe the bug Zinit cannot compile annex since some of the handler files have unicode chars in their names which zcompile does not support. I wonder if we can dance around this issue by making the compile ice dynamically rename files.

Zinit config

zinit light-mode compile'*handler' for \
     zdharma-continuum/zinit-annex-bin-gem-node

Error output

(anon):zcompile:2: can't open file: /home/pschmitt/.local/share/zinit/plugins/zdharma-continuum---zinit-annex-bin-gem-node/\M-b\M-^F\M-^Rza-bgn-atclone-handler                                         
(anon):zcompile:2: can't open file: /home/pschmitt/.local/share/zinit/plugins/zdharma-continuum---zinit-annex-bin-gem-node/\M-b\M-^F\M-^Rza-bgn-atdelete-handler                                        
(anon):zcompile:2: can't open file: /home/pschmitt/.local/share/zinit/plugins/zdharma-continuum---zinit-annex-bin-gem-node/\M-b\M-^F\M-^Rza-bgn-atload-handler                                          
(anon):zcompile:2: can't open file: /home/pschmitt/.local/share/zinit/plugins/zdharma-continuum---zinit-annex-bin-gem-node/\M-b\M-^F\M-^Rza-bgn-help-handler

bug 🌐 ecosystem 🧹 chore ➕ annex

opened by pschmitt 12

Second attempt to enable custom tree for 'zinit ls' command

Enable users to specify the zinit ls command via ZINIT[LIST_COMMAND] and provide default commands for exa and tree. Prefer exa if it is installed.

Addresses issue https://github.com/zdharma-continuum/zinit/issues/170

I cherry-picked the original changes to a clean branch and then updated the docs to attempt to address the documentation action issues.

opened by nbrown 10
gh-r isn't searching for Apple Silicon compatible binaries correctly.
On my new M1 MacBookPro...

The gh-r ice isn't correctly grabbing the right binary packages that are using platform strings like x86_64-apple-darwin (usually Rust apps in my experience). e.g. ripgrep, git-delta, fd, led, and bat.

It's usually finding the linux arm binaries instead.

Here are my environment variables from zsh installed via Home-brew which is version zsh 5.8 (arm-apple-darwin21.1.0):

CPUTYPE=arm64 MACHTYPE=arm OSTYPE=darwin21.1.0

When using /bin/zsh which is zsh 5.8 (x86_64-apple-darwin21.0):

CPUTYPE=arm64 MACHTYPE=x86_64 OSTYPE=darwin21.0

# An example command to cause the issue(s) in question. zinit wait lucid for \ from'gh-r' \ as'program' \ mv'lsd* -> lsd' \ pick'lsd/lsd' \ @Peltoche/lsd

I suspect the way to deal with this is to detect that it is an M1 macOS system and do an arm check then an intel type.

I don't think moving the CPUTYPE up in .zinit-get-latest-gh-r-url-part would be enough. Plus MACHTYPE won't check for amd64 unless it is /bin/zsh. A native zsh won't have any indication that it has Rosetta 2 installed and can handle amd64 binaries.

Yes, I can do experiments for you. :smiley:
bug
opened by docwhat 10
Question: How to migrate from zdharma/zinit?
I used zinit before it was deleted, and I wanted to migrate to the new repository. In ~/.zinit/bin, I ran:

git remote set-url origin https://github.com/zdharma-continuum/zinit.git

It seems to have worked; zinit self-update pulls from the new URL.

Is this the recommended way of migrating? Perhaps some documentation could be added to the README to help other users.
📚 documentation ❔ question ℹ️ faq
opened by tactlessfish 10
MANPATH doesn't have ~/.zinit/polaris/man, also ~/.zinit/polaris/man doesn't exist
Describe the bug ZPFX=~/.zinit/polaris MANPATH doesn't have $ZPFX/man, also $ZPFX/man doesn't exist.

To Reproduce

# requires the zdharma-continuum/z-a-bin-gem-node annex # i'm also using ryaminal/z-a-meta-plugins to bring in the annexes(including the one above), but I don't anticipate this being a problem. zinit wait'0b' lucid for \ id-as'github-cli' from"gh-r" sbin'usr/bin/gh' atclone'ln -sf $PWD/usr/share/man/man1/* $ZPFX/man/man1' atpull'%atclone' cli/cli \ ;

Expected behavior Used to be that a $ZPFX/man directory was created and added to the MANPATH directory, this is the expected behavior.

Additional context Mostly I'm just curious if anyone is familiar with why this wouldn't work? Are others seeing this directory existing and an entry in MANPATH? I've tried to look through the code but nothing is indicating the problem.
opened by ryaminal 10
fix: Don't error if $OPTS is not yet defined in .zinit-compinit call
This codepath was triggered when deleting the whole ~/.ziniti/plugins dir: during recreation in .zinit-prepare-home, .zinit-compinit &> /dev/null would be called and the sourcing of zinit.zsh would error out with

+.zinit-compinit:2> [[.zinit-compinit:2: bad math expression: operand expected at `/Users/jan...' -n '' ]]

As the error was redirected to /dev/null, this never showed up. Any zinit install call during that session would not run any hooks as they were not yet registered. The next session would then be fine because the plugins dir would exist.

Motivation and Context

See https://github.com/zdharma-continuum/zinit/issues/129#issuecomment-1092111737 -> basically deleting the ~/.zinit/plugins dir should result in complete recreation on the next run, but due to this bug, it had bad side effects.

Closes: #129 (probably, not tested on initial run, only after deleting the plugins dir)

How Has This Been Tested?

Manually deleting the whole folder and starting the whole zinit setup from scratch

rm -rf ~/.zinit/plugins/ && exec zsh

Types of changes

[x] Bug fix (non-breaking change which fixes an issue)

Checklist:

[ ] My change requires a change to the documentation.

[ ] I have updated the documentation accordingly.

[ ] I have added tests to cover my changes.

[ ] All new and existing tests passed.

zinit
opened by jankatins 9

🐞 bug: `__git_zsh_bash_func:9: command not found: __git_aliased_command` when calling `zicompinit`

Issue description

Any time I call zicompinit, git's completion gets polluted by errors.

% git com<TAB>
_git:.:42: no such file or directory:

% git commit<TAB>
% git commit __git_zsh_bash_func:9: command not found: __git_aliased_command
  git commit

git version 2.31.1

zinit config

# Zinit
# sh -c "$(curl -fsSL https://git.io/zinit-install)"
### Added by Zinit's installer
if [[ ! -f $HOME/.local/share/zinit/zinit.git/zinit.zsh ]]; then
    print -P "%F{33} %F{220}Installing %F{33}ZDHARMA-CONTINUUM%F{220} Initiative Plugin Manager (%F{33}zdharma-continuum/zinit%F{220})…%f"
    command mkdir -p "$HOME/.local/share/zinit" && command chmod g-rwX "$HOME/.local/share/zinit"
    command git clone https://github.com/zdharma-continuum/zinit "$HOME/.local/share/zinit/zinit.git" && \
        print -P "%F{33} %F{34}Installation successful.%f%b" || \
        print -P "%F{160} The clone has failed.%f%b"
fi

source "$HOME/.local/share/zinit/zinit.git/zinit.zsh"
autoload -Uz _zinit
(( ${+_comps} )) && _comps[zinit]=_zinit

# Load a few important annexes, without Turbo
# (this is currently required for annexes)
zinit light-mode for \
    zdharma-continuum/zinit-annex-as-monitor \
    zdharma-continuum/zinit-annex-bin-gem-node \
    zdharma-continuum/zinit-annex-patch-dl \
    zdharma-continuum/zinit-annex-rust

# Plugins
# https://github.com/zdharma-continuum/fast-syntax-highlighting#zinit
zinit wait lucid light-mode for \
    atinit"ZINIT[COMPINIT_OPTS]=-C; zicompinit; zicdreplay" \
        zdharma-continuum/fast-syntax-highlighting

zinit version or commit ID

19347bad3b3a09f9b6344225ea338c63888eae70

zsh version

5.8

bug 🎲 triage

opened by paw-lu 9

[bug]: `gh-r` selection broken for volta-cli/volta `x86_64` macOS binary
Describe the bug

See following issues:

https://github.com/chalkygames123/dotfiles/issues/1

https://github.com/zdharma-continuum/zinit/issues/179

Steps to reproduce

Use gh-r ice and attempt to install Volta CLI on macOS M1 & Intel variants.

Expected behavior

Download the Volta binary for the correct CPU architecture.

Screenshots and recordings

N/A

OS / Linux distribution

N/A

Zsh version

N/A

Terminal emulator

N/A

If using WSL on Windows, which version of WSL

No response

Additional context

N/A
bug
opened by vladdoster 0
fix: fix triggers and brew ncurses installationrun for unit tests
Signed-off-by: Vladislav Doster [email protected]

Description

Motivation and Context

Usage examples

How Has This Been Tested?

Types of changes

[ ] Bug fix (non-breaking change which fixes an issue)

[ ] New feature (non-breaking change which adds functionality)

[ ] Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

[ ] My change requires a change to the documentation.

[ ] I have updated the documentation accordingly.

[ ] I have added tests to cover my changes.

[ ] All new and existing tests passed.

ci/cd zinit scripts tests
opened by vladdoster 7
[bug]: `zinit delete` defaults to deleting the snippets directory #214
Describe the bug

Issue description

~ ᐳ zi delete Delete /Users/anonymous/.local/share/zsh/zinit/snippets/? (it holds: OMZL::clipboard.zsh, OMZL::compfix.zsh, OMZL::completion.zsh, OMZL::git.zsh, more…) [yY/n…] y Done (action executed, exit code: 0)

zinit config

N/A

zinit version or commit ID

N/A

zsh version

N/A

host info

N/A

Steps to reproduce

Run:

zinit delete

Expected behavior

Delete nothing and print usage

Prompt the user with the choice of Zinit directories to delete.

Screenshots and recordings

No response

OS / Linux distribution

N/A

Zsh version

N/A

Terminal emulator

N/A

If using WSL on Windows, which version of WSL

No response

Additional context

N/A
bug
opened by vladdoster 0
[maint]: improve readability of Zinit source code
Summary

Inconsistent line length & wrapping, making it hard to read, grok, and edit Zinit.

Examples:

zinit-install.zsh#L4

zinit-install.zsh#L995

zinit-install.zsh#L1848

Proposed fix

Add the following Vim Modeline to all Zinit source code:

vim: ft=zsh et ts=2 sw=2
opened by vladdoster 2

fix: don't escape exclamation marks in hook keys

Exclamation marks (per default) get escaped in interactive mode, but not in non-interactive modes. In this case it meant that zinit would not find any hooks which implements the ices when running in non-interactive mode (e.g. in a script). This in turn would NOT result in errors but would just silently not execute any of the ices which of course would be a bad thing(tm).

Description

This a) disables history mark expansion during hook register and changes any search pattern to not include the (double) escaped exclamation mark

Motivation and Context

It broke using zinit calls with ices in scripts (e.g. from a $HOME bootstrap script or an update script)

https://github.com/zdharma-continuum/zinit/issues/199 has the details...

Closes: #199

How Has This Been Tested?

Running the same ice (mv in this case) interactively and in a script. Both calls contain the direnv.darwin-amd64 -> direnv log line.


[16:30:23] λ  zinit delete direnv/direnv -y ; zsh -i -c -f --no-rcs 'source ~/.zinit/bin/zinit.zsh ; source ~/.zinit/bin/zinit-install.zsh; zinit from"gh-r" mv"direnv* -> direnv" for direnv/direnv'
bin-gem-node annex: The direnv shim didn't exist in $ZPFX/bin (or isn't a regular file)

Done (action executed, exit code: 0)

Downloading direnv/direnv…
(Requesting `direnv.darwin-amd64'…)
#################################################################################################################################################################################################################### 100.0%
ziextract: Successfully extracted and assigned +x chmod to the file: `direnv.darwin-amd64'.
direnv.darwin-amd64 -> direnv
No files for compilation found.
Warning: ∞zinit-compile-plugin-hook hook returned with 1


[16:30:29] [1] ✗  ls -la ~/.zinit/plugins/direnv---direnv/direnv*
-rwxr-xr-x  1 jankatins  staff  8811104 Apr 25 16:30 /Users/jankatins/.zinit/plugins/direnv---direnv/direnv


[16:30:37] λ  zinit delete direnv/direnv -y ; source ~/.zinit/bin/zinit.zsh ; source ~/.zinit/bin/zinit-install.zsh; zinit from"gh-r" mv"direnv* -> direnv" for direnv/direnv
bin-gem-node annex: The direnv shim didn't exist in $ZPFX/bin (or isn't a regular file)

Done (action executed, exit code: 0)

Downloading direnv/direnv…
(Requesting `direnv.darwin-amd64'…)
#################################################################################################################################################################################################################### 100.0%
ziextract: Successfully extracted and assigned +x chmod to the file: `direnv.darwin-amd64'.
direnv.darwin-amd64 -> direnv
No files for compilation found.
Warning: ∞zinit-compile-plugin-hook hook returned with 1

[16:31:02] [1] ✗  ls -la ~/.zinit/plugins/direnv---direnv/direnv*
-rwxr-xr-x  1 jankatins  staff  8811104 Apr 25 16:31 /Users/jankatins/.zinit/plugins/direnv---direnv/direnv

Types of changes

[x] Bug fix (non-breaking change which fixes an issue)
[ ] New feature (non-breaking change which adds functionality)
[ ] Breaking change (fix or feature that would cause existing functionality to change)

Checklist:

[ ] My change requires a change to the documentation.
[ ] I have updated the documentation accordingly.
[ ] I have added tests to cover my changes.
[ ] All new and existing tests passed.

ci/cd zinit tests docs

opened by jankatins 21

🎁 Feature request: Allow for checksum

Feature request

It would be nice to have a method to validate checksums. Perhaps it's should be an annex but I think having it built-in seems more reasonable.

There's a certain format many people use when uploading binaries (at least, to GitHub). It's usually along the lines of <filename>.<sum>, and potentially a <filename>.sig file too. From there zinit can then validate using the relevant binaries, and if a .sig is available, a key is provided, and GPG binaries are available, zinit can create a new gpg home directory, import the key from a keyserver and then validate the binaries.

opened by hoshsadiq 0