Z-Shell

https://github.com/z-shell/wiki
Admin
Z-Shell is a Docusaurus-powered documentation site providing guides for the Zi plugin manager,...
Tokens:114,640
Snippets:1,573
Trust Score:9.2
Update:3 months ago
Show doc for...
Tokens:
Raw
### Local Development Setup

Source: https://github.com/z-shell/wiki/blob/main/community/00_contributing/04_contributing_docs.mdx

Clone the wiki repository, install dependencies, and start the development server.

```shell
git clone https://github.com/<your-username>/wiki.git
cd wiki
pnpm install          # install dependencies
pnpm start            # dev server at http://localhost:3000
```

--------------------------------

### Zunit Installation and Project Setup

Source: https://github.com/z-shell/wiki/blob/main/community/03_zunit/index.mdx

Follow these steps to install Zunit, initialize a new project, write a test, and run it.

```zsh
# 1. Install
git clone https://github.com/z-shell/zunit.git
cd zunit && ./build.zsh && cp ./zunit /usr/local/bin

# 2. Scaffold a new project
cd my-project
zunit init

# 3. Write a test  (tests/example.zunit)
# #!/usr/bin/env zunit
# @test 'addition works' {
#   assert 2 equals 2
# }

# 4. Run
zunit
```

--------------------------------

### Set Install Location and Create Directory

Source: https://github.com/z-shell/wiki/blob/main/docs/getting_started/01_installation.mdx

Configures the installation directory for Zi and creates the necessary bin directory. This is the first step in manual setup.

```zsh
typeset -Ag ZI
typeset -gx ZI[HOME_DIR]="${XDG_DATA_HOME:-${HOME}/.local/share}/zi"
typeset -gx ZI[BIN_DIR]="${ZI[HOME_DIR]}/bin"
command mkdir -p "$ZI[BIN_DIR]"
```

--------------------------------

### Install fbterm with Patches

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/annexes/4_patch-dl.mdx

Example demonstrating how to download and apply two patches for installing fbterm using `dl` and `patch` ice-modifiers, followed by build and installation commands.

```zsh
zi ice as"command" pick"$ZPFX/bin/fbterm" \
  dl"https://bugs.archlinux.org/task/46860?getfile=13513 -> ins.patch" \
  dl"https://aur.archlinux.org/cgit/aur.git/plain/0001-Fix-build-with-gcc-6.patch?h=fbterm-git" \
    patch"ins.patch; 0001-Fix-build-with-gcc-6.patch" \
      atclone"./configure --prefix=$ZPFX" \
      atpull"%atclone" make"install" reset
zi load izmntuk/fbterm
```

--------------------------------

### Install with make using ZPFX

Source: https://github.com/z-shell/wiki/blob/main/community/00_contributing/03_zsh_plugin_standard.mdx

Installs software using the 'make' command, specifying the installation prefix with the ZPFX environment variable.

```zsh
make PREFIX=$ZPFX install
```

--------------------------------

### Install git-extras with specific build flags

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs 'git-extras' with 'wait lucid' and 'nocompile' flags. It picks all executables starting with 'git-' and sets the make prefix.

```zsh
zi ice wait lucid as'program' pick'$ZPFX/bin/git-*' make'PREFIX=$ZPFX' nocompile
zi light tj/git-extras
```

--------------------------------

### Fully Manual Installation of Zsh Navigation Tools

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/zsh_navigation_tools.mdx

Copy ZNT files to a site-functions directory and autoload the necessary commands in `.zshrc`. This method is for manual setup without plugin managers.

```shell
autoload n-list n-cd n-env n-kill n-panelize n-options n-aliases n-functions n-history n-help
```

--------------------------------

### Install zsh-users/zsh-completions

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/02_completions.mdx

Installs the zsh-users/zsh-completions plugin from GitHub.

```zsh
zi ice lucid wait as'completion'
zi light zsh-users/zsh-completions
```

--------------------------------

### Install Plugin from Private Repository using from'...' ice

Source: https://github.com/z-shell/wiki/blob/main/docs/guides/syntax/01_standard.mdx

Install and load plugins from private repositories by using the from'...' ice, which requires credentials. This example shows how to specify a GitHub user and then load a plugin from that user's repository.

```zsh
zi ice from"user@github.com"
zi load user/fsh-auto-themes
```

--------------------------------

### Install docker/compose

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs 'docker-compose' from the docker/compose GitHub repository.

```zsh
zi ice from"gh-r" as'program' mv'docker* -> docker-compose'
zi light docker/compose
```

--------------------------------

### Install zsh-pandoc-completion

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/02_completions.mdx

Installs the zsh-pandoc-completion plugin from GitHub.

```zsh
zi ice lucid wait as'completion' blockf has'pandoc'
zi light srijanshetty/zsh-pandoc-completion
```

--------------------------------

### Install neovim/neovim

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'nvim' binary from the neovim/neovim GitHub repository.

```zsh
zi ice as'program' from'gh-r' 
  bpick'nvim-linux64.tar.gz' sbin'**/bin/nvim -> nvim'
zi light neovim/neovim
```

--------------------------------

### Install ajeetdsouza/zoxide

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs 'zoxide' from GitHub, including completion scripts and initialization.

