DOCSEARCHbyAlgolia
Submit Docs

Zinit Documentation

repository·main·Indexed 26 days ago

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

A high-performance Zsh plugin manager featuring Turbo mode for reduced shell startup times and Lucid mode for quiet asynchronous loading. Zinit allows users to load plugins and snippets, manage binary releases from GitHub, and migrate from other managers like Oh-My-ZSH, Prezto, Zgen, and Zplug using a flexible system of 'ice' modifiers.

Tokens
14.2K
Snippets
33
Records
118
Agent score
89%

What's inside Zinit

  1. Upgrade Zinit and its plugins

    main

    Use the following commands to keep Zinit and your installed plugins up to date:

    • zinit self-update: Updates the Zinit tool itself.
    • zinit update: Updates all installed plugins.
    • zinit update --parallel: Updates plugins in parallel for speed.
    • zinit update --parallel <N>: Updates plugins in parallel using <N> concurrent jobs.
    zinit self-update
zinit update
zinit update --parallel 40

  2. Use Turbo Mode for deferred loading

    main
    If a zinit load, zinit light, or zinit snippet command is preceded by ice-mods such as wait, load, unload, or on-update-of/subscribe, Zinit enters 'turbo-mode'. In this mode, the task is added to an internal scheduler (@zinit-scheduler) to be executed later, preventing slow plugin loading from delaying your shell startup.

  3. Install binary releases and programs with Zinit

    main

    Zinit can manage binary releases (from GitHub releases) and compiled programs using ice modifiers:

    • GitHub Releases: Use from"gh-r" and as"program" to download and extract binaries.
    • Renaming Binaries: Use mv"<pattern> -> <new_name>" to rename extracted files.
    • Compiling from Source: Use atclone and atpull to run configuration and build steps (like ./configure and make), and pick to add the resulting binary to your $PATH.
    • Automatic OS/Arch Selection: Zinit automatically greps for operating system and architecture names when using from"gh-r" unless bpick is specified.
    # Load fzf from GitHub releases
zi ice from"gh-r" as"program"
zi light junegunn/fzf

# Load docker-compose with renaming and OS filtering
zi ice from"gh-r" as"program" mv"docker* -> docker-compose" bpick"*linux*"
zi load docker/compose

# Compile Vim from source
zi ice \
  as"program" \
  atclone"rm -f src/auto/config.cache; ./configure" \
  atpull"%atclone" \
  make \
  pick"src/vim"
zi light vim/vim

  4. Ignore specific plugin completions

    main

    To prevent certain plugins or snippets from providing completions, load them first and then issue zinit cdclear (or zicdclear when used inside hooks like atload''). This clears the gathered compdef calls from those specific plugins before subsequent plugins are loaded.

    ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}/zinit/zinit.git"
source "${ZINIT_HOME}/zinit.zsh"

zi snippet OMZP::git
zi cdclear -q # Forget completions provided by Git plugin

zi load "some/plugin"

autoload -Uz compinit
compinit
zinit cdreplay -q

  5. Debug Zinit operations

    main

    Zinit provides a set of internal debug functions to investigate plugin loading and behavior. You can manage a debug session using the following workflow:

    1. Start debug mode: Use .zinit-debug-start to begin recording.
    2. Check status: Use .zinit-debug-status to see the current state.
    3. View results: Use .zinit-debug-report to display the recorded debug data from your interactive session.
    4. Stop and Revert: Use .zinit-debug-stop to end the session and .zinit-debug-revert to undo changes made during the debug mode.

  6. Migrate from Prezto to Zinit

    main

    Zinit provides shorthand syntax to load Prezto modules and snippets:

    • zi snippet PZT::<PATH>: Shorthand for https://github.com/sorin-ionescu/prezto/tree/master/<PATH>.
    • zi snippet PZTM::<PATH>: Shorthand for https://github.com/sorin-ionescu/prezto/tree/master/modules/<PATH>.

    Handling Subdirectories and Special Cases:

    • Use zi ice svn if the module requires an entire subdirectory.
    • Use zi ice as"null" if the module lacks standard entry files like init.zsh or *.plugin.zsh.
    • Use zi ice atclone"..." if the module has external dependencies that need to be cloned recursively (e.g., zsh-completions).
    # PZT Shorthand Syntax
