Completion System

## What compsys actually is zsh's modern completion system, usually called compsys, is not a builtin table of rules. It is a large collection of ordinary zsh **functions** that ship with zsh, plus whatever functions you or your packages add. When you press Tab, zsh works out the context (which command you are typing, which argument you are on) and calls the function registered for that command. Because these are just functions, getting a new completion to work is the same problem as getting any autoloadable function to work: zsh has to be able to find it, and it has to be told the function exists. ## fpath: the search path for functions `fpath` is an array parameter — the function equivalent of `PATH`. When a function is marked autoloadable, zsh does not read its body until the first call; at that point it searches each directory in `fpath` for a file named after the function and loads it. Completion functions live in files named with a leading underscore (`_mytool`, `_git`, `_ssh`), which is a naming convention, not a requirement of the shell. Distributions and package managers install their completion files into a directory that is on `fpath` by default, typically a `site-functions` directory under the zsh share path. A tool that installs somewhere else — say into `~/.local/share/zsh/completions` — needs that directory added yourself: ```bash fpath=(~/.local/share/zsh/completions $fpath) ``` ## compinit: what initialisation does Adding to `fpath` alone changes nothing for completion. The registration step is `compinit`: ```bash autoload -Uz compinit compinit ``` `autoload -Uz compinit` marks the `compinit` function itself as autoloadable (`-U` suppresses alias expansion while loading, `-z` forces zsh-style autoloading — both are defensive flags you should just always use). Calling `compinit` then walks every directory in `fpath`, looks at each file whose name starts with `_`, and reads its **first line**, the `#compdef` tag line: ```bash #compdef mytool ``` That line is a comment as far as the shell is concerned, but compinit parses it to build the mapping from command name to completion function. It also defines the `compdef` function, installs the completion widgets on the keymap, and sets up the machinery the completion functions rely on. ## Why the order in .zshrc matters The scan happens once, when `compinit` is called. Appending a directory to `fpath` *after* that call means compinit never saw it, so the file is never registered — the single most common reason a freshly installed completion appears to do nothing. Put every `fpath` modification above the `compinit` call. ## The dump file Scanning every file in every `fpath` directory on each shell start would be slow, so compinit writes what it learned to a dump file, by default `${ZDOTDIR:-$HOME}/.zcompdump`, and reuses it on subsequent starts. compinit does try to notice when the set of completion files has changed and rebuild, but the check is not perfect, and it is skipped entirely if you call `compinit -C` for faster startup. The standard cure when a new completion refuses to appear is: ```bash rm -f ~/.zcompdump && compinit ``` Or just start a fresh shell after removing the dump. You can also point compinit at an explicit dump file with `compinit -d <file>`, which is useful when several zsh configurations share a home directory. ## What is not the problem Completion files do not need the execute bit — they are read by the shell, not executed as programs. They should not be sourced from `.zshrc`; sourcing `_mytool` directly would run its body outside a completion context and typically error. And the leading underscore matters: compinit only considers files that look like completion functions. ## Checking your work After re-running `compinit`, `echo $_comps[mytool]` prints the function name registered for that command (`_comps` is the association compinit builds), and `which _mytool` shows whether the function loaded. If `_comps[mytool]` is empty, the file is either not on `fpath`, missing or misspelling its `#compdef` line, or masked by a stale dump.