```zsh
zi ice as'program' from'gh-r' pick'zoxide' 
  atclone'ln -s completions/_zoxide -> _zoxide;
  cp man/man1/*.1 $ZI[MAN_DIR]/man1; ./zoxide init zsh --cmd x > init.zsh' 
  atpull'%atclone' src'init.zsh' nocompile'!'
zi light ajeetdsouza/zoxide
```

--------------------------------

### Install jq binary with custom build steps using `zi`

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/06_plugins.mdx

Installs the `jq` binary using `zi`. It includes custom `atclone` steps for building from source and specifies the binary to be installed as `jq`.

```zsh
zi wait lucid for if"(( ! ${+commands[jq]} ))" as"null" \
  atclone"autoreconf -fi && ./configure --with-oniguruma=builtin && make \
  && ln -sfv $PWD/jq.1 $ZI[MAN_DIR]/man1" sbin"jq" \
    stedolan/jq
```

--------------------------------

### Install Git Tools via Meta-Plugins

Source: https://github.com/z-shell/wiki/blob/main/docs/guides/02_customization.mdx

Install a collection of Git tools and annexes using a meta-plugin. This command simplifies the setup of multiple Git extensions and related utilities.

```zsh
zi light-mode for z-shell/z-a-meta-plugins @annexes @ext-git
```

--------------------------------

### Install zchee/zsh-completions

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/02_completions.mdx

Installs the zsh-completions plugin from GitHub.

```zsh
zi ice lucid wait as'completion' blockf
zi light zchee/zsh-completions
```

--------------------------------

### Install sdkman-cli with remote script and self-update

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs 'sdkman-cli' using a remote script for initial setup and configures self-update. It sets up the SDKMAN_DIR and initializes sdkman.

```zsh
zi ice as'program' pick'$ZPFX/sdkman/bin/sdk' id-as'sdkman' run-atpull nocompile \
  atclone'curl -s "https://get.sdkman.io?rcupdate=false" -o scr.sh; SDKMAN_DIR=$ZPFX/sdkman bash scr.sh' \
  atpull'SDKMAN_DIR=$ZPFX/sdkman sdk selfupdate' \
  atinit'export SDKMAN_DIR=$ZPFX/sdkman; source $ZPFX/sdkman/bin/sdkman-init.sh'
zi light z-shell/0
```

--------------------------------

### Install ogham/exa

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'exa' program from the ogham/exa GitHub repository and copies completion scripts.

```zsh
zi ice from'gh-r' as'program' sbin'**/exa -> exa' atclone'cp -vf completions/exa.zsh _exa'
zi light ogham/exa
```

--------------------------------

### Install sharkdp/hyperfine

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'hyperfine' program from the sharkdp/hyperfine GitHub repository.

```zsh
zi ice from'gh-r' as'program' mv"hyperfine* hyperfine" sbin"**/hyperfine(.exe|) -> hyperfine"
zi light @sharkdp/hyperfine
```

--------------------------------

### Install b4b4r07/gotcha

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'gotcha' program from the b4b4r07/gotcha GitHub repository.

```zsh
zi ice as'program' from'gh-r' mv'gotcha_* -> gotcha'
zi light b4b4r07/gotcha
```

--------------------------------

### Load Autosuggestions with Turbo Mode

Source: https://github.com/z-shell/wiki/blob/main/docs/getting_started/02_overview.mdx

This example shows how to use turbo mode with `zsh-users/zsh-autosuggestions`. The `wait lucid atload'!_zsh_autosuggest_start'` ice command defers loading and specifies a function to start the autosuggestions service after loading, ensuring no drawbacks.

```zsh
zi ice wait lucid atload'!_zsh_autosuggest_start'
zi light zsh-users/zsh-autosuggestions
```

--------------------------------

### Install Homebrew from Source Archive

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs Homebrew from its source archive. It updates Homebrew, installs Zsh completions, and compiles the brew.zsh script.

```zsh
zi for as'null' depth'3' nocompletions sbin'bin/brew' \
  atclone'+zi-message "{auto}Installing brew …"; ./bin/brew update --preinstall; \
    ln -sf $PWD/completions/zsh/_brew $ZI[COMPLETIONS_DIR]; \
    rm -f brew.zsh; ./bin/brew shellenv --dummy-arg > brew.zsh; \
    zcompile brew.zsh;' \
  atpull'%atclone' src'brew.zsh' \
    @homebrew/brew
```

--------------------------------

### Start Local Development Server

Source: https://github.com/z-shell/wiki/blob/main/CLAUDE.md

Starts the local development server. Access the site at http://localhost:3000.

```shell
pnpm start
```

--------------------------------

### Install direnv/direnv

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'direnv' program from the direnv/direnv GitHub repository.

```zsh
zi ice as'program' from'gh-r' mv'direnv* -> direnv'
zi light direnv/direnv
```

--------------------------------

### Install sharkdp/fd

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'fd' program from the sharkdp/fd GitHub repository.

```zsh
zi ice from'gh-r' as'program' mv'fd* fd' sbin'**/fd(.exe|) -> fd'
zi light @sharkdp/fd
```

--------------------------------

### Install zgdbm Plugin

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/zsh_modules.mdx

