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

weihanglo · 2025-12-23T23:16:41Z

FCP

What does this PR try to resolve?

Make space for future report kinds iun cargo report documentations.

A new sub-section of "report commands" in the Cargo book.
Fixed that cargo report man page didn't match its --help text equivalent
cargo report future-incompat didn't have its own man page.

Note that cargo help hasn't yet supported for future-incompat.
It will be a separate PR.

How to test and review this PR?

mdbook serve src/doc
target/debug/cargo help report

rustbot · 2025-12-23T23:16:46Z

r? @epage

rustbot has assigned @epage.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

.ignore

epage · 2025-12-26T19:11:46Z

‼️ Make report future-incompat the primary name instead of an alias.

I'm a bit concerned about this as incompat isn't too obvious of a meaning. To not block the other changes and to make this more visible, should this be split out into its own PR?

epage · 2025-12-26T19:25:10Z

src/doc/man/cargo-report-future-incompat.md

@@ -0,0 +1,64 @@
+# cargo-report-future-incompat(1)


Do we need an FCP for this as well?

This is a doc change that we can easily revert by redirecting the new page to https://doc.rust-lang.org/nightly/cargo/reference/future-incompat-report.html, so I don't think it need an FCP.

Don't remember what my concern was here

Now I remember: do we have compatibility guarantees on the man pages that we provide?

Ah, for that, yes. The toolchain distribution tarball has them in ./share/man/man1. Also rustup man <dot-joined-cmd> displays them.

So in terms of CLI compatibility we might want an FCP.

The toolchain distribution tarball has them in ./share/man/man1

Some OS distros include them in man database when install a toolchain from the system package manager.

Before starting FCP, let's align with the concerns.

The major change of this is we expose man pages and documentation of sub-subcommand (i.e., cargo report future-incompatibilities).

If we consider man pages for human only, it is less an concern. If we then don't want to expose sub-subcommand later, we can just redirect them to their parent command.

If we consider man pages also for manchine/programmable use cases, then we need to be ensure what the compatibility we guarantee here before making this change.

Do we always want sub-subcommands to have its own man pages, or case-by-case? For example, cargo worktree doesn't have man pages for worktree add|remove separately This is similar to our cargo owner case. OTOH, docker container ls|rm|inspect does, as all the sub-subcommands are different than others.

Do we always want sub-subcommands to have its own man pages, or case-by-case? For example, cargo worktree doesn't have man pages for worktree add|remove separately This is similar to our cargo owner case. OTOH, docker container ls|rm|inspect does, as all the sub-subcommands are different than others.

I think this should be handled on a case by case basis. Some subcommands are modes of the parent subcommand, like git stash. Clap has support for this as flatten_help. Other subcommands are more independent of each other and should have independent help.

weihanglo · 2025-12-27T18:35:23Z

‼️ Make report future-incompat the primary name instead of an alias.

I'm a bit concerned about this as incompat isn't too obvious of a meaning. To not block the other changes and to make this more visible, should this be split out into its own PR?

Removed. incompat is already a name in the stable flag --future-incompat-report in cargo build, as well as in the config table [future-incompat-report]. Personally I am not too worried about it.

### What does this PR try to resolve? docs(unstable): expand docs for `-Zbuild-analysis` ### How to test and review this PR? [rendered](https://github.com/weihanglo/cargo/blob/ed66196b0b0e71aff8208565533411ffde49ff8a/src/doc/src/reference/unstable.md) Each command's doc will be in their own man page after this is merged <#16430>.

rust-rfcbot · 2026-01-20T15:42:43Z

🔔 This is now entering its final comment period, as per the review above. 🔔

They were missing before

rustbot · 2026-01-21T22:37:49Z

This PR was rebased onto a different master commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

rust-rfcbot · 2026-01-30T15:42:44Z

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

