zinit
Manage Zsh plugins and snippets
TLDR
Show all installed plugins
Go to the directory of a plugin
Fetch the newest version of zinit from GitHub
List status of all installed completions
Install completions for a plugin
Delete completion for a plugin
SYNOPSIS
Zinit is primarily configured within the .zshrc file. Its core syntax involves declarative statements for loading packages, along with various interactive commands for maintenance:
Declaration Syntax:
zinit [ice-modifiers] {load|light|snippet|cd} <repository_or_path>
Maintenance Commands:
zinit {update|clean|cd|status|self-update|help} [arguments]
Examples:
zinit load zsh-users/zsh-syntax-highlighting
zinit ice lucid; zinit light romkatv/powerlevel10k
zinit update
PARAMETERS
ice
Begins a block of global modifiers that apply to subsequent load, light, or snippet calls until another ice or zinit command is encountered.
as'...'
Specifies the type of package: plugin (default), theme, completion, snippet, command, null, etc.
pick'...'
Sources specific files or directories after the plugin is loaded, useful when not all files in a repo should be sourced.
src'...'
Sources a specific file, similar to pick but for a single file.
make'...'
Executes commands (e.g., make install) after cloning or updating a repository.
wait
Loads the package asynchronously after a short delay, speeding up shell startup.
lucid
Loads the package immediately without lazy-loading or Turbo mode, suitable for essential or small plugins.
atclone'...'
Executes commands immediately after cloning a repository.
atpull'...'
Executes commands immediately after pulling updates to a repository.
fpath'...'
Adds a directory to the fpath, making functions within it available for auto-loading.
path'...'
Adds a directory to the PATH environment variable.
badd'...'
Adds a binary executable from the package to the PATH.
completion
Forces Zinit to load completions for the package, even if not auto-detected.
nocompletions
Prevents Zinit from loading completions for the package.
bindkey'...'
Registers keybindings, often used with lazy-loaded packages.
multisrc
Sources multiple files matching a pattern within the package.
clone-depth'...'
Performs a shallow Git clone with a specified depth, reducing download size.
DESCRIPTION
Zinit is a powerful and highly configurable plugin manager for the Zsh shell. It excels in optimizing shell startup times through its innovative 'Turbo' mode and asynchronous loading capabilities, allowing plugins, themes, snippets, and completions to be loaded in the background or on demand. Beyond basic package management, Zinit offers fine-grained control over how packages are handled using 'ice' modifiers. These modifiers allow users to specify actions like sourcing specific files, adding paths, compiling programs, defining keybindings, or even loading binary executables. It supports fetching packages from GitHub, GitLab, Bitbucket, local paths, and arbitrary URLs, making it a versatile tool for enhancing the Zsh environment with speed and precision.
CAVEATS
Zinit is exclusively designed for the Zsh shell and will not function with Bash or other shell environments. While its 'ice' modifiers offer immense flexibility, they can introduce a steeper learning curve for new users. Overly complex configurations with numerous specific 'ice' declarations might become challenging to debug without a clear understanding of Zinit's loading mechanisms. Its primary reliance on Git for fetching repositories means that network connectivity and Git setup are prerequisites for managing packages.
CORE CONCEPTS
Ice Modifiers: These are special keywords preceding a load, light, or snippet command that modify how Zinit handles the package. They provide extensive control over sourcing, path management, compilation, and more.
Turbo Mode: Zinit's default lazy-loading mechanism. Plugins are sourced only when a command they provide is first invoked, or after a specified delay, significantly reducing shell startup time.
Snippets: Allows loading of single files or small code blocks directly from URLs (e.g., Gist) without requiring a full Git repository clone.
Completions: Zinit has robust support for Zsh completion systems, often automatically detecting and loading completions provided by packages.
ZINIT COMMANDS
While Zinit is primarily configured via .zshrc, it provides several interactive commands for managing packages:
zinit update: Updates all installed packages or specified ones to their latest versions.
zinit clean: Removes unused or orphaned packages from the installation directory.
zinit cd <package>: Changes the current directory to the installation location of a specified package.
zinit status: Displays information about loaded packages, their status, and any errors.
zinit self-update: Updates Zinit itself to the latest version.
zinit help: Shows help messages for Zinit commands and ice modifiers.
ZINIT ANNEXES
Zinit Annexes are optional extensions that provide additional functionality, such as enhanced completion management, specialized build systems, or support for unique package types. They extend Zinit's core capabilities without bloating the main codebase, allowing users to customize their setup with only the features they need.
HISTORY
Zinit (originally known as zplugin) was created by the developer known as 'zdharma' (now under the 'zdharma-continuum' organization) to address the performance shortcomings and lack of fine-grained control prevalent in earlier Zsh plugin managers like oh-my-zsh. Its development focused heavily on optimizing shell startup times through asynchronous loading, a feature it pioneered among Zsh managers. The introduction of 'Turbo' mode and a comprehensive set of 'ice' modifiers allowed users unprecedented control over how and when plugins were loaded, setting a new standard for flexibility and efficiency in Zsh environments. It has continuously evolved, introducing 'annexes' for extended functionality, solidifying its position as a leading-edge tool for Zsh power users.