Install the zgdbm plugin using the `zi light` command.

```zsh
zi light z-shell/zgdbm
```

--------------------------------

### Install and Load asciinema

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs asciinema as a program, setting up Python path and compiling it on clone.

```zsh
zi ice as"program" wait lucid atinit"export PYTHONPATH=$ZPFX/lib/python3.10/site-packages/"
  atclone"PYTHONPATH=$ZPFX/lib/python3.10/site-packages/ python3 setup.py --quiet install --prefix $ZPFX"
  test"0" pick"$ZPFX/bin/asciinema"
zi load asciinema/asciinema
```

--------------------------------

### Install mvdan/sh

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'shfmt' program from the mvdan/sh GitHub repository.

```zsh
zi ice as'program' from'gh-r' mv'shfmt* -> shfmt'
zi light mvdan/sh
```

--------------------------------

### Install sharkdp/vivid

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'vivid' program from the sharkdp/vivid GitHub repository.

```zsh
zi ice from'gh-r' as'program' mv'vivid* vivid' sbin'**/vivid(.exe|) -> vivid'
zi light @sharkdp/vivid
```

--------------------------------

### Install junegunn/fzf

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'fzf' program from the junegunn/fzf GitHub repository.

```zsh
zi ice from'gh-r' as'program'
zi light junegunn/fzf
```

--------------------------------

### Install sharkdp/hexyl

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'hexyl' program from the sharkdp/hexyl GitHub repository.

```zsh
zi ice from'gh-r' as'program' mv'hexyl* hexyl' sbin'**/hexyl(.exe|) -> hexyl'
zi light @sharkdp/hexyl
```

--------------------------------

### Install a Meta-Plugin

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/annexes/2_meta_plugins.mdx

Use this command to install a meta-plugin. The '@' prefix is used to avoid syntax conflicts.

```zsh
zi light @annexes
```

--------------------------------

### Install local thefuck completion

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/02_completions.mdx

Installs local completion for thefuck from a specified path.

```zsh
zi ice lucid wait has'thefuck'
zi snippet "$SHELL_COMMON/zsh/thefuck/thefuck.sh"
```

--------------------------------

### Install z-shell/zsh-diff-so-fancy

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'git-dsf' program from the z-shell/zsh-diff-so-fancy collection.

```zsh
zi ice wait lucid as'program' pick'bin/git-dsf'
zi load z-shell/zsh-diff-so-fancy
```

--------------------------------

### Compile Program with Installation Prefix

Source: https://github.com/z-shell/wiki/blob/main/docs/guides/syntax/01_standard.mdx

Compile a program with a specified installation prefix using 'zi ice'. This ensures the program is installed in the desired location, typically under $ZPFX.

```zsh
zi ice as'program' atclone'rm -f src/auto/config.cache; \
  ./configure --prefix=$ZPFX' atpull'%atclone' make'all install' pick'$ZPFX/bin/vim'
zi light vim/vim
```

--------------------------------

### Install cmatrix using standard syntax

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs 'cmatrix' using the standard 'zi ice' syntax. It configures build steps for cloning, pulling, and installation, and picks the final executable.

```zsh
zi ice lucid as'program' atclone"autoreconf -i; ./configure --prefix=$ZPFX" \
  atpull'%atclone' make"install" pick"$ZPFX/bin/cmatrix"
zi light abishekvashok/cmatrix
```

--------------------------------

### Minimal Installation

Source: https://github.com/z-shell/wiki/blob/main/docs/getting_started/01_installation.mdx

Installs Z-Shell with minimal configuration, adding essential setup to your .zshrc file.

```shell
sh -c "$(curl -fsSL get.zshell.dev)" --
```

--------------------------------

### Install ZUI Standalone

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/zui.mdx

Unpack zui and source it in your .zshrc for standalone installation.

```shell
source {where-zui-is}/zui.plugin.zsh
```

--------------------------------

### ZUI Hello World Example

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/zui.mdx

Demonstrates a basic 'Hello World' application using ZUI. It initializes the ZUI environment, sets up a default configuration, and defines a module to display a simple message. This snippet is useful for understanding the fundamental ZUI application structure.

```shell
-zui_std_cleanup deserialize:"zui-demo-hello-world"
-zui_std_init app:"zui-demo-hello-world" app_name:"ZUI Hello World"
emulate -LR zsh -o extended_glob -o type_set_silent -o warn_create_global
-zui_std_init2 # after emulate -LR

-zui_std_store_default_app_config b:border 1

demo_generator_A() {
  local mod="$1" ice="$2"
  # Content, no hyper-links
  reply=( "Hello World from ${ZUI[YELLOW]}ZUI${ZUI[FMT_END]}! Module $mod, instance $ice." )
  # Non-selectable lines   Hops to jump with [ and ]   Local anchors
  reply2=( )               reply3=( 1 )                reply4=( )
}

## Start application ##
zui-event-loop 1:demo_generator_A

-zui_std_cleanup serialize
```

--------------------------------

### Setup and Teardown Blocks

Source: https://github.com/z-shell/wiki/blob/main/community/03_zunit/02_test-syntax.mdx

Demonstrates using @setup to initialize variables before each test and @teardown to clean them up afterward. Shows how state is reset between tests.

