feat(help): display manpage for nested commands #16432

weihanglo · 2025-12-25T16:09:52Z

Blocked on #16430

What does this PR try to resolve?

This allows cargo help to display manpages for nested subcommand,
such as cargo report future-incompat.

The argument of cargo help can be

A single <COMMAND>, such as cargo help build
or cargo help report-future-incompat (dash-joined)
Multiple <COMMAND>s, such as cargo help report future-incompat

This dash-joined form helps man-page user learn from existing convention.
The multiple commands form is straightforward for normal users.

How to test and review this PR?

cargo run -- help rpeort-future-incompat
cargo run -- help report-future-incompatibilities
cargo run -- help report future-incompat
cargo run -- help report future-incompatibilities

weihanglo · 2025-12-26T05:57:40Z

src/bin/cargo/commands/help.rs

This will need an team FCP

src/bin/cargo/commands/help.rs

tests/testsuite/cargo_help/nested_cmd_suggestion/mod.rs

src/bin/cargo/commands/help.rs

epage · 2025-12-26T19:33:51Z

src/bin/cargo/commands/help.rs

What about completions?

Can clap complete cargo help report fu<tab>? I guess it is not really supported and we might need to auto-complete in dash-joined form.

num_args(1..) are assumed to not be hierarchical so it can't. We don't have external subcommand completers yet, so switching to that wouldn't help.

Hmm, just realized we might not be offering completions for built-in help with the new completion engine. The old one would instantiate help in special way that automatically generated subcommands for every subcommand, recursively.

with the new completion engine

What is this?

The original clap completion system auto-generated completion files files similar to what we hand write in cargo. The new completion system is what Cargo is migrating to and what you wrote code for.

Ah thanks. I thought clap_completion going to get a new engine 😆.

epage · 2025-12-26T19:34:32Z

src/bin/cargo/commands/help.rs

+#[derive(Clone)]
+enum CommandKind {
+    Primary,
+    /// Contains the primary manpage name
+    Alias(String),
+}


Why do we care to track this?

For getting the original man page dash-joined name.

Made the intent more outstanding by renaming it to ManPageLookup

Still isn't making sense since all we do is immediately

let subcommand = match lookup { ManPageLookup::Direct => subcommand, ManPageLookup::RedirectTo(primary) => primary, };

epage · 2025-12-29T21:24:06Z

src/doc/man/cargo-help.md

