Advanced Zsh: Completion System Techniques

What Is the Zsh Completion System?

The Z shell (Zsh) completion system is a sophisticated framework that provides context‑sensitive tab‑completion for commands, arguments, options, paths, and even custom data structures. Unlike simpler shells, Zsh offers a fully programmable completion system that can adapt to any command’s syntax, read from external data sources, and present completions in a rich, interactive menu. At its core, the system is built around completion functions (often stored in _* files) that describe how to generate candidates for a given command or context.

The completion system is split into two layers: the completion core (built into Zsh) and the completion functions (usually installed via compinstall or a plugin manager like Oh My Zsh or zinit). The core handles user interaction (menu selection, filtering, etc.), while the functions define what to complete.

Why It Matters

Effective use of the completion system dramatically improves productivity. Instead of typing long paths, remembering obscure flags, or consulting man pages constantly, you can let Zsh do the heavy lifting. Advanced techniques allow you to:

Complete Git branches, tags, and remote names without leaving your terminal.
Provide intelligent completions for custom scripts, project‑specific commands, or even database schemas.
Create dynamic completions that query APIs, read files, or parse configuration on the fly.
Optimise performance with caching and lazy loading.
Customise the appearance and behaviour of completion menus (colors, grouping, sorting).

For developers, system administrators, and power users, mastering these techniques transforms the shell from a simple command interpreter into a true productivity tool.

Understanding the Completion System Architecture

🚀 Deploy your AI agent in 10 minutes

Managed Hermes hosting. Zero DevOps. 100M tokens/mo included.

Try it free →

The Completion Context

Every completion request is processed within a context. The context includes the current command, its arguments, the cursor position, and environment variables. Completion functions use this context to decide what to propose. The system provides standard contexts like _arguments (for option parsing), _files (for file paths), and _describe (for simple lists).

Completion Functions and the `fpath`

Completion functions are stored in directories listed in the fpath array. Each function is named after the command it completes, prefixed with an underscore (e.g., _git, _docker). When you type Tab after git, Zsh loads _git if not already loaded. The function then uses helper functions like _arguments to parse the command line and generate suggestions.

# Example: a minimal completion function for a custom command 'myapp'
# Save as ~/.zsh/completions/_myapp and add that directory to fpath

#compdef myapp

_myapp() {
  local -a subcommands
  subcommands=(
    'start:Start the application'
    'stop:Stop the application'
    'status:Show status'
    'restart:Restart the application'
  )

  _describe 'myapp subcommands' subcommands
}

_myapp "$@"

How to Use the Completion System

Basic Setup and Activation

To use the advanced completion features, ensure the completion system is loaded in your .zshrc:

# Enable completion system (usually done by compinstall or plugin manager)
autoload -Uz compinit
compinit

# Optionally use menu selection (arrow keys to choose)
zstyle ':completion:*' menu select

# Enable caching for slower completions
zstyle ':completion:*' use-cache yes
zstyle ':completion:*' cache-path ~/.zsh/cache

Writing Custom Completion Functions

Let’s build a more advanced example: a completion function for a fictional tool deploy that manages deployment environments. The tool accepts options --env, --branch, and a subcommand (push, rollback). We want to complete environment names from a config file and branch names from Git.

# ~/.zsh/completions/_deploy

#compdef deploy

_deploy() {
  local context state line
  typeset -A opt_args

  _arguments -C \
    '--env[Deployment environment]:environment:->envs' \
    '--branch[Git branch]:branch:->branches' \
    ':subcommand:->subcmds' \
    && return 0

  case $state in
    envs)
      # Read environments from a JSON config file using jq
      if _cache_invalid deploy_envs || ! _retrieve_cache deploy_envs; then
        local -a envs
        envs=( $(jq -r '.environments[]' ~/.deploy_config.json 2>/dev/null) )
        _store_cache deploy_envs envs
      fi
      _wanted environments expl 'environment' compadd -a envs
      ;;
    branches)
      # Complete local Git branches (assumes we are in a repo)
      _wanted branches expl 'branch' _git_branches
      ;;
    subcmds)
      local -a subcmds
      subcmds=('push:Push deployment' 'rollback:Rollback to previous')
      _describe 'subcommand' subcmds
      ;;
  esac
}

_deploy "$@"

This function demonstrates several advanced techniques:

_arguments -C – parses command line options and subcommands with context.
_cache_invalid / _retrieve_cache / _store_cache – caches the list of environments to avoid re‑reading the JSON file on every tab press.
_wanted and compadd -a – standard way to add completions with tags.
_git_branches – reuses Zsh’s built‑in Git completion helper.

Advanced Techniques

Matchers and Completion Styles

Zsh allows you to customise how completions are matched and displayed using zstyle. For example, you can enable case‑insensitive matching, partial‑word matching, or even “approximate” matching (fuzzy). This is extremely useful when you’re not sure of the exact spelling.

# Case-insensitive matching for all completions
zstyle ':completion:*' matcher-list 'm:{a-zA-Z}={A-Za-z}' 'r:|[._-]=* r:|=*' 'l:|=* r:|=*'

# Enable approximate matching (fuzzy) with up to 1 error
zstyle ':completion:*' completer _complete _approximate
zstyle ':completion:*:approximate:*' max-errors 1

# Group results by tag (e.g., files, options, subcommands)
zstyle ':completion:*' group-name ''
zstyle ':completion:*' format ' %F{yellow}-- %d --%f'
zstyle ':completion:*:descriptions' format ' %F{blue}-- %d --%f'

# Use menu selection with highlighting
zstyle ':completion:*' menu select=2
zstyle ':completion:*:default' list-colors ${(s.:.)LS_COLORS}