ZI(1)

📦 version 1.0.0-unstable-2022-04, in nixpkgs unstable

🎀 ZI(1) 🎀

okay bestie, so this is the manual page for ZI — literally the whole thing, section by section, and I'm gonna walk you through every single bit of it because you deserve to know. no skimming, no "you'll figure it out", we're doing this properly. 💅

✨ NEWS ✨

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

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

🗓 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.:
zi ice id-as"auto"
zi load robobenklein/zinc

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

🗓 14-09-2019

🗓 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 ZI, provided that the emulation level done by Zsh is sufficient, e.g.:
zi ice bash pick"bash_it.sh" \
        atinit"BASH_IT=${ZPLGM[PLUGINS_DIR]}/Bash-it---bash-it" \
        atclone"yes n | ./install.sh"
zi 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. 😭 (so close, bestie)

🗓 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 ZI annexes (i.e. extensions (http://z-shell.github.io/zi/wiki/Annexes/)):

Generates man pages and code-documentation man pages from plugin's README.md and source files (the code documentation is obtained from Zshelldoc (https://github.com/z-shell/zshelldoc)).

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

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 ZI should be cloned. 🫶

🗓 09-08-2019

  • A new ice-mod wrap-track'' which gets ;-separated list of functions that are to be tracked once when executing. In other words you can extend the tracking beyond the moment of loading of a plugin.
  • The unloading of Zle widgets is now more smart – it takes into account the chains of plugins that can overload the Zle widgets, and solves the interactions that result out of it. ✨

🗓 29-07-2019

  • delete now supports following options:
    • --all – deletes all plugins and snippets (a purge, similar to rm -rf ${ZPLGM[PLUGINS_DIR]} ${ZPLGM[SNIPPETS_DIR]})
    • --clean – deletes only plugins and snippets that are currently not loaded in the current session.
ngl --all is giving "no thoughts, head empty, everything gone" energy. use it on purpose, bestie. 💀

🗓 09-07-2019

  • ZI can now have its own plugins, called z-plugins! Check out an example but fully functional z-plugin z-shell/z-a-submods (https://github.com/z-shell/z-a-submods) and a document that explains on how to implement your own z-plugin (here (../../wiki/Z-PLUGINS)).

🗓 08-07-2019

  • You can now do zi ice wait ... and it will work as zi ice wait'0' ... :) I.e. when there's no value to the wait'' ice then a value of 0 is being substituted. 😌

🗓 02-07-2019

🗓 01-07-2019

  • atclone'', atpull'' & make'' get run in the same subshell, thus an e.g. export done in atclone'' will be visible during the make. 💅

🗓 26-06-2019

  • notify'' contents gets evaluated, i.e. can contain active code like $(tail -1 /var/log/messages), etc.

🗓 23-06-2019

  • New ice mod subscribe''/on-update-of'' which works like the wait'' ice-mod, i.e. defers loading of a plugin, but it looks at modification time of the given file(s), and when it changes, it then triggers loading of the plugin/snippet:
% zi ice on-update-of'{~/files-*,/tmp/files-*}' lucid \
    atload"echo I have been loaded" \
    notify"Yes that's true :)"
% zi load z-shell/null
% touch ~/files-1
The plugin has been loaded
%
Yes that's true :)

The plugin/snippet will be sourced as many times as the file gets updated. 🔥

🗓 22-06-2019

  • New ice mod reset-prompt that will issue zle .reset-prompt after loading the plugin or snippet, causing the prompt to be recomputed. Useful with themes & Turbo mode.
  • New ice-mod notify'' which will cause to display an under-prompt notification when the plugin or snippet gets loaded. E.g.:
% zi ice wait"0" lucid notify"z-shell/null has been loaded"
% zi light z-shell/null
%
z-shell/null has been loaded

In case of problems with the loading a warning message will be output:

% zi ice notify atload'return 7'
% zi light z-shell/null
%
notify: Plugin not loaded / loaded with problem, the return code: 7

Refer to Ice Modifiers (Ice Modifiers) section for a complete description.

🗓 29-05-2019

  • Turbo mode, i.e. the wait'' ice-mode now supports a suffix – the letter a, b or c. The meaning is illustrated by the following example:
zi ice wait"0b" as"command" pick"wd.sh" atinit"echo Firing 1" lucid
zi light mfaerevaag/wd
zi ice wait"0a" as"command" pick"wd.sh" atinit"echo Firing 2" lucid
zi light mfaerevaag/wd

# The output
Firing 2
Firing 1

As it can be seen, the second plugin has been loaded first. That's because there are now three sub-slots (the a, b and c) in which the plugin/snippet loadings can be put into. Plugins from the same time-slot with suffix a will be loaded before plugins with suffix b, etc.

In other words, instead of wait'1' you can enter wait'1a', wait'1b' and wait'1c' – to this way impose order on the loadings regardless of the order of zi commands. 🧚

To see the full history check the changelog (CHANGELOG.md).

👑 ZI 👑

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

ZI is currently the only plugin manager out there that has Turbo mode which yields 50-73% faster Zsh startup! 🔥

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

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

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

🦋 ZI WIKI 🦋

The information in this README is complemented by the ZI wiki (http://z-shell.github.io/zi/wiki/). The README is an introductory overview of ZI while the wiki gives a complete and in-depth information with examples. Make sure to read it to get the most out of ZI. 💖

okay so the easiest way to install ZI — like, genuinely the one everyone does — is to run this bad boy:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/z-shell/zi/main/lib/install.sh)"

That slays it into ~/.zi/bin. Your .zshrc gets updated too, bestie — three lines of code get tacked onto the bottom. Those lines source zi.zsh and set up completion for the command zi. That's it, that's the whole vibe.

After installing and reloading the shell, compile ZI with zi self-update ✨

🦋 Option 2 - Manual Installation 🦋

okay so you're a do it myself girlie, respect. To manually install ZI, clone the repo to e.g. ~/.zi/bin:

mkdir ~/.zi
git clone https://github.com/z-shell/zi.git ~/.zi/bin

and then source it from .zshrc — above compinit, bestie, this matters:

source ~/.zi/bin/zi.zsh

If you place the source below compinit instead (no judgment, but like… pay attention here), then add these two lines right after the source:

autoload -Uz _zi
(( ${+_comps} )) && _comps[zi]=_zi

Lowkey there are so many various paths you can customize — peep the section Customizing Paths (Customizing Paths) for that whole situation 💅

After installing and reloading the shell, compile ZI with zi self-update.

🌈 USAGE 🌈

⭐ Introduction ⭐

Click here to read the introduction to ZI — it's at http://z-shell.github.io/zi/wiki/INTRODUCTION/ 🫶

It explains basic usage and some of the more unique features of ZI such as the Turbo mode. If you're new to ZI we highly recommend you read it at least once. Fr fr, read it. It's giving essential.

💜 Example Usage 💜

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

# Two regular plugins loaded without tracking.
zi light zsh-users/zsh-autosuggestions
zi light z-shell/F-Sy-H

# Plugin history-search-multi-word loaded with tracking.
zi load z-shell/history-search-multi-word

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

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

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

# Vim repository on GitHub – a typical source code that needs compilation – ZI
# 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://z-shell.github.io/zi/wiki/Compiling-programs
zi ice as"program" atclone"rm -f src/auto/config.cache; ./configure" \
    atpull"%atclone" make pick"src/vim"
zi 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.
zi ice as"program" pick"$ZPFX/bin/git-*" make"PREFIX=$ZPFX"
zi light tj/git-extras

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

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

You can see an extended explanation of LS_COLORS in the wiki, at http://z-shell.github.io/zi/wiki/LS_COLORS-explanation/ 🌸

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

You can see an extended explanation of direnv in the wiki, at http://z-shell.github.io/zi/wiki/Direnv-explanation/ 🌟

If you're interested in more examples then check out the zi-configs repository at https://github.com/z-shell/zi-configs, where users have uploaded their ~/.zshrc and ZI configurations. Feel free to submit yours at https://github.com/z-shell/zi-configs/issues/new?template=request-to-add-zshrc-to-the-zi-configs-repo.md — like, if your ~/.zshrc contains ZI commands, drop it there 👑

You can also check out the Gallery of ZI Invocations at http://z-shell.github.io/zi/wiki/GALLERY/ for some additional examples. It's giving inspiration, ngl.

🧊 Ice Modifiers 🧊

Okay so the following ice modifiers are the ones you pass to zi ice ... to get the described effects. And like — why "ice"? The word ice means something that's added (like ice to a drink) 🍹 — and in ZI it means adding a modifier to a next zi command, and also something that's temporary because it melts. So the modification lasts only for a single next zi command. Blink and it's gone, bestie 💅

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

  • 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. zi ice from"gh-r" as"program" bpick"*Darwin*"; zi load docker/compose. Does not work with snippets.
  • depth — Pass --depth to git, i.e. limit how much of history to download. Does not work with snippets.
  • cloneopts — Pass the contents of cloneopts to git clone. Defaults to --recursive i.e. Change cloning options. Does not work with snippets.
  • svn — Use Subversion for downloading snippet. GitHub supports SVN protocol, this allows to clone subdirectories as snippets, e.g. zi ice svn; zi snippet OMZ::plugins/git. Other ice pick can be used to select file to source (default are: *.plugin.zsh, init.zsh, *.zsh-theme). Does not work with plugins.

🎯 Selection of Files (To Source, …)

⏳ Conditional Loading

  • 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 73% faster thanks to postponed loading 🔥 Fact: when wait is used without value, it works as wait'0'. Wiki: http://z-shell.github.io/zi/wiki/Example-wait-conditions
  • 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* ]]'. Wiki: http://z-shell.github.io/zi/wiki/Multiple-prompts
  • unload — A condition to check causing plugin to unload. It will unload once, then only if loaded again. E.g.: unload'[[ $PWD != */github* ]]'. Wiki: http://z-shell.github.io/zi/wiki/Multiple-prompts
  • cloneonly — Don't load the plugin / snippet, only download it.
  • if — Load plugin or snippet only when given condition is fulfilled, for example: zi ice if'[[ -n "$commands[otool]" ]]'; zi load ….
  • has — Load plugin or snippet only when given command is available (in $PATH), e.g. zi 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-*}'.

