jj / How jj help works

How jj help works

jj help prints the long help of jj or of a subcommand, the same text as --help, or one of the user docs that are compiled into the binary.

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

In short: clap's own help subcommand is turned off and replaced by this command. With -k, it prints an embedded Markdown doc through the pager. Otherwise it re-parses the named commands against the CLI definition, walks down to the subcommand, and prints its long help. It never loads a repo.

The command is cmd_help. Its help text: "Print this message or the help of the given subcommand(s)" (source). It is the Help variant of the top-level Command enum (source, dispatch), which also sets disable_help_subcommand so clap doesn't add its own (source).

1. Command-line surface

ArgumentTypeDefaultMeaning
COMMAND… (positional)stringsnone"Print help for the subcommand(s)", for example jj help workspace root (source).
-k, --keyword KEYWORDone of seven namesnone"Show help for keywords instead of commands". Conflicts with COMMAND. The values are bookmarks, config, filesets, glossary, revsets, templates and tutorial (source, KEYWORDS).

HelpArgs. The top-level long help ends with a hint pointing at jj help -k (source). The global flags are on the CLI page.

3. End-to-end flow

jj help: call flow If --keyword is given, cmd_help finds the keyword, requests the pager and prints its embedded Markdown. Otherwise it builds an argument list of the binary name and the given commands and parses it with a clone of the CLI definition, returning clap's error only for an unknown subcommand. It then walks down the given names with find_subcommand_mut, failing with "Unknown command" if one is missing, requests the pager, and prints render_long_help, in colour if the UI is coloured. --keyword given? yes → pager, print embedded doc parse [bin, COMMAND…] with a clone only InvalidSubcommand is an error find_subcommand_mut for each name missing → "Unknown command: …" request_pager; render_long_help ANSI styles only if ui.color() KEYWORDS docs/*.md, include_str! at compile time no

4. Core architecture touchpoints

PieceRole here
The clap command tree (command.app())Cloned and parsed so global arguments propagate to subcommands before help is rendered (source). That is why jj help log prints exactly what jj log --help does (test).
KEYWORDSSeven Markdown files from docs/, embedded with include_str!, so the binary carries its own copy. jj help -k revsets prints docs/revsets.md byte for byte (test).
UiBoth paths call request_pager, so output goes through ui.pager on a terminal; keyword docs are printed as raw Markdown (source, TODO).
Repo, working copy, operation logNot touched: cmd_help never asks for a workspace.

Errors and edge cases

InputResult
jj help unknownclap's unrecognized subcommand 'unknown' with a "similar subcommand" tip, exit 2 (test).
jj help log -- -rError: Unknown command: log -r, exit 2 (test).
jj workspace help roothelp is only top-level: unrecognized subcommand 'help' (test).
jj help -k revclap rejects the value, lists the seven keywords and suggests revsets (test).
jj help revsetsKeywords need -k; without it this is an unknown subcommand (test).