Update cargo submodule 18 commits in efcd9f58636c1990393d495159045d9c35e43b8f..fe2f314aef06e688a9517da1ac0577bb1854d01f 2026-01-23 13:50:59 +0000 to 2026-01-30 21:52:01 +0000 - feat(lints): Add unused workspace dependency lint (rust-lang/cargo#16571) - docs: Remove redundant homepage link (rust-lang/cargo#16572) - refactor: Remove unused workspace dependencies (rust-lang/cargo#16573) - Re-downgrade curl-sys (rust-lang/cargo#16570) - docs(report): enhance man pages for `cargo report *` (rust-lang/cargo#16430) - fix(lints): Refine redundant metadata lints (rust-lang/cargo#16564) - Prevent `cargo init` in home directory (rust-lang/cargo#16566) - feat(lints): Add redundant_homepage lint (rust-lang/cargo#16561) - feat(lints): Add `non_*_case_features` (rust-lang/cargo#16560) - Update build_std::basic test to ensure index doesn't update (rust-lang/cargo#16559) - feat(lints): Add mutually exclusive `non_{kebab,snake}_case_packages` (rust-lang/cargo#16554) - fix(lints): Pluralize non_kebab_case_bins (rust-lang/cargo#16553) - Add -Z json-target-spec (rust-lang/cargo#16557) - feat(lint): Add redundant_readme lint (rust-lang/cargo#16552) - chore(deps): update msrv (rust-lang/cargo#16387) - tests: add regression test for --artifact-dir on stable (rust-lang/cargo#16541) - Don't check the specific build-std output (rust-lang/cargo#16551) - Fix build-std lto test to run on other platforms (rust-lang/cargo#16550)

rustbot assigned epage Dec 23, 2025

rustbot added A-cli-help Area: built-in command-line help A-documenting-cargo-itself Area: Cargo's documentation S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Dec 23, 2025

weihanglo force-pushed the manpage-for-nested branch 2 times, most recently from e08f161 to eb13e52 Compare December 24, 2025 03:31

rustbot added A-cli Area: Command-line interface, option parsing, etc. A-future-incompat Area: future incompatible reporting Command-report labels Dec 24, 2025

epage reviewed Dec 24, 2025

View reviewed changes

.ignore Show resolved Hide resolved

weihanglo force-pushed the manpage-for-nested branch 2 times, most recently from d34d267 to 870a35a Compare December 25, 2025 16:08

weihanglo mentioned this pull request Dec 25, 2025

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

Draft

weihanglo force-pushed the manpage-for-nested branch from 870a35a to 9c693b6 Compare December 25, 2025 17:55

weihanglo mentioned this pull request Dec 26, 2025

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

Open

4 tasks

epage reviewed Dec 26, 2025

View reviewed changes

weihanglo force-pushed the manpage-for-nested branch from 9c693b6 to 8a7ab6e Compare December 27, 2025 18:30

This comment has been minimized.

Sign in to view

weihanglo force-pushed the manpage-for-nested branch from 8a7ab6e to 01940e6 Compare December 27, 2025 18:32

weihanglo force-pushed the manpage-for-nested branch from 01940e6 to f895fd7 Compare December 27, 2025 19:10

This comment has been minimized.

Sign in to view

weihanglo force-pushed the manpage-for-nested branch from f895fd7 to 5f18a45 Compare December 29, 2025 21:16

This comment has been minimized.

Sign in to view

epage approved these changes Dec 29, 2025

View reviewed changes

epage enabled auto-merge December 29, 2025 21:19

epage disabled auto-merge December 29, 2025 21:19

weihanglo force-pushed the manpage-for-nested branch from 511422f to 9c546e2 Compare January 6, 2026 01:16

This comment has been minimized.

Sign in to view

ehuss added this to Cargo status tracker Jan 6, 2026

ehuss moved this to FCP merge in Cargo status tracker Jan 6, 2026

weihanglo mentioned this pull request Jan 6, 2026

docs(unstable): expand docs for -Zbuild-analysis #16476

Merged

weihanglo mentioned this pull request Jan 8, 2026

Man pages for new cargo report * commands #16488

Open

rust-rfcbot added the final-comment-period FCP — a period for last comments before action is taken label Jan 20, 2026

rust-rfcbot removed the proposed-final-comment-period An FCP proposal has started, but not yet signed off. label Jan 20, 2026

weihanglo force-pushed the manpage-for-nested branch from 9c546e2 to 204ef92 Compare January 20, 2026 22:31

This comment has been minimized.

Sign in to view

weihanglo added 4 commits January 21, 2026 10:50

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

a4e3cfe

docs(report): show all available options

52e9f27

They were missing before

test(report): snapshot future-incompat help text

67b6687

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

a478878

weihanglo force-pushed the manpage-for-nested branch from 204ef92 to a478878 Compare January 21, 2026 22:37

rust-rfcbot added finished-final-comment-period FCP complete and removed final-comment-period FCP — a period for last comments before action is taken labels Jan 30, 2026

rust-rfcbot added the to-announce label Jan 30, 2026

epage approved these changes Jan 30, 2026

View reviewed changes

epage added this pull request to the merge queue Jan 30, 2026

Merged via the queue into rust-lang:master with commit 9dab518 Jan 30, 2026
29 checks passed

rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Jan 30, 2026

weihanglo mentioned this pull request Jan 31, 2026

Update cargo submodule rust-lang/rust#151764

Open

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

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

Conversation

weihanglo commented Dec 23, 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!

rustbot commented Dec 23, 2025

Uh oh!

Uh oh!

epage commented Dec 26, 2025

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.

weihanglo commented Dec 27, 2025

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

rust-rfcbot commented Jan 20, 2026

Uh oh!

This comment has been minimized.

rustbot commented Jan 21, 2026

Uh oh!

rust-rfcbot commented Jan 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

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

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

weihanglo commented Dec 23, 2025 •

edited

Loading

weihanglo Dec 29, 2025 •

edited

Loading