```zunit
#!/usr/bin/env zunit

@setup {
  SOME_VAR='rainbows'
}

@teardown {
  unset SOME_VAR
}

@test 'check SOME_VAR' {
  assert $SOME_VAR same_as 'rainbows'
}

@test 'change SOME_VAR' {
  SOME_VAR='unicorns'
  assert $SOME_VAR same_as 'unicorns'
}

@test 'SOME_VAR is reset between tests' {
  # @setup ran again, so SOME_VAR is 'rainbows' again
  run assert $SOME_VAR same_as 'unicorns'
  assert $state equals 1
}
```

--------------------------------

### Install denisidoro/navi

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'navi' program from the denisidoro/navi GitHub repository, requiring 'fzf'.

```zsh
zi ice lucid wait as'program' from"gh-r" has'fzf'
zi light denisidoro/navi
```

--------------------------------

### Install fzf using Zi package manager

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/packages/01_synopsis.mdx

Installs the fzf fuzzy finder and its associated completion script and fzf-tmux executable. This is a simplified installation compared to manual cloning and building.

```zsh
zi lucid as=program pick="$ZPFX/bin/(fzf|fzf-tmux)" \
  atclone="cp shell/completion.zsh _fzf_completion; \
    cp bin/(fzf|fzf-tmux) $ZPFX/bin" \
  make="PREFIX=$ZPFX install" for \
    junegunn/fzf
```

```zsh
zi pack for fzf
```

--------------------------------

### Install Git Extensions with Common Ices and Build Commands

Source: https://github.com/z-shell/wiki/blob/main/docs/guides/syntax/02_for.mdx

Installs several git-related plugins, applying common 'wait', 'lucid', and 'as"null"' ices, along with plugin-specific 'make' commands for installation.

```zsh
zi wait"3" lucid for as"null" \
  sbin Fakerr/git-recall \
  sbin paulirish/git-open \
  sbin paulirish/git-recent \
  sbin davidosomething/git-my \
  make"PREFIX=$ZPFX install" iwata/git-now \
  make"PREFIX=$ZPFX" tj/git-extras
```

--------------------------------

### Install ZUI with Zgen

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/zui.mdx

Use the zgen load command in your .zshrc for installation with Zgen.

```shell
zgen load z-shell/zui.git
```

--------------------------------

### Install pyenv with custom init and clone steps

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs 'pyenv' with custom clone and init steps to set up the PYENV_ROOT and initialize pyenv. It picks the 'bin/pyenv' executable and disables compilation.

```zsh
zi ice atclone'PYENV_ROOT="$PWD" ./libexec/pyenv init - > zpyenv.zsh' \
  atinit'export PYENV_ROOT="$PWD"' atpull"%atclone" \
  as'program' pick'bin/pyenv' src"zpyenv.zsh" nocompile'!'
zi light pyenv/pyenv
```

--------------------------------

### Install asciinema/agg (Annex)

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'agg' tool from the asciinema/agg GitHub repository using the bin-gem-node annex.

```zsh
zi ice has'asciinema' as'program' from'gh-r' sbin'agg* -> agg'
zi light asciinema/agg
```

--------------------------------

### Install Turbo-Loaded Plugins in Dockerfile

Source: https://github.com/z-shell/wiki/blob/main/docs/getting_started/01_installation.mdx

This command is used within a Dockerfile to install Turbo-loaded plugins for Z-Shell (Zi) before the shell starts interactively. It ensures plugins are installed instantly without waiting for a prompt, making it script-friendly.

```dockerfile
RUN zsh -i -c -- '@zi-scheduler burst || true'
```

--------------------------------

### Install vim with custom configure and make steps

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs 'vim' with custom steps for cloning (clearing cache and configuring) and making. It picks the 'src/vim' executable.

```zsh
zi ice as'program' atclone'rm -f src/auto/config.cache; ./configure' \
  atpull'%atclone' make pick'src/vim'
zi light vim/vim
```

--------------------------------

### Install Rustup and Exa (Stderr Redirected)

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs Rustup and Exa, redirecting standard error to /dev/null.

```zsh
zi ice rustup cargo'!E:exa' id-as'exa' as'program' nocompile
zi load z-shell/0
```

--------------------------------

### Install zsh-lint

Source: https://github.com/z-shell/wiki/blob/main/community/04_zsh_lint/index.mdx

Installs the zsh-lint command-line tool using Go's package management.

```sh
go install github.com/z-shell/zsh-lint/cmd/zsh-lint@latest
```

--------------------------------

### Install Gem or Node Module Package

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/packages/01_synopsis.mdx

Use these commands to install Gem or Node modules as packages. The `param` argument specifies the module to install, and `for` indicates the package type.

```zsh
zi pack param='GEM -> rails' for any-gem
zi pack param='MOD -> doctoc' for any-node
```

--------------------------------

### Install Rust and Multiple Crates

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/annexes/9_rust.mdx

Installs Rust and then the 'exa' and 'lsd' crates, making their binaries available.

```zsh
zi ice rustup cargo'exa;lsd'
zi load z-shell/0
```

--------------------------------

### Example Zi Commit Messages