zi snippet PZT::modules/environment
zi snippet PZT::modules/terminal

# Using svn for subdirectories
zi ice svn
zi snippet PZTM::docker

# Using as"null" for modules without standard entry files
zi ice svn as"null"
zi snippet PZTM::archive

# Handling external modules with atclone
zi ice \
  atclone"git clone --recursive https://github.com/zsh-users/zsh-completions.git external" \
  blockf \
  svn
zi snippet PZTM::completion

  7. Update the documentation on gh-pages

    main

    To update the live documentation at https://zdharma-continuum.github.io/, follow these steps:

    1. Fetch and checkout the documentation branch:
      git fetch origin documentation
git checkout documentation
    2. Apply your modifications.
3. Push your changes to the branch.
4. Monitor the CI logs at `https://github.com/zdharma-continuum/zinit/actions/workflows/gh-pages.yaml` to ensure the deployment succeeds.

  8. Update Zinit and Plugins

    main

    To update the Zinit core, use zinit self-update. To update all installed plugins and snippets, use zinit update. You can also update a specific plugin by providing its name: zinit update NAME_OF_PLUGIN.

    If a plugin requires a specific action after being updated (like running a configuration script), use the atpull ice modifier. For example, zinit ice atpull './configure' will execute the ./configure command immediately after a successful update.

    zinit self-update
zinit update
zinit update NAME_OF_PLUGIN

# Example with ice modifier
zinit ice atpull'./configure'
zinit load some/plugin

  9. Configure Completions with Turbo Mode

    main

    When using Turbo mode (wait''), completions are loaded asynchronously. To ensure completions are initialized correctly, use the zicompinit helper function (which runs autoload compinit; compinit) and zicdreplay (to replay caught compdef calls) within the atinit or atload hooks of your last completion-related plugin.

    ZINIT_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}/zinit"
source "${ZINIT_HOME}/zinit.zsh"

zinit lucid wait for "some/plugin"
zinit lucid wait for "other/plugin"

zi for \
    atload"zicompinit; zicdreplay" \
    blockf \
    lucid \
    wait \
  zsh-users/zsh-completions

  10. Migrate from Oh-My-ZSH to Zinit

    main

    Zinit provides shorthand syntax to easily source Oh-My-ZSH (OMZ) components as snippets. This allows you to use OMZ libraries, plugins, and themes without installing the full OMZ framework.

    OMZ Shorthand Syntax:

    • OMZ::<PATH>: Sources from the OMZ root.
    • OMZL::<PATH>: Sources from oh-my-zsh/lib/.
    • OMZT::<PATH>: Sources from oh-my-zsh/themes/.
    • OMZP::<PATH>: Sources from oh-my-zsh/plugins/.

    Important Notes:

    • Many OMZ themes require the git library and promptsubst (setopt promptsubst in .zshrc).
    • Use zinit cdclear -q to suppress completions provided by plugins you might want to ignore.

  11. Update asciidoc and zshelldoc

    main

    To update documentation files like asciidoc or zshelldoc, it is recommended to use Docker or Podman to avoid locale-related issues with zsd (zshelldoc).

    Run the following command from the repository root:

    make doc-container

    If you prefer to build zshelldoc or the PDF manually, you will need zshelldoc (zsd), asciidoc, and the make doc command.

  12. Migrate from Zgen to Zinit

    main

    When migrating from Zgen, map your existing loading logic to Zinit commands:

    • Oh-My-Zsh: Replace zgen oh-my-zsh with zi snippet OMZL::<ALL_OF_THEM> and zgen oh-my-zsh <PATH> with zi snippet OMZ::<PATH>.
    • Prezto: Replace zgen prezto with zi snippet PZTM::<LIST> and zgen prezto <modulename> with zi snippet PZTM::<modulename>.
    • General: Replace zgen load <repo> [location] [branch] with zi ice ver"<branch>" followed by zi load <repo>.