+### Manifest Options
+
+{{#options}}
+{{> options-locked }}
+{{/options}}


Should we be bothering if these don't do anything

Or we can hide them also in --help text. Either works for me but man page and help text should be aligned.

epage · 2025-12-29T21:27:39Z

src/bin/cargo/commands/help.rs

-                &[OsStr::new(subcommand), OsStr::new("--help")],
-            )?;
-        }
+    if super::builtin_exec(subcommand).is_none() {


nit: I think in a previous iteration, you had used !option.is_some(). One advantage of that is it makes the fact that this is negative logic upfront.

Thoughts?

Also, is there a reason you swapped the order of the cases instead of doing option.is_some()?

Ah, for an early return later

epage · 2025-12-29T21:29:45Z

src/bin/cargo/commands/help.rs

-        Some(s) => s,
-        None => return Ok(false),
-    };
+    if super::builtin_exec(subcommand).is_none() {


nit: another case of option.is_none()

epage · 2025-12-29T21:31:37Z

src/bin/cargo/commands/help.rs

    if super::builtin_exec(&subcommand).is_none() {
+        // If not built-in, try giving `--help` to external command.
        crate::execute_external_subcommand(
            gctx,
            &subcommand,
            &[OsStr::new(&subcommand), OsStr::new("--help")],
        )?;
-    } else {
-        crate::execute_internal_subcommand(gctx, &[OsStr::new(&subcommand), OsStr::new("--help")])?;
    }


doesn't this need an early return?

epage · 2025-12-29T21:35:27Z

src/bin/cargo/commands/help.rs

+        if !is_valid_builtin_command_path(&args_command) {
+            let command_str = args_command.join(" ");
+            let err = anyhow::format_err!(
+                "no such command: `{command_str}`\n\n\
+                 help: view all installed commands with `cargo --list`",
+            );
+            return Err(err.into());
        }


cargo --list won't help for cargo report foo

They were missing before

So that when snapshotting, windows target won't be redacted by snapbox

This allows `cargo help` to display manpages for nested subcommand, such as `cargo report future-incompat`. The argument of `cargo help` can be * A single `<COMMAND>`, such as `cargo help build` or `cargo help report-future-incompat` (dash-joined) * Multiple `<COMMAND>`s, such as `cargo help report future-incompat` This dash-joined form helps man-page user learn from existing convention. The multiple commands form is straightforward for normal users.

rustbot added A-cli Area: Command-line interface, option parsing, etc. A-cli-help Area: built-in command-line help A-documenting-cargo-itself Area: Cargo's documentation A-future-incompat Area: future incompatible reporting Command-report labels Dec 25, 2025

weihanglo force-pushed the cargo-help branch 2 times, most recently from 525addb to 286129a Compare December 26, 2025 02:01

weihanglo mentioned this pull request Dec 26, 2025

Prototype Cargo build analysis rust-lang/rust-project-goals#398

Open

4 tasks

weihanglo force-pushed the cargo-help branch from 286129a to 8d3fb08 Compare December 26, 2025 02:42

weihanglo commented Dec 26, 2025

View reviewed changes

src/bin/cargo/commands/help.rs

Copy link

Member Author

weihanglo Dec 26, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will need an team FCP

epage reviewed Dec 26, 2025

View reviewed changes

src/bin/cargo/commands/help.rs Outdated Show resolved Hide resolved

epage reviewed Dec 26, 2025

View reviewed changes

tests/testsuite/cargo_help/nested_cmd_suggestion/mod.rs Show resolved Hide resolved

epage reviewed Dec 26, 2025

View reviewed changes

src/bin/cargo/commands/help.rs Outdated Show resolved Hide resolved

epage reviewed Dec 26, 2025

View reviewed changes

src/bin/cargo/commands/help.rs Show resolved Hide resolved

epage reviewed Dec 26, 2025

View reviewed changes

src/bin/cargo/commands/help.rs Outdated Show resolved Hide resolved

epage reviewed Dec 26, 2025

View reviewed changes

src/bin/cargo/commands/help.rs Show resolved Hide resolved

epage reviewed Dec 26, 2025

View reviewed changes

src/bin/cargo/commands/help.rs Outdated Show resolved Hide resolved

epage reviewed Dec 26, 2025

View reviewed changes

src/bin/cargo/commands/help.rs Outdated Show resolved Hide resolved

epage reviewed Dec 26, 2025

View reviewed changes

weihanglo force-pushed the cargo-help branch 3 times, most recently from 6eb4401 to 459fd78 Compare December 29, 2025 20:10

This comment has been minimized.

Sign in to view

rustbot added the S-waiting-on-author Status: The marked PR is awaiting some action (such as code changes) from the PR author. label Dec 29, 2025

weihanglo force-pushed the cargo-help branch from 459fd78 to ef90c8a Compare December 29, 2025 21:16

epage reviewed Dec 29, 2025

View reviewed changes

weihanglo force-pushed the cargo-help branch from ef90c8a to ab4cf3d Compare December 29, 2025 21:49

weihanglo mentioned this pull request Dec 29, 2025

docs(report): enhance man pages for cargo report * #16430

Open

This comment has been minimized.

Sign in to view

weihanglo added 15 commits January 5, 2026 20:15

docs(report): move cargo report to its own subsection

0b21787

docs(report): show all available options

ddedfcc

They were missing before

test(report): snapshot future-incompat help text

e5aa3db

docs(report): manpage for cargo report future-incompat

9c546e2

docs(cargo-rm): change example to wasm32-unknown-unknown

80b9d3e

So that when snapshotting, windows target won't be redacted by snapbox

docs(help): show missing options

a889c91

test(help): snapshot cargo help tests

85ac7ee

refactor(help): early return rather than nested if-else

588980b

refactor(help): inline check alias/builtin functions

cf7ef9f

refactor(help): move alias expansion out from try_help

86f89b9

refactor(help): avoid checking built-in commands twice

26a5d39

docs(help): document dash-joined format for nested commands

7eef672

fix(report): show manpage hint in help test

ba302cc

feat(completion): help completion also for nested commands

ec6c69a

weihanglo force-pushed the cargo-help branch from ab4cf3d to ec6c69a Compare January 6, 2026 01:16

feat(help): display manpage for nested commands #16432

Are you sure you want to change the base?

feat(help): display manpage for nested commands #16432

Uh oh!

Conversation

weihanglo commented Dec 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR try to resolve?

How to test and review this PR?

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

weihanglo Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

weihanglo commented Dec 25, 2025 •

edited

Loading

weihanglo Dec 29, 2025 •

edited

Loading