Source: https://github.com/z-shell/wiki/blob/main/community/00_contributing/02_contributing_to_zi.mdx

Examples of conventional commit messages using zi-specific scopes like 'core', 'install', 'ci', 'docs', and 'annex'. These scopes help categorize changes within the zi plugin manager.

```text
fix(core): resolve fpath duplication on plugin reload
feat(annex): expose atdelete hook to external annexes
docs(ci): document workflow trigger conditions
```

--------------------------------

### Manual ZUnit Installation

Source: https://github.com/z-shell/wiki/blob/main/community/03_zunit/01_installation.mdx

Clone the ZUnit repository, build it, make it executable, and copy it to a system-wide binary directory.

```shell
git clone https://github.com/z-shell/zunit.git
cd zunit
./build.zsh
chmod u+x ./zunit
cp ./zunit /usr/local/bin
```

--------------------------------

### Install Rustup and Exa (ls Shim)

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs Rustup and the Exa program, aliasing it to 'ls'.

```zsh
zi ice rustup cargo'!exa -> ls' id-as'exa' as'program' nocompile
zi load z-shell/0
```

--------------------------------

### Example Theme Configuration

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/f-sy-h.mdx

An example INI file demonstrating theme configuration, including base styles and a secondary theme for recursive highlighting.

```ini
; free.ini
[base]
default          = none
unknown-token    = red,bold
; ...
; ...
; ...
secondary        = zdharma
```

--------------------------------

### Automated Setup with Specific Branch

Source: https://github.com/z-shell/wiki/blob/main/docs/getting_started/01_installation.mdx

Installs Z-Shell using a specific branch or tag. Useful for testing or using development versions.

```shell
sh -c "$(curl -fsSL get.zshell.dev)" -- -i skip -b main
```

--------------------------------

### Customize Option Highlighting

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/h-s-mw.mdx

Enable coloring for options that start with a single or double hyphen using the `HSMW_HIGHLIGHT_STYLES` array. This example sets them to be cyan.

```zsh
typeset -gA HSMW_HIGHLIGHT_STYLES
HSMW_HIGHLIGHT_STYLES[single-hyphen-option]="fg=cyan"
HSMW_HIGHLIGHT_STYLES[double-hyphen-option]="fg=cyan"
```

--------------------------------

### Advanced multisrc Usage with Patterns

Source: https://github.com/z-shell/wiki/blob/main/docs/guides/syntax/01_standard.mdx

Patterns can be used with `multisrc` to load files matching a glob. This example loads files starting with 'funct' or 'misc'.

```zsh
zi ice multisrc'{funct*,misc}.zsh' pick'/dev/null'
zi light some/plugin
```

--------------------------------

### Initialize New ZUnit Project

Source: https://github.com/z-shell/wiki/blob/main/community/03_zunit/01_installation.mdx

Use the `zunit init` command to set up a new ZUnit project structure, including configuration and test directories.

```shell
cd my-project
zunit init
```

--------------------------------

### Install z-shell/zunit

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'zunit' program from the z-shell/zunit collection, with build and pull hooks.

```zsh
zi ice wait lucid as'program' pick'zunit' atclone'./build.zsh' atpull'%atclone'
zi load z-shell/zunit
```

--------------------------------

### Install mfaerevaag/wd

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'wd' program from the mfaerevaag/wd collection, with custom pull hook.

```zsh
zi ice wait lucid as'program' cp'wd.sh -> wd' 
  mv'_wd.sh -> _wd' atpull'!git reset --hard' pick'wd'
zi light mfaerevaag/wd
```

--------------------------------

### Install yank with make

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs 'yank' using the 'make' command and 'pick' to select the executable.

```zsh
zi ice as'program' pick'yank' make
zi light mptre/yank
```

--------------------------------

### Configure zconvey in Zi Turbo Mode

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/zconvey.mdx

Example configuration for loading zconvey in Zi's turbo mode. This setup optimizes plugin loading.

```zsh
zi ice wait"0"
zi light z-shell/zconvey
```

--------------------------------

### Install Bun Completion

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/02_completions.mdx

Installs Bun shell completions. This command fetches the completion script and sets it up.

```zsh
zi ice lucid wait as'completion' blockf has'bun'
zi snippet https://github.com/oven-sh/bun/blob/main/completions/bun.zsh
```

--------------------------------

### Install Zprompts Standalone

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/zprompts.mdx

Load the Zprompts plugin manually by sourcing the plugin file and then initializing and setting a theme.

```shell
source {where-zprompts-is}/zprompts.plugin.zsh
```

```shell
promptinit
prompt scala3
```

--------------------------------

### Download, build, and install Subversion

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/packages/02_usage.mdx

Use this command to download, build, and install the latest Subversion package.

```zsh
zi pack for subversion
```

--------------------------------

### Install and Load Redis Service

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/05_services.mdx

Installs the Redis service using 'zi ice' and then loads it with 'zi light'.

```zsh
zi ice wait lucid service"redis"
zi light z-shell/redis
```

--------------------------------

### Standalone ZCA Installation

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/zsh_comand_architect.mdx

Execute this command to install ZCA using a standalone script. The script handles installation, configuration file copying, and .zshrc updates. Re-running the command updates the installation.

