'\" t .\" Automatically generated by Pandoc 2.14.1 .\" .TH "" "" "" "" "" .hy .PP [IMAGE: MIT License (https://img.shields.io/badge/license-MIT-blue.svg)] [IMAGE: image (https://img.shields.io/github/tag/zdharma-continuum/zinit.svg)] (https://github.com/zdharma-continuum/zinit/releases) [IMAGE: Join the chat at https://matrix.to/#/#zdharma-continuum_community:gitter.im (https://badges.gitter.im/zdharma-continuum/zinit.svg)] (https://gitter.im/zdharma-continuum/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) .RS .PP \f[B]Note\f[R]: The original author (https://github.com/psprint) of zinit deleted the \f[C]zdharma\f[R] organization randomly. .PP This is a reliable fork / place for the continuation of the project. .PP \[u1F6A7] For migration instructions please refer to this wiki entry (https://github.com/zdharma-continuum/zinit/wiki/%F0%9F%9A%9A-Migration-to-zdharma-continuum) .RE .PP \f[B]Table of Contents\f[R] \f[I]generated with DocToc (https://github.com/thlorenz/doctoc)\f[R] .IP \[bu] 2 News .IP \[bu] 2 Zinit .IP \[bu] 2 Zinit Wiki .IP \[bu] 2 Quick Start .RS 2 .IP \[bu] 2 Install .RS 2 .IP \[bu] 2 Automatic Installation (Recommended) .IP \[bu] 2 Manual Installation .RE .IP \[bu] 2 Usage .RS 2 .IP \[bu] 2 Introduction .IP \[bu] 2 Plugins and snippets .IP \[bu] 2 Upgrade Zinit and plugins .IP \[bu] 2 Turbo and lucid .IP \[bu] 2 Migration .IP \[bu] 2 More Examples .RE .RE .IP \[bu] 2 How to Use .RS 2 .IP \[bu] 2 Ice Modifiers .RS 2 .IP \[bu] 2 Cloning Options .IP \[bu] 2 Selection of Files (To Source, \&...) .IP \[bu] 2 Conditional Loading .IP \[bu] 2 Plugin Output .IP \[bu] 2 Completions .IP \[bu] 2 Command Execution After Cloning, Updating or Loading .IP \[bu] 2 Sticky-Emulation Of Other Shells .IP \[bu] 2 Others .IP \[bu] 2 Order of Execution .RE .IP \[bu] 2 Zinit Commands .RS 2 .IP \[bu] 2 Help .IP \[bu] 2 Loading and Unloading .IP \[bu] 2 Completions .IP \[bu] 2 Tracking of the Active Session .IP \[bu] 2 Reports and Statistics .IP \[bu] 2 Compiling .IP \[bu] 2 Other .RE .IP \[bu] 2 Updating Zinit and Plugins .RE .IP \[bu] 2 Completions .RS 2 .IP \[bu] 2 Calling \f[C]compinit\f[R] Without Turbo Mode .IP \[bu] 2 Calling \f[C]compinit\f[R] With Turbo Mode .IP \[bu] 2 Ignoring Compdefs .IP \[bu] 2 Disabling System-Wide \f[C]compinit\f[R] Call (Ubuntu) .RE .IP \[bu] 2 Zinit Module .IP \[bu] 2 Hints and Tips .RS 2 .IP \[bu] 2 Customizing Paths .IP \[bu] 2 Non-GitHub (Local) Plugins .IP \[bu] 2 Extending Git .RE .IP \[bu] 2 Supporting .IP \[bu] 2 Getting Help and Community .SH News .PP See here .PP To see the full history check the changelog. .SH Zinit .PP Zinit is a flexible and fast Zshell plugin manager that will allow you to install everything from GitHub and other sites. Its characteristics are: .IP "1." 3 Zinit is currently the only plugin manager out there that provides Turbo mode which yields \f[B]50-80% faster Zsh startup\f[R] (i.e.: the shell will start up to \f[B]5\f[R] times faster!). Check out a speed comparison with other popular plugin managers here (https://github.com/zdharma-continuum/pm-perf-test). .IP "2." 3 The plugin manager gives \f[B]reports\f[R] from plugin loadings describing what \f[B]aliases\f[R], functions, \f[B]bindkeys\f[R], Zle widgets, zstyles, \f[B]completions\f[R], variables, \f[C]PATH\f[R] and \f[C]FPATH\f[R] 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. .IP "3." 3 Supported is unloading of plugin and ability to list, (un)install and \f[B]selectively disable\f[R], \f[B]enable\f[R] plugin\[cq]s completions. .IP "4." 3 The plugin manager supports loading Oh My Zsh and Prezto plugins and libraries, however the implementation isn\[cq]t framework specific and doesn\[cq]t bloat the plugin manager with such code (more on this topic can be found on the Wiki, in the Introduction (https://zdharma-continuum.github.io/zinit/wiki/INTRODUCTION/#oh_my_zsh_prezto)). .IP "5." 3 The system does not use \f[C]$FPATH\f[R], loading multiple plugins doesn\[cq]t clutter \f[C]$FPATH\f[R] with the same number of entries (e.g.\ \f[C]10\f[R], \f[C]15\f[R] or more). Code is immune to \f[C]KSH_ARRAYS\f[R] and other options typically causing compatibility problems. .IP "6." 3 Zinit supports special, dedicated \f[B]packages\f[R] that offload the user from providing long and complex commands. See the zinit-packages repository (https://github.com/zdharma-continuum/zinit-packages) for a growing, complete list of Zinit packages and the Wiki page (https://zdharma-continuum.github.io/zinit/wiki/Zinit-Packages/) for an article about the feature. .IP "7." 3 Also, specialized Zinit extensions \[em] called \f[B]annexes\f[R] \[em] allow to extend the plugin manager with new commands, URL-preprocessors (used by e.g.: zinit-annex-as-monitor (https://github.com/zdharma-continuum/zinit-annex-as-monitor) annex), post-install and post-update hooks and much more. See the zdharma-continuum (https://github.com/zdharma-continuum) organization for a growing, complete list of available Zinit extensions and refer to the Wiki article (https://zdharma-continuum.github.io/zinit/wiki/Annexes/) for an introduction on creating your own annex. .SH Zinit Wiki .PP The information in this README is complemented by the Zinit Wiki (https://zdharma-continuum.github.io/zinit/wiki/). The README is an introductory overview of Zinit while the Wiki gives a complete information with examples. Make sure to read it to get the most out of Zinit. .SH Quick Start .SS Install .SS Automatic Installation (Recommended) .PP The easiest way to install Zinit is to execute: .IP .nf \f[C] sh -c \[dq]$(curl -fsSL https://git.io/zinit-install)\[dq] \f[R] .fi .PP This will install Zinit in \f[C]\[ti]/.local/share/zinit/zinit.git\f[R]. \f[C].zshrc\f[R] will be updated with three lines of code that will be added to the bottom. The lines will be sourcing \f[C]zinit.zsh\f[R] and setting up completion for command \f[C]zinit\f[R]. .PP After installing and reloading the shell compile Zinit with \f[C]zinit self-update\f[R]. .SS Manual Installation .PP To manually install Zinit clone the repo to e.g.\ \f[C]\[ti]/.local/share/zinit/zinit.git\f[R]: .IP .nf \f[C] ZINIT_HOME=\[dq]${XDG_DATA_HOME:-${HOME}/.local/share}/zinit/zinit.git\[dq] mkdir -p \[dq]$(dirname $ZINIT_HOME)\[dq] git clone https://github.com/zdharma-continuum/zinit.git \[dq]$ZINIT_HOME\[dq] \f[R] .fi .PP and source \f[C]zinit.zsh\f[R] from your \f[C].zshrc\f[R] (above compinit (http://zsh.sourceforge.net/Doc/Release/Completion-System.html#Initialization)): .IP .nf \f[C] ZINIT_HOME=\[dq]${XDG_DATA_HOME:-${HOME}/.local/share}/zinit/zinit.git\[dq] source \[dq]${ZINIT_HOME}/zinit.zsh\[dq] \f[R] .fi .PP If you place the \f[C]source\f[R] below \f[C]compinit\f[R], then add those two lines after the \f[C]source\f[R]: .IP .nf \f[C] autoload -Uz _zinit (( ${+_comps} )) && _comps[zinit]=_zinit \f[R] .fi .PP Various paths can be customized, see section Customizing Paths. .PP After installing and reloading the shell compile Zinit with \f[C]zinit self-update\f[R]. .SS Usage .SS Introduction .PP Click here to read the introduction to Zinit (https://zdharma-continuum.github.io/zinit/wiki/INTRODUCTION/). It explains basic usage and some of the more unique features of Zinit such as the Turbo mode. If you\[cq]re new to Zinit we highly recommend you read it at least once. .SS Plugins and snippets .PP Plugins can be loaded using \f[C]load\f[R] or \f[C]light\f[R]. .IP .nf \f[C] zinit load # Load with reporting/investigating. zinit light # Load without reporting/investigating. \f[R] .fi .PP If you want to source local or remote files (using direct URL), you can do so with \f[C]snippet\f[R]. .IP .nf \f[C] zinit snippet \f[R] .fi .PP Such lines should be added to \f[C].zshrc\f[R]. Snippets are cached locally, use \f[C]-f\f[R] option to download a fresh version of a snippet, or \f[C]zinit update {URL}\f[R]. Can also use \f[C]zinit update --all\f[R] to update all snippets (and plugins). .PP \f[B]Example\f[R] .IP .nf \f[C] # 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/ \f[R] .fi .PP \f[B]Prompt(Theme) Example\f[R] .PP This is powerlevel10k (https://github.com/romkatv/powerlevel10k), pure (https://github.com/sindresorhus/pure), starship (https://github.com/starship/starship) sample: .IP .nf \f[C] # Load powerlevel10k theme zinit ice depth\[dq]1\[dq] # git clone depth zinit light romkatv/powerlevel10k # Load pure theme zinit ice pick\[dq]async.zsh\[dq] src\[dq]pure.zsh\[dq] # with zsh-async library that\[aq]s bundled with it. zinit light sindresorhus/pure # Load starship theme zinit ice as\[dq]command\[dq] from\[dq]gh-r\[dq] \[rs] # \[ga]starship\[ga] binary as command, from github release atclone\[dq]./starship init zsh > init.zsh; ./starship completions zsh > _starship\[dq] \[rs] # starship setup at clone(create init.zsh, completion) atpull\[dq]%atclone\[dq] src\[dq]init.zsh\[dq] # pull behavior same as clone, source init.zsh zinit light starship/starship \f[R] .fi .SS Upgrade Zinit and plugins .PP Zinit can be updated to \f[C]self-update\f[R] and plugins to \f[C]update\f[R]. .IP .nf \f[C] # 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 \f[R] .fi .SS Turbo and lucid .PP Turbo and lucid are the most used options. Turbo Mode .PP Turbo mode is the key to performance. It can be loaded asynchronously, which makes a huge difference when the amount of plugins increases. .PP Usually used as \f[C]zinit ice wait\[dq]\[dq]\f[R], let\[cq]s use the previous example: .IP .nf \f[C] zinit ice wait # wait is same wait\[dq]0\[dq] zinit load zdharma-continuum/history-search-multi-word zinit ice wait\[dq]2\[dq] # load after 2 seconds zinit load zdharma-continuum/history-search-multi-word zinit ice wait # also be used in \[ga]light\[ga] and \[ga]snippet\[ga] zinit snippet https://gist.githubusercontent.com/hightemp/5071909/raw/ \f[R] .fi Lucid .PP Turbo mode is verbose, so you need an option for quiet. .PP You can use with \f[C]lucid\f[R]: .IP .nf \f[C] zinit ice wait lucid zinit load zdharma-continuum/history-search-multi-word \f[R] .fi .PP \f[B]\f[BI]F&A:\f[B]\f[R] What is \f[C]ice\f[R]? .PP \f[C]ice\f[R] is zinit\[cq]s option command. The option melts like ice and is used only once. (more: Ice Modifiers) .SS Migration Migration from Oh-My-ZSH .PP \f[B]Basic\f[R] .IP .nf \f[C] zinit snippet # Raw Syntax with URL zinit snippet OMZ:: # Shorthand OMZ/ (https://github.com/ohmyzsh/ohmyzsh/raw/master/) zinit snippet OMZL:: # Shorthand OMZ/lib/ zinit snippet OMZT:: # Shorthand OMZ/themes/ zinit snippet OMZP:: # Shorthand OMZ/plugins/ \f[R] .fi .PP \f[B]Library\f[R] .PP Importing the clipboard (https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/clipboard.zsh) and termsupport (https://github.com/ohmyzsh/ohmyzsh/blob/master/lib/termsupport.zsh) Oh-My-Zsh Library Sample: .IP .nf \f[C] # 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 \f[R] .fi .PP \f[B]Theme\f[R] .PP To use \f[B]themes\f[R] created for Oh My Zsh you might want to first source the \f[C]git\f[R] library there. .PP Then you can use the themes as snippets (\f[C]zinit snippet \f[R]). Some themes require not only Oh My Zsh\[cq]s Git \f[B]library\f[R], but also Git \f[B]plugin\f[R] (error about \f[C]current_branch\f[R] may appear). Load this Git-plugin as single-file snippet directly from OMZ. .PP Most themes require \f[C]promptsubst\f[R] option (\f[C]setopt promptsubst\f[R] in \f[C]zshrc\f[R]), if it isn\[cq]t set, then prompt will appear as something like: \f[C]... $(build_prompt) ...\f[R]. .PP You might want to suppress completions provided by the git plugin by issuing \f[C]zinit cdclear -q\f[R] (\f[C]-q\f[R] is for quiet) \[en]\ see below \f[B]Ignoring Compdefs\f[R]. .PP To summarize: .IP .nf \f[C] ## Oh My Zsh Setting ZSH_THEME=\[dq]robbyrussell\[dq] ## 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 \f[R] .fi .PP External Theme Sample: NicoSantangelo/Alpharized (https://github.com/nicosantangelo/Alpharized) .IP .nf \f[C] ## Oh My Zsh Setting ZSH_THEME=\[dq]alpharized\[dq] ## 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[R] .fi .PP \f[B]\f[BI]F&A:\f[B]\f[R] Error occurs when loading OMZ\[cq]s theme. .PP If the \f[C]git\f[R] library will not be loaded, then similar to following errors will be appearing: .IP .nf \f[C] \&........:1: command not found: git_prompt_status \&........:1: command not found: git_prompt_short_sha \f[R] .fi .PP \f[B]Plugin\f[R] .PP If it consists of a single file, you can just load it. .IP .nf \f[C] ## 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 \f[R] .fi .PP Use \f[C]zinit ice svn\f[R] if multiple files require an entire subdirectory. Like gitfast (https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/gitfast), osx (https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/osx): .IP .nf \f[C] zinit ice svn zinit snippet OMZP::gitfast zinit ice svn zinit snippet OMZP::osx \f[R] .fi .PP Use \f[C]zinit ice as\[dq]completion\[dq]\f[R] to directly add single file completion snippets. Like docker (https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/docker), fd (https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/fd): .IP .nf \f[C] zinit ice as\[dq]completion\[dq] zinit snippet OMZP::docker/_docker zinit ice as\[dq]completion\[dq] zinit snippet OMZP::fd/_fd \f[R] .fi .PP You can see an extended explanation of Oh-My-Zsh setup in the Wiki (https://zdharma-continuum.github.io/zinit/wiki/Example-Oh-My-Zsh-setup/) Migration from Prezto .PP \f[B]Basic\f[R] .IP .nf \f[C] zinit snippet # Raw Syntax with URL zinit snippet PZT:: # Shorthand PZT/ (https://github.com/sorin-ionescu/prezto/tree/master/) zinit snippet PZTM:: # Shorthand PZT/modules/ \f[R] .fi .PP \f[B]Modules\f[R] .PP Importing the environment (https://github.com/sorin-ionescu/prezto/tree/master/modules/environment) and terminal (https://github.com/sorin-ionescu/prezto/tree/master/modules/terminal) Prezto Modules Sample: .IP .nf \f[C] ## Prezto Setting zstyle \[aq]:prezto:load\[aq] pmodule \[aq]environment\[aq] \[aq]terminal\[aq] ## 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 \f[R] .fi .PP Use \f[C]zinit ice svn\f[R] if multiple files require an entire subdirectory. Like docker (https://github.com/sorin-ionescu/prezto/tree/master/modules/docker), git (https://github.com/sorin-ionescu/prezto/tree/master/modules/git): .IP .nf \f[C] zinit ice svn zinit snippet PZTM::docker zinit ice svn zinit snippet PZTM::git \f[R] .fi .PP Use \f[C]zinit ice as\[dq]null\[dq]\f[R] if don\[cq]t exist \f[C]*.plugin.zsh\f[R], \f[C]init.zsh\f[R], \f[C]*.zsh-theme*\f[R] files in module. Like archive (https://github.com/sorin-ionescu/prezto/tree/master/modules/archive): .IP .nf \f[C] zinit ice svn as\[dq]null\[dq] zinit snippet PZTM::archive \f[R] .fi .PP Use \f[C]zinit ice atclone\[dq]git clone \[dq]\f[R] if module have external module. Like completion (https://github.com/sorin-ionescu/prezto/tree/master/modules/completion): .IP .nf \f[C] zplugin ice svn blockf \[rs] # use blockf to prevent any unnecessary additions to fpath, as zinit manages fpath atclone\[dq]git clone --recursive https://github.com/zsh-users/zsh-completions.git external\[dq] zplugin snippet PZTM::completion \f[R] .fi .PP \f[B]\f[BI]F&A:\f[B]\f[R] What is \f[C]zstyle\f[R]? .PP Read zstyle (http://zsh.sourceforge.net/Doc/Release/Zsh-Modules.html#The-zsh_002fzutil-Module) doc (more: What does \f[C]zstyle\f[R] do? (https://unix.stackexchange.com/questions/214657/what-does-zstyle-do)). Migration from Zgen .PP \f[B]Oh My Zsh\f[R] .PP More reference: check \f[B]Migration from Oh-My-ZSH\f[R] .IP .nf \f[C] # Load ohmyzsh base zgen oh-my-zsh zinit snippet OMZL:: # Load ohmyzsh plugins zgen oh-my-zsh zinit snippet OMZ:: \f[R] .fi .PP \f[B]Prezto\f[R] .PP More reference: check \f[B]Migration from Prezto\f[R] .IP .nf \f[C] # Load Prezto zgen prezto zinit snippet PZTM:: # environment terminal editor history directory spectrum utility completion prompt # Load prezto plugins zgen prezto zinit snippet PZTM:: # Load a repo as Prezto plugins zgen pmodule zinit ice ver\[dq]\[dq] zinit load # Set prezto options zgen prezto