jj / How jj util completion works

How jj util completion works

jj util completion prints a static shell-completion script generated from jj's clap command tree.

On this page
  1. 1. Command-line surface
  2. 3. End-to-end flow
  3. 4. Core architecture touchpoints

In short: it hands a copy of the CLI definition to clap_complete (or clap_complete_nushell) and writes the script to stdout. That script knows subcommands and flags only. jj's other completion mode, the "dynamic" one, doesn't use this command: the shell runs jj itself with COMPLETE set, which can also complete bookmarks, revisions, operations and files (docs).

The command is cmd_util_completion. Its help text: "Print a command-line-completion script", followed by how to load it in each shell (source). It is the Completion variant of UtilCommand (source, dispatch).

1. Command-line surface

ArgumentTypeDefaultMeaning
SHELL (positional, required)one of six namesnonebash, elvish, fish, nushell, power-shell or zsh (source, ShellCompletion).

For example source <(jj util completion bash); the dynamic equivalent is source <(COMPLETE=bash jj) (docs). The global flags are on the CLI page.

3. End-to-end flow

jj util completion: call flow, and the dynamic alternative cmd_util_completion clones the clap command, and ShellCompletion::generate calls clap_complete's generate for the chosen shell, or clap_complete_nushell for Nushell, with the binary name jj. The script is written to stdout. Separately, when the COMPLETE environment variable is set, CliRunner skips normal parsing and calls handle_shell_completion, which runs clap_complete's CompleteEnv against the command tree. command.app().clone() the full clap command tree ShellCompletion::generate clap_complete::generate(shell, cmd, "jj") not this command: dynamic completion COMPLETE set → handle_shell_completion checked before argument parsing clap_complete::CompleteEnv candidates from cli/src/complete.rs

4. Core architecture touchpoints

PieceRole here
The clap command tree (command.app())The only input. Because it is the same tree jj parses with, the script lists every subcommand and flag of this build, including ones a custom binary adds.
clap_complete, clap_complete_nushellThe generators, declared in the workspace Cargo.toml; clap_complete is built with its unstable-dynamic feature for the dynamic mode (source).
cli/src/complete.rsThe candidate functions (bookmarks, revisions, operations, files and so on) that only dynamic completion uses.
Repo, working copy, operation logNot touched: cmd_util_completion never asks for a workspace. Upstream's test checks each of the six shells prints to stdout only (test).