```shell
sh -c "$(curl -fsSL https://raw.githubusercontent.com/z-shell/zsh-cmd-architect/main/doc/install.sh)"
```

--------------------------------

### Install Zsh Annexes

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/01_collection.mdx

Use this command to install required annexes for Zsh, which may be needed for certain installations.

```zsh
zi light-mode for z-shell/z-a-meta-plugins @annexes
```

--------------------------------

### Install zconvey as Standalone Plugin

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/zconvey.mdx

Install zconvey by unpacking it to a directory and sourcing the plugin file in your .zshrc. This method is for manual installation.

```shell
source {where-zconvey-is}/zconvey.plugin.zsh
```

--------------------------------

### Install Git Completion

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/02_completions.mdx

Installs Git shell completions. It renames the completion file to '_git' and sets it up.

```zsh
zi ice lucid wait as'completion' blockf mv'git-completion.zsh -> _git'
zi snippet https://github.com/git/git/blob/master/contrib/completion/git-completion.zsh
```

--------------------------------

### Install zpmod using Zi (Build and Info)

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/zsh_modules.mdx

Build the zpmod module using `zi module -B` and display loading instructions with `zi module -I`. Use `--clean` with `-B` to run `make distclean`.

```zsh
zi module [-B|--build[--clean]] [-I|--info] [-r|--reset] [-h|--help] [options]
```

```zsh
zi module -B [--clean]  # Build the module, append --clean to run distclean.
```

```zsh
zi module -I            # Display instructions on loading the module.
```

```zsh
zi module -r            # Check timestamps and rebuild the module if needed.
```

--------------------------------

### Install Plugin as a Program

Source: https://github.com/z-shell/wiki/blob/main/docs/getting_started/02_overview.mdx

Use 'zi ice as"program"' to add a plugin directory to your PATH, copy and rename a script, and make it executable.

```zsh
zi ice as"program" cp"httpstat.sh -> httpstat" pick"httpstat"
zi light b4b4r07/httpstat
```

--------------------------------

### Install Dependencies

Source: https://github.com/z-shell/wiki/blob/main/CLAUDE.md

Install project dependencies using pnpm. Ensure Node.js version >= 22 and pnpm version >= 10 are installed.

```shell
pnpm install
```

--------------------------------

### Install Z-Shell (Zi) via Script

Source: https://github.com/z-shell/wiki/blob/main/docs/getting_started/01_installation.mdx

Use this command to initiate the Z-Shell (Zi) installation process using a script from get.zshell.dev. The -a ??? argument is a placeholder for potential arguments.

```shell
sh -c "$(curl -fsSL get.zshell.dev)" -- -a ???
```

--------------------------------

### Install zsh-diff-so-fancy with Zi (Recommended)

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/diff-so-fancy.mdx

Use the bin-gem-node annex for recommended installation. This adds diff-so-fancy, fancy-diff, and git-dsf to your PATH and equips git with the dsf subcommand.

```zsh
zi ice as'null' sbin'bin/*'
zi light z-shell/zsh-diff-so-fancy
```

--------------------------------

### Install nnn from Binary Archive

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the nnn file manager from its binary archive. It specifically picks the 'quitcd.zsh' script for program installation.

```zsh
zi light-mode for pick'misc/quitcd/quitcd.zsh' as'program' nocompile \
  sbin make \
    jarun/nnn
```

--------------------------------

### Minimal Installation with Loader

Source: https://github.com/z-shell/wiki/blob/main/docs/getting_started/01_installation.mdx

Installs Z-Shell with minimal configuration and the loader module. The installer downloads the loader and adds the necessary snippet to .zshrc.

```shell
sh -c "$(curl -fsSL get.zshell.dev)" -- -a loader
```

```zsh
if [[ -r "${XDG_CONFIG_HOME:-"${HOME}"/.config}/zi/init.zsh" ]]; then
  source "${XDG_CONFIG_HOME:-"${HOME}"/.config}/zi/init.zsh" && zzinit
fi
```

--------------------------------

### Install zoxide with Eval

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/annexes/19_eval.mdx

This snippet shows how to install zoxide using the 'zi' command with the Eval annex. The 'eval' keyword caches the output of the initialization command.

```zsh
zi ice as"command" from"gh-r" \
  eval"./zoxide init --cmd x zsh"
zi light ajeetdsouza/zoxide
```

--------------------------------

### Minimal Installation with ZUnit

Source: https://github.com/z-shell/wiki/blob/main/docs/getting_started/01_installation.mdx

Installs Z-Shell with minimal configuration, recommended annexes, and sets up ZUnit for testing. This is for users who need testing capabilities.

```shell
sh -c "$(curl -fsSL get.zshell.dev)" -- -a zunit
```

--------------------------------

### Install Multiple Tools from GitHub Releases

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs fzf, fd, bat, and exa from their respective GitHub releases. It also copies the exa Zsh completion script.

```zsh
zi from"gh-r" as"null" for \
  sbin"fzf" junegunn/fzf \
  sbin"**/fd" @sharkdp/fd \
  sbin"**/bat" @sharkdp/bat \
  sbin"**/exa -> exa" atclone"cp -vf completions/exa.zsh _exa" ogham/exa
```

--------------------------------