🔇 Plugin Output

  • silent — Mute plugin's or snippet's stderr & stdout. Also skip Loaded ... message under prompt for wait, etc. loaded plugins, and completion-installation messages. Total mute icon behavior 🤐
  • 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

  • blockf — Disallow plugin to modify fpath. Useful when a plugin wants to provide completions in traditional way. ZI 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 zi creinstall {plugin-spec}.

🚀 Command Execution After Cloning, Updating or Loading

okay so these are the ice-mods that fire off around cloning, updating, and loading — every single one, no skips, no cap 💅

  • 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 ⟨http://z-shell.github.io/zi/wiki/atload-and-other-at-ices⟩ — run command after cloning, within plugin's directory, e.g. zi ice atclone"echo Cloned". Ran also after downloading snippet. 🦋
  • atpull ⟨http://z-shell.github.io/zi/wiki/atload-and-other-at-ices⟩ — 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 ⟨http://z-shell.github.io/zi/wiki/atload-and-other-at-ices⟩ — run command after directory setup (cloning, checking it, etc.) of plugin/snippet but before loading. 💖
  • atload ⟨http://z-shell.github.io/zi/wiki/atload-and-other-at-ices⟩ — run command after loading, within plugin's directory. Can be also used with snippets. Passed code can be preceded with !, it will then be tracked (if using load, not light). 🎀
  • run-atpull — always run the atpull hook (when updating), not only when there are new commits to be downloaded. 🔥
  • nocd — don't switch the current directory into the plugin's directory when evaluating the above ice-mods atinit'', atload'', etc. 🙈
  • make ⟨http://z-shell.github.io/zi/wiki/Installing-with-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'!'. 👑

