You ship a command-line tool called `deploytool` and want `deploytool <TAB>` to complete its subcommands in bash. Which bash builtins and shell variables implement that, and where does the completion script get installed?

## The pieces Bash's completion system has three parts: the `complete` builtin that registers a *completion spec* for a command name, the `compgen` builtin that generates candidate words, and a set of `COMP_*` variables that carry the context into your function. ## Simple cases without a function ```bash complete -W "start stop status restart" deploytool # fixed word list complete -d cd_to_project # directories only complete -c which # command names complete -F _deploytool deploytool # call a function ``` `complete -p deploytool` prints the spec currently registered, and `complete -r deploytool` removes it. Useful `-o` modifiers include `-o default` (fall back to bash's normal filename completion if the spec produces nothing), `-o nospace` (do not append a trailing space, for completing a path prefix) and `-o filenames` (treat results as filenames so bash escapes them and marks directories). ## The function protocol When bash calls a `-F` function it sets: - `COMP_WORDS` — an array of the words on the current command line. - `COMP_CWORD` — the index into that array of the word the cursor is in. - `COMP_LINE` and `COMP_POINT` — the raw line and cursor offset, for the rare case you need to re-parse yourself. The function's return value carries no candidates; its job is to assign them into the `COMPREPLY` array. Bash takes it from there — it inserts the single candidate, or lists them on a second Tab. ```bash _deploytool() { local cur prev cur=${COMP_WORDS[COMP_CWORD]} prev=${COMP_WORDS[COMP_CWORD-1]} if [ "$COMP_CWORD" -eq 1 ]; then COMPREPLY=( $(compgen -W "start stop status restart" -- "$cur") ) return fi case $prev in start|restart) COMPREPLY=( $(compgen -W "--env --dry-run" -- "$cur") ) ;; --env) COMPREPLY=( $(compgen -W "dev staging prod" -- "$cur") ) ;; *) COMPREPLY=( $(compgen -f -- "$cur") ) ;; esac } complete -F _deploytool deploytool ``` The `-- "$cur"` argument to `compgen` is what filters the list down to what the user has already typed; forgetting it is the most common beginner bug, because bash then offers every candidate regardless of prefix. ## compgen as a generator `compgen` shares `complete`'s generator options but writes matches to standard output instead of registering anything, so it is also useful on its own — `compgen -c ssh` lists commands starting with `ssh`, and `compgen -W "$(deploytool list-envs)" -- "$cur"` builds candidates from the tool's own output. Calling out to the tool on every Tab is convenient but costs a process per completion, so cache anything slow. `compopt` changes options for the completion in progress, for example `compopt -o nospace` when you are completing a `key=` prefix the user will keep typing. ## Where the script lives Completion specs are per-shell state, so they must be registered in every session — which is what the `bash-completion` package automates. Two locations matter: - `/usr/share/bash-completion/completions/` — install a file **named exactly after the command** (`deploytool`). bash-completion registers a lazy loader, so the file is sourced only the first time someone completes that command. This is the modern, fast path and where a distribution package should put the file. - `/etc/bash_completion.d/` — the legacy directory, whose contents are sourced eagerly at shell startup. It still works, but every file there is a tax on every shell start. For a single user, sourcing the file from `~/.bashrc` is fine. Note that none of this happens unless bash-completion itself is loaded; a minimal container or a stripped `~/.bashrc` simply gets bash's default filename completion. ## Generated completions Many CLI frameworks emit a completion script for you — the usual pattern is a subcommand that prints one to standard output, which the user then evaluates or redirects into the completions directory. Generating beats hand-maintaining, because a hand-written script drifts out of date the moment a flag is added. ## What can go wrong - Unquoted expansion in `COMPREPLY=( $(compgen ...) )` splits candidates containing spaces; use `mapfile -t COMPREPLY < <(compgen ...)` when candidates may contain whitespace. - A completion function that prints to standard output corrupts the display — keep it silent. - A slow function makes Tab feel broken, because the user is blocked while it runs.