### Install Pip Package with Zi

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/annexes/1_bin_gem_node.mdx

Use `pip'` to install a Python package. The second form allows aliasing the installed binary to a different function name.

```shell
pip'{pip-package}; …'
pip'[{path-to-binary} <-] !{pip-package} [-> {name-of-the-function}]; …'
```

--------------------------------

### Find Directories and List First Item

Source: https://github.com/z-shell/wiki/blob/main/community/01_zsh_guide/01_roadmap/10_expansion.mdx

This complex example finds all directories, lists their contents, and outputs the first item of each.

```zsh
print -rl /home/me/**/*(D/e{'reply=($REPLY/*(N[-1]:t))'})
```

--------------------------------

### Install Node.js Module with Zi

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/annexes/1_bin_gem_node.mdx

Use `node'` to install a Node.js module. The second form allows aliasing the installed binary to a different function name.

```shell
node'{node-module}; …'
node'[{path-to-binary} <-] !{node-module} [-> {name-of-the-function}]; …'
```

--------------------------------

### Install neofetch with man page copy

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs 'neofetch'. It copies the man page during clone and pulls updates.

```zsh
zi ice lucid wait as'program' pick'neofetch' \
  atclone"cp neofetch.1 $ZI[MAN_DIR]/man1" atpull'%atclone'
zi light dylanaraps/neofetch
```

--------------------------------

### Install Apache Portable Runtime (APR) library

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/packages/02_usage.mdx

Installs the latest Apache Portable Runtime (APR) library from its source tarball. This is the default installation method.

```zsh
zi pack for apr
```

--------------------------------

### Install obihann/archey-osx

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'archey' program from the obihann/archey-osx collection.

```zsh
zi ice wait lucid as'program' pick'bin/archey'
zi light obihann/archey-osx
```

--------------------------------

### Loading Custom Completions

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/02_completions.mdx

Demonstrates how to load custom completion functions. Use 'has'...' to specify the command and 'pick'...' to select specific completion files.

```zsh
zi_completion has'…'
zi snippet …

zi_completion has'…' pick'…' from'…'
zi light …

zi_completion has'…'
zi snippet …
```

--------------------------------

### ZNT List Configuration Example

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/zsh_navigation_tools.mdx

Example configuration for n-list.conf, demonstrating settings for text boldness, color pairs, border drawing, and color themes.

```shell
# Should the list (text, borders) be drawn in bold
local bold=0

# Main color pair (foreground/background)
local colorpair="white/black"

# Should draw the border?
local border=1

# Combinations of colors to try out with Ctrl-T and Ctrl-G
# The last number is the bold option, 0 or 1
local -a themes
themes=(
  "white/black/1" "green/black/0" "green/black/1" "white/blue/0"
  "white/blue/1" "magenta/black/0" "magenta/black/1"
)
```

--------------------------------

### Install z-shell/revolver

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'revolver' program from the z-shell/revolver collection.

```zsh
zi ice wait lucid as'program' pick'revolver'
zi light z-shell/revolver
```

--------------------------------

### Install cmatrix using 'for' syntax

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs 'cmatrix' using the 'zi for' syntax. It specifies build steps for cloning, pulling, and installation, and picks the final executable.

```zsh
zi for as'program' atclone"autoreconf -i; ./configure --prefix=$ZPFX" \
  atpull'%atclone' make"all install" pick"$ZPFX/bin/cmatrix" \
    abishekvashok/cmatrix
```

--------------------------------

### Install eth-p/bat-extras

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs programs from eth-p/bat-extras, requiring 'bat' to be present.

```zsh
zi ice lucid wait as'program' has'bat' pick'src/*'
zi light eth-p/bat-extras
```

--------------------------------

### Install with Zi

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/h-s-mw.mdx

Add this line to your .zshrc file to install the plugin using Zi. Reload the shell afterwards.

```zsh
zi light z-shell/H-S-MW
```

--------------------------------

### Install direnv with make and hook script

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs 'direnv'. It runs 'make !' (likely to build), copies a hook script during clone, and pulls updates.

```zsh
zi ice as'program' make'!' atclone'./direnv hook zsh > zhook.zsh' \
  atpull'%atclone' src'zhook.zsh'
zi light direnv/direnv
```

--------------------------------

### Install asciinema/agg (Default)

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'agg' tool from the asciinema/agg GitHub repository using the default Zinit annex.

```zsh
zi ice has'asciinema' as'program' from'gh-r' 
  mv'agg* -> agg' pick'agg'
zi light asciinema/agg
```

--------------------------------

### Zi 'equal' Syntax for Plugin Configuration

Source: https://github.com/z-shell/wiki/blob/main/docs/guides/syntax/01_standard.mdx

Demonstrates loading a plugin using the 'equal' syntax for ice-modifiers and specifying a command to run on atload.

```zsh
zi ice id-as=equal atload="print Hello World"
zi load z-shell/0
```

--------------------------------

### Install wl-clipboard Completions

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/02_completions.mdx

Installs wl-clipboard shell completions for both copy and paste commands. This command fetches the completion scripts and sets them up.