🦋 Sticky-Emulation Of Other Shells

  • 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

  • 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. ✨
  • id-as ⟨http://z-shell.github.io/zi/wiki/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 ⟨https://github.com/zservices⟩ 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 zi light ..., i.e. even with tracking disabled (fast loading), to allow bindmap to remap the key-binds. The same effect has zi light -b ..., i.e. additional -b option to the light-subcommand. Does not work with snippets. 👀
  • wrap-track ⟨http://z-shell.github.io/zi/wiki/wrap-track⟩ — takes a ;-separated list of function names that are to be tracked (meaning gathering report and unload data) once during execution. It works by wrapping the functions with a tracking-enabling and disabling snippet of code. In summary, wrap-track allows to extend the tracking beyond the moment of loading of a plugin. Example use is to wrap-track a precmd function of a prompt (like _p9k_precmd() of powerlevel10k) or other plugin that postpones its initialization till the first prompt (like e.g.: zsh-autosuggestions). Does not work with snippets. 🧚
  • aliases — load the plugin with the aliases mechanism enabled. Use with plugins that define and use aliases in their scripts. 🪄

⭐ Order of Execution

order of execution of related Ice-mods, bestie — this is the exact chain:

atinit -> atpull! -> make'!!' -> mv -> cp -> make! -> atclone/atpull -> make -> (plugin script loading) -> src -> multisrc -> atload.

👑 ZI Commands

following commands are passed to zi ... to obtain described effects. 🫡

💖 Help

  • -h, --help, help — usage information.
  • man — manual. 📖

