Packaging, Completions, and Docs Generation

This tooling turns ripgrep’s flag metadata into shell completion scripts, help text, and a man page. The flag module owns completion, --help, and man-page generation alongside flag parsing and validation.

It exists so these user-facing outputs can be assembled from shared flag information rather than maintained as unrelated descriptions. The generators read flag names, documentation, choices, negations, or categories according to the output they produce.

Sources: crates/core/flags/mod.rs:1-7, crates/core/flags/complete/bash.rs:63-107, crates/core/flags/complete/fish.rs:13-75, crates/core/flags/doc/help.rs:24-54

Core concepts

Flag metadata

Flag metadata provides names, documentation, choices, completion behavior, negated forms, and documentation categories to the generators.

Sources: crates/core/flags/complete/bash.rs:63-107, crates/core/flags/complete/fish.rs:13-75, crates/core/flags/doc/help.rs:24-54

Generation mode

A generation mode selects the man page or one of four supported completion scripts: bash, zsh, fish, or PowerShell.

Sources: crates/core/flags/lowargs.rs:228-241

Help output

Help has a condensed -h form and a verbose --help form, with the verbose form containing complete flag documentation.

Sources: crates/core/flags/lowargs.rs:125-132, crates/core/flags/defs.rs:2805-2813

Packaging manifest

A packaging manifest declares installation actions or target-platform runtime settings. The Homebrew formula installs the executable, man page, and bash/zsh completions; the Windows manifest declares supported operating systems and Windows settings.

Sources: pkg/brew/ripgrep-bin.rb:16-22, pkg/windows/Manifest.xml:6-27

How one flag model feeds multiple outputs

The generation workflow starts from shared flag information and fills format-specific templates for completions and documentation.

The available modes are:

These five choices are the documented values for the generation flag, and the low-level mode enum assigns each one its purpose.

Sources: crates/core/flags/defs.rs:2519-2527, crates/core/flags/lowargs.rs:228-241

How shell completions are generated

Bash builds an option list from every long flag, optional short flag, and optional negated flag, then appends <PATTERN> <PATH>.... It creates a case for every flag, using a choice-aware template when doc_choices() is non-empty.

The final Bash text is based on TEMPLATE_FULL, whose _rg() function checks the current command and completes options or file names.

Fish starts with prelude.fish, substitutes each flag’s short name, long name, and escaped short documentation into TEMPLATE, and adds completion arguments based on CompletionType. Filename, executable, filetype, encoding, documented-choice, and non-switch values receive different behaviors.

When a flag has name_negated(), Fish emits another completion entry using TEMPLATE_NEGATED.

PowerShell’s template registers a native argument completer for rg. The generator creates entries for long, short, and negated names, then replaces !FLAGS! with those entries.

Zsh uses a checked-in template and replaces placeholders for encodings and hyperlink-alias descriptions obtained from grep::printer::hyperlink_aliases().

Sources: crates/core/flags/complete/bash.rs:63-107, crates/core/flags/complete/bash.rs:45-50, crates/core/flags/complete/bash.rs:7-43, crates/core/flags/complete/fish.rs:13-75, crates/core/flags/complete/powershell.rs:7-35, crates/core/flags/complete/powershell.rs:43-85, crates/core/flags/complete/zsh.rs:21-32

How help and the man page are rendered

Short help groups flags by doc_category(), creates each short-help row with generate_short_flag, measures the columns, and inserts formatted values into TEMPLATE_SHORT. The indexing category receives a fallback message when the unstable-index feature is disabled.

generate_short_flag renders the short and long names, an optional documentation variable, and the short description from doc_short(). format_short_columns then pads the first column before writing the description.

Long help groups flags by category and delegates each complete entry to generate_long_flag before inserting the results into TEMPLATE_LONG.

generate_long_flag obtains doc_long(), expands \flag{...} and \flag-negate{...} references through render_custom_markup, removes roff escapes with remove_roff, and wraps the resulting paragraphs for terminal output.

The man-page generator groups the same FLAGS collection by category, inserts the generated category text into TEMPLATE, and calls generate_flag for each flag.

generate_flag renders names and doc_long() with roff escapes, resolves the same custom markup forms, and preserves roff structure such as .RS, .sp, and .RE.

Sources: crates/core/flags/doc/help.rs:24-54, crates/core/flags/doc/help.rs:60-89, crates/core/flags/doc/help.rs:96-117, crates/core/flags/doc/help.rs:120-146, crates/core/flags/doc/help.rs:149-226, crates/core/flags/doc/help.rs:234-277, crates/core/flags/doc/mod.rs:18-38, crates/core/flags/doc/man.rs:27-49, crates/core/flags/doc/man.rs:52-116

What the packaging manifests declare

The Homebrew formula sets version 15.0.0, selects macOS or Linux release archives, declares a conflict with ripgrep, and installs rg, doc/rg.1, complete/rg.bash, and complete/_rg into their respective Homebrew locations.

The Windows manifest declares compatibility with Windows 7, 8, 8.1, 10, and 11. It enables the UTF-8 active code page and sets longPathAware to true.

The build script calls set_windows_exe_options; its documented purpose is to embed the Windows manifest and set linker options, including support for paths longer than 260 characters when the relevant registry support is enabled.

Sources: pkg/brew/ripgrep-bin.rb:1-22, pkg/windows/Manifest.xml:6-27, build.rs:1-11

How it connects

The --generate interface belongs to the CLI flag system described in CLI Entry and Flag Parsing. Its documented choices are the man page and four completion modes.

The generated artifacts connect to release and installation work described in CI and Release Pipeline and Building and Installing. The Homebrew formula shows the packaged hand-off for the executable, man page, and two completion files.

The flag metadata and generation responsibilities are part of the CLI surface described in Repository and Crate Map.

Sources: crates/core/flags/defs.rs:2519-2527, crates/core/flags/lowargs.rs:228-241, pkg/brew/ripgrep-bin.rb:16-22

Key takeaways

• Shared flag metadata drives shell completions, help output, and the man page.
• Bash, fish, PowerShell, and zsh each combine generator logic with format-specific templates.
• Short help uses doc_short(); long help and the man page use doc_long().
• Homebrew installs rg, the man page, and bash/zsh completion files.
• Windows packaging declares OS compatibility, UTF-8 behavior, and long-path awareness.