```zsh
zi ice lucid wait as'completion' blockf has'wl-copy'
zi snippet https://github.com/bugaevc/wl-clipboard/blob/master/completions/zsh/_wl-copy

zi ice lucid wait as'completion' blockf has'wl-paste'
zi snippet https://github.com/bugaevc/wl-clipboard/blob/master/completions/zsh/_wl-paste
```

--------------------------------

### Install zsh-diff-so-fancy with Zi (Standard)

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/plugins/diff-so-fancy.mdx

Standard installation using Zi. This adds diff-so-fancy, fancy-diff, and git-dsf to your PATH and equips git with the dsf subcommand.

```zsh
zi ice as'program' pick'bin/*'
zi light z-shell/zsh-diff-so-fancy
```

--------------------------------

### Install sharkdp/bat

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'bat' program from the sharkdp/bat GitHub repository.

```zsh
zi ice from'gh-r' as'program' mv'bat* bat' sbin'**/bat(.exe|) -> bat'
zi light @sharkdp/bat
```

--------------------------------

### Install Seirdy/stpv without specific dependency

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'stpv' program using 'pick' to select the executable, without specifying additional dependencies.

```zsh
zi ice lucid wait as'program' pick'stpv'
zi light Seirdy/stpv
```

--------------------------------

### Install dandavison/delta

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs the 'delta' program from the dandavison/delta GitHub repository.

```zsh
zi ice wait lucid as'program' from'gh-r' sbin'**/delta -> delta'
zi light dandavison/delta
```

--------------------------------

### Install zoxide completion

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/02_completions.mdx

Installs zoxide completion from a remote URL.

```zsh
zi ice wait lucid as'completion' blockf has'zoxide'
zi snippet https://github.com/ajeetdsouza/zoxide/blob/main/contrib/completions/_zoxide
```

--------------------------------

### Basic Globbing Example

Source: https://github.com/z-shell/wiki/blob/main/community/01_zsh_guide/01_roadmap/10_expansion.mdx

Demonstrates a simple glob pattern to list all .txt files recursively in a directory.

```shell
ls ~/**/*.txt # <- THIS IS A GLOB
```

--------------------------------

### Install ghq completion

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/02_completions.mdx

Installs ghq completion from a remote URL.

```zsh
zi ice lucid wait as'completion' blockf has'ghq'
zi snippet https://github.com/x-motemen/ghq/blob/master/misc/zsh/_ghq
```

--------------------------------

### Install yadm completion

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/02_completions.mdx

Installs yadm completion from a remote URL.

```zsh
zi ice lucid wait as'completion' blockf has'yadm'
zi snippet https://github.com/yadm-dev/yadm/blob/master/completion/zsh/_yadm
```

--------------------------------

### Install Firefox using bin-gem-node

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/annexes/1_bin_gem_node.mdx

Installs Firefox using the bin-gem-node annex. This command leverages Zi's package management capabilities to fetch and install the specified application.

```zsh
zi pack=bgn for firefox
```

--------------------------------

### Install Zinc Theme

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/07_themes.mdx

Installs the Zinc theme, compiling necessary files and setting up precmd hooks for prompt initialization.

```zsh
zi ice wait'!' lucid nocompletions \
  compile"{zinc_functions/*,segments/*,zinc.zsh}" \
  atload'!prompt_zinc_setup; prompt_zinc_precmd'
zi load robobenklein/zinc
```

--------------------------------

### Zplug basics with ZI

Source: https://github.com/z-shell/wiki/blob/main/docs/getting_started/03_migration.mdx

Migrate Zplug configurations like `zplug <repo/plugin>, tag1:<option1>, tag2:<option2>` to ZI's `zi ice tag1"<option1>" tag2"<option2>"` and `zi load <repo/plugin>`.

```diff
- zplug <repo/plugin>, tag1:<option1>, tag2:<option2>

+ zi ice tag1"<option1>" tag2"<option2>"
+ zi load <repo/plugin>
```

--------------------------------

### Load pure Theme

Source: https://github.com/z-shell/wiki/blob/main/src/components/Markdown/_multiple_prompts_example.mdx

Loads the 'pure' theme. This example configures 'pick' and 'multisrc' options, uses an 'atload' hook, and employs 'zi lucid' for theme management.

```shell
zi lucid load'![[ $MYPROMPT = 5 ]]' unload'![[ $MYPROMPT != 5 ]]' \
  pick"/dev/null" multisrc"{async,pure}.zsh" atload'!prompt_pure_precmd' nocd for \
    sindresorhus/pure
```

--------------------------------

### Install the newest Zsh

Source: https://github.com/z-shell/wiki/blob/main/ecosystem/packages/02_usage.mdx

Use this command to install the newest Zsh package.

```zsh
zi pack for zsh
```

--------------------------------

### Install Rustup for Exa and LSD

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs Rustup to manage both Exa and LSD.

```zsh
zi ice rustup cargo'exa;lsd' nocompile
zi load z-shell/0
```

--------------------------------

### Install Rustup and LSD

Source: https://github.com/z-shell/wiki/blob/main/community/gallery/collection/03_programs.mdx

Installs Rustup and the LSD program without compilation.

```zsh
zi ice rustup cargo'!lsd' id-as'lsd' as'program' nocompile
zi load z-shell/0
```
Tokens:
Raw