🧸 Loading and Unloading

  • load {plg-spec} — load plugin, can also receive absolute local path. 🚀
  • light [-b] {plg-spec} — light plugin load, without reporting/tracking. -b – track bindkey-calls only. 🪶
  • unload [-q] {plg-spec} — unload plugin loaded with zi load .... -q – quiet. 🫧
  • snippet [-f] {url} — source local or remote file (by direct URL). -f – don't use cache (force redownload). 🌐

🎀 Completions

  • clist columns, completions columns — list completions in use, with columns completions per line. zi clist 5 will for example print 5 completions per line. Default is 3. 📋
  • cdisable {cname} — disable completion cname. 🙅‍♀️
  • cenable {cname} — enable completion cname. ✅
  • creinstall [-q] {plg-spec} — install completions for plugin, can also receive absolute local path. -q – quiet. 📦
  • cuninstall {plg-spec} — uninstall completions for plugin. 🗑️
  • csearch — search for available completions from any plugin. 🔍
  • compinit — refresh installed completions. 🔄
  • cclear — clear stray and improper completions. 🧹
  • cdlist — show compdef replay list. 📜
  • cdreplay [-q] — replay compdefs (to be done after compinit). -q – quiet. 🔁
  • cdclear [-q] — clear compdef replay list. -q – quiet. 🧼

🦋 Tracking of the Active Session

  • dtrace, dstart — start tracking what's going on in session. 🎬
  • dstop — stop tracking what's going on in session. ⏹️
  • dunload — revert changes recorded between dstart and dstop. ⏪
  • dreport — report what was going on in session. 📝
  • dclear — clear report of what was going on in session. 🧽

🌸 Reports and Statistics

  • times [-s] — statistics on plugin load times, sorted in order of loading. -s – use seconds instead of milliseconds. ⏱️
  • zstatus — overall ZI 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

  • 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 🌸

okay so this is the grab-bag of the remaining zi subcommands — the little side quests, iykyk 💅

  • self-update — updates and compiles ZI. two birds, one slay ✨
  • update [-q] [-r] {plg-spec}|URL|--all — git-updates a plugin or snippet. --all means update all plugins and snippets. -q is quiet mode. -r | --reset runs git reset --hard / svn revert before pulling changes 👀
  • ice <ice specification> — adds an ice to the next command; the argument is e.g. from"gitlab"
  • delete {plg-spec}|URL|--clean|--all — removes a plugin or snippet from disk (lowkey great for forgetting wrongly passed ice-mods 🙈). --all – purge. --clean – delete plugins and snippets that are not loaded.
  • cd {plg-spec} — cds you into the plugin's directory. also supports snippets if you feed it a URL 🫶
  • edit {plg-spec} — opens the plugin's file in $EDITOR
  • glance {plg-spec} — lets you look at the plugin's source (pygmentize, {,source-}highlight)
  • stress {plg-spec} — tests the plugin for compatibility with a set of options 💀
  • changes {plg-spec} — views the plugin's git log
  • create {plg-spec} — creates a plugin (also together with a GitHub repository 👑)
  • srv {service-id} [cmd] — controls a service; the command can be: stop, start, restart, next, quit; next moves the service to another Zshell
  • recall {plg-spec}|URL — fetches the saved ice modifiers and constructs the zi ice ... command for you ✨
  • env-whitelist [-v] [-h] {env..} — lets you specify names (also patterns) of variables that stay unchanged during an unload. -v – verbose.
  • module — manages the binary Zsh module shipped with ZI, see zi module help

💖 Updating ZI and Plugins 💖

To update ZI, just drop zi self-update in the command line. periodt.

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

Some plugins require performing an action each time they're updated — and one way you can do that is with the atpull ice modifier 🧚 for example, writing zi ice atpull'./configure' before loading a plugin will execute ./configure after a successful update. Refer to Ice Modifiers (Ice Modifiers) for more info.

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

🦋 Using Oh My Zsh Themes 🦋

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

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

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

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

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

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

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

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

To summarize:

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

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

setopt promptsubst

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

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

See also the Wiki page: Example Oh My Zsh Setup http://z-shell.github.io/zi/wiki/Example-Oh-My-Zsh-setup/ 💜

✨ COMPLETIONS ✨

💅 Calling compinit Without Turbo Mode 💅

With no Turbo mode in use, compinit can be called normally, i.e.: as autoload compinit; compinit. This should be done after loading of all plugins and before possibly calling zi cdreplay. Also, plugins aren't allowed to simply run compdefs 🫶 you can decide whether to run compdefs by issuing zi cdreplay (reads: compdef-replay). To summarize:

source ~/.zi/bin/zi.zsh

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

autoload -Uz compinit
compinit

zi 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; ZI solves this
                    # via intercepting the `compdef'-calls and storing them for later
                    # use with `zi 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 🔥 like… that's not a glow-up, that's a whole transformation.

🌈 Calling compinit With Turbo Mode 🌈

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

🎀 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 zi cdclear (or zpcdclear, designed to be used in hooks like atload''):

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

zi load "some/plugin"
zi load "other/plugin"

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

🍓 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

👑 ZI 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, and the module is a solution to this 🫶 even if a plugin manager does compile the plugin's main script (like ZI 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 the plugin load command and tracking updates to the plugin – in ZI case: by using the compile ice-mod).

image https://raw.githubusercontent.com/z-shell/zi/images/mod-auto-compile.png

🌸 Installation 🌸

💜 Without ZI 💜

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

sh -c "$(curl -fsSL https://raw.githubusercontent.com/z-shell/zi/main/lib/mod-install.sh)"

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

🦋 With ZI 🦋

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

zi 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 the duration of each script sourcing. Issue zpmod source-study after loading the module at the 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 you to profile the shell startup. Also, no script can pass-through that check and you will obtain a complete list of all loaded scripts, like if Zshell itself was tracking this. The list can be surprising 👀

🧚 Debugging 🧚

To enable debug messages from the module set:

typeset -g ZPLG_MOD_DEBUG=1

✨ HINTS AND TIPS ✨

Okay so this is the glow-up guide part: custom paths, local plugins, git extensions, and preinstall magic. Let’s get into it, bestie 💅

🎀 Customizing Paths 🎀

You can set the following variables to custom values before sourcing ZI. The previous global variables like $ZPLG_HOME have been removed so they don’t pollute the namespace — there’s single $ZPLGM (aka "ZI MAP") hash instead of 8 string variables. Please update your dotfiles. 🫶

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

Here are the hash fields, no cap:

  • ZPLGMBIN_DIR — where ZI code resides, e.g. "~/.zi/bin"
  • ZPLGMHOME_DIR — where ZI should create all working directories, e.g. "~/.zi"
  • ZPLGMPLUGINS_DIR — override single working directory for plugins, e.g. "/opt/zsh/zi/plugins"
  • ZPLGMCOMPLETIONS_DIR — same override energy as above, but for completion files, e.g. "/opt/zsh/zi/root_completions"
  • ZPLGMSNIPPETS_DIR — as above, but for snippets
  • ZPLGMZCOMPDUMP_PATH — path to the .zcompdump file, with the file included (i.e. its name can be different)
  • ZPLGMCOMPINIT_OPTS — options for the compinit call (i.e. done by zpcompinit), use it to pass -C to speed up loading
  • ZPLGMMUTE_WARNINGS — if set to 1, then it mutes some of the ZI warnings, specifically the plugin already registered warning

There’s also $ZPFX, set by default to ~/.zi/polaris — a directory where software with Makefile, etc. can be pointed to, by e.g. atclone'./configure --prefix=$ZPFX'. 🛠️

🌸 Non-GitHub (Local) Plugins 🌸

Use the create subcommand with user name _local (the default) to create the plugin’s skeleton in $ZPLGM[PLUGINS_DIR]. It lowkey won’t be connected to a GitHub repository (because the user name is _local). To enter the plugin’s directory, use the cd command with just the plugin’s name (without _local, it’s optional). 🐚

If the user name is not _local, then ZI will create the repository also on GitHub and set up the correct repository origin. ✨

🦋 Extending Git 🦋

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

  • all files are under $HOME — no administrator rights needed
  • declarative setup (like Chef or Puppet) — copying .zshrc to a different account brings the git-related setup too
  • easy update by e.g. zi update --all

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

zi ice wait"2" lucid as"program" pick"bin/git-dsf"
zi light z-shell/zsh-diff-so-fancy

zi ice wait"2" lucid as"program" pick"$ZPFX/bin/git-now" make"prefix=$ZPFX install"
zi light iwata/git-now

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

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

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

🧚 Preinstalling Plugins 🧚

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

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

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

RUN zsh -i -c -- '-zi-scheduler burst || true'

An example Dockerfile can be found here: https://github.com/robobenklein/configs/blob/master/Dockerfile 🐳

🌈 GETTING HELP AND COMMUNITY 🌈

Whant to learn more? 👀

That’s the whole page, bestie 💖 — footer check: the date is November 2021, and the source/version slot is literally () (mysterious, but iconic). 🎀

📦 where this page comes from