docs(report): enhance man pages for `cargo report *` by weihanglo · Pull Request #16430 · rust-lang/cargo

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

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

@@ -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)

Pkgsrc changes: * Update version & checksums, and adapt to new libc crate included. Upstream changes relative to 1.94.1: Version 1.95 (2026-04-16) ========================== Language -------- - [Stabilize `if let` guards on match arms] (rust-lang/rust#141295) - [`irrefutable_let_patterns` lint no longer lints on let chains] (rust-lang/rust#146832) - [Support importing path-segment keywords with renaming] (rust-lang/rust#146972) - [Stabilize inline assembly for PowerPC and PowerPC64] (rust-lang/rust#147996) - [const-eval: be more consistent in the behavior of padding during typed copies] (rust-lang/rust#148967) - [Const blocks are no longer evaluated to determine if expressions involving fallible operations can implicitly be constant-promoted.] (rust-lang/rust#150557). Expressions whose ability to implicitly be promoted would depend on the result of a const block are no longer implicitly promoted. - [Make operational semantics of pattern matching independent of crate and module] (rust-lang/rust#150681) Compiler -------- - [Stabilize `--remap-path-scope` for controlling the scoping of how paths get remapped in the resulting binary] (rust-lang/rust#147611) Platform Support ---------------- - [Promote `powerpc64-unknown-linux-musl` to Tier 2 with host tools] (rust-lang/rust#149962) - [Promote `aarch64-apple-tvos` to Tier 2] (rust-lang/rust#152021) - [Promote `aarch64-apple-tvos-sim` to Tier 2] (rust-lang/rust#152021) - [Promote `aarch64-apple-watchos` to Tier 2] (rust-lang/rust#152021) - [Promote `aarch64-apple-watchos-sim` to Tier 2] (rust-lang/rust#152021) - [Promote `aarch64-apple-visionos` to Tier 2] (rust-lang/rust#152021) - [Promote `aarch64-apple-visionos-sim` to Tier 2] (rust-lang/rust#152021) Refer to Rust's [platform support page][platform-support-doc] for more information on Rust's tiered platform support. https://doc.rust-lang.org/rustc/platform-support.html Libraries --------- - [`thread::scope`: document how join interacts with TLS destructors] (rust-lang/rust#149482) - [Speed up `str::contains` on aarch64 targets with `neon` target feature enabled by default] (rust-lang/rust#152176) Stabilized APIs --------------- - [`MaybeUninit<[T; N]>: From<[MaybeUninit<T>; N]>`] (https://doc.rust-lang.org/stable/std/mem/union.MaybeUninit.html#impl-From%3CMaybeUninit%3C%5BT;+N%5D%3E%3E-for-%5BMaybeUninit%3CT%3E;+N%5D) - [`MaybeUninit<[T; N]>: AsRef<[MaybeUninit<T>; N]>`] (https://doc.rust-lang.org/stable/std/mem/union.MaybeUninit.html#impl-AsRef%3C%5BMaybeUninit%3CT%3E;+N%5D%3E-for-MaybeUninit%3C%5BT;+N%5D%3E) - [`MaybeUninit<[T; N]>: AsRef<[MaybeUninit<T>]>`] (https://doc.rust-lang.org/stable/std/mem/union.MaybeUninit.html#impl-AsRef%3C%5BMaybeUninit%3CT%3E%5D%3E-for-MaybeUninit%3C%5BT;+N%5D%3E) - [`MaybeUninit<[T; N]>: AsMut<[MaybeUninit<T>; N]>`] (https://doc.rust-lang.org/beta/std/mem/union.MaybeUninit.html#impl-AsMut%3C%5BMaybeUninit%3CT%3E;+N%5D%3E-for-MaybeUninit%3C%5BT;+N%5D%3E) - [`MaybeUninit<[T; N]>: AsMut<[MaybeUninit<T>]>`] (https://doc.rust-lang.org/stable/std/mem/union.MaybeUninit.html#impl-AsMut%3C%5BMaybeUninit%3CT%3E%5D%3E-for-MaybeUninit%3C%5BT;+N%5D%3E) - [`[MaybeUninit<T>; N]: From<MaybeUninit<[T; N]>>`] (https://doc.rust-lang.org/stable/std/mem/union.MaybeUninit.html#impl-From%3C%5BMaybeUninit%3CT%3E;+N%5D%3E-for-MaybeUninit%3C%5BT;+N%5D%3E) - [`Cell<[T; N]>: AsRef<[Cell<T>; N]>`] (https://doc.rust-lang.org/stable/std/cell/struct.Cell.html#impl-AsRef%3C%5BCell%3CT%3E;+N%5D%3E-for-Cell%3C%5BT;+N%5D%3E) - [`Cell<[T; N]>: AsRef<[Cell<T>]>`] (https://doc.rust-lang.org/stable/std/cell/struct.Cell.html#impl-AsRef%3C%5BCell%3CT%3E%5D%3E-for-Cell%3C%5BT;+N%5D%3E) - [`Cell<[T]>: AsRef<[Cell<T>]>`] (https://doc.rust-lang.org/stable/std/cell/struct.Cell.html#impl-AsRef%3C%5BCell%3CT%3E%5D%3E-for-Cell%3C%5BT%5D%3E) - [`bool: TryFrom<{integer}>`] (https://doc.rust-lang.org/stable/std/primitive.bool.html#impl-TryFrom%3Cu128%3E-for-bool) - [`AtomicPtr::update`] (https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicPtr.html#method.update) - [`AtomicPtr::try_update`] (https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicPtr.html#method.try_update) - [`AtomicBool::update`] (https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicBool.html#method.update) - [`AtomicBool::try_update`] (https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicBool.html#method.try_update) - [`AtomicIn::update`] (https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicIsize.html#method.update) - [`AtomicIn::try_update`] (https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicIsize.html#method.try_update) - [`AtomicUn::update`] (https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicUsize.html#method.update) - [`AtomicUn::try_update`] (https://doc.rust-lang.org/stable/std/sync/atomic/struct.AtomicUsize.html#method.try_update) - [`cfg_select!`] (https://doc.rust-lang.org/stable/std/macro.cfg_select.html) - [`mod core::range`] (https://doc.rust-lang.org/stable/core/range/index.html) - [`core::range::RangeInclusive`] (https://doc.rust-lang.org/stable/core/range/struct.RangeInclusive.html) - [`core::range::RangeInclusiveIter`] (https://doc.rust-lang.org/stable/core/range/struct.RangeInclusiveIter.html) - [`core::hint::cold_path`] (https://doc.rust-lang.org/stable/core/hint/fn.cold_path.html) - [`<*const T>::as_ref_unchecked`] (https://doc.rust-lang.org/stable/std/primitive.pointer.html#method.as_ref_unchecked) - [`<*mut T>::as_ref_unchecked`] (https://doc.rust-lang.org/stable/std/primitive.pointer.html#method.as_ref_unchecked-1) - [`<*mut T>::as_mut_unchecked`] (https://doc.rust-lang.org/stable/std/primitive.pointer.html#method.as_mut_unchecked) These previously stable APIs are now stable in const contexts: - [`fmt::from_fn`] (https://doc.rust-lang.org/stable/std/fmt/fn.from_fn.html) - [`ControlFlow::is_break`] (https://doc.rust-lang.org/stable/core/ops/enum.ControlFlow.html#method.is_break) - [`ControlFlow::is_continue`] (https://doc.rust-lang.org/stable/core/ops/enum.ControlFlow.html#method.is_continue) Cargo ----- - [docs(report): enhance man pages for `cargo report *`] (rust-lang/cargo#16430) Rustdoc ----- - [In search results, rank unstable items lower] (rust-lang/rust#149460) - [Add new "hide deprecated items" setting in rustdoc] (rust-lang/rust#151091) Compatibility Notes ------------------- - [Array coercions may now result in less inference constraints than before] (rust-lang/rust#140283) - Importing `$crate` without renaming, i.e. `use $crate::{self};`, is now no longer permitted due to stricter error checking for `self` imports. - [const-eval: be more consistent in the behavior of padding during typed copies.] (rust-lang/rust#148967) In very rare cases, this may cause compilation errors due to bytes from parts of a pointer ending up in the padding bytes of a `const` or `static`. - [A future-incompatibility warning lint `ambiguous_glob_imported_traits` is now reported when using an ambiguously glob imported trait] (rust-lang/rust#149058) - [Check lifetime bounds of types mentioning only type parameters] (rust-lang/rust#149389) - [Report more visibility-related ambiguous import errors] (rust-lang/rust#149596) - [Deprecate `Eq::assert_receiver_is_total_eq` and emit future compatibility warnings on manual impls] (rust-lang/rust#149978) - [powerpc64: Use the ELF ABI version set in target spec instead of guessing] (rust-lang/rust#150468) (fixes the ELF ABI used by the OpenBSD target) - Matching on a `#[non_exhaustive]` enum [now reads the discriminant, even if the enum has only one variant] (rust-lang/rust#150681). This can cause closures to capture values that they previously wouldn't. - `mut ref` and `mut ref mut` patterns, part of the unstable [Match Ergonomics 2024 RFC] (rust-lang/rust#123076), were accidentally allowed on stable within struct pattern field shorthand. These patterns are now correctly feature-gated as unstable in this position. - [Add future-compatibility warning for derive helper attributes which conflict with built-in attributes] (rust-lang/rust#151152) - [JSON target specs] (https://doc.rust-lang.org/rustc/targets/custom.html) have been destabilized and now require `-Z unstable-options` to use. Previously, they could not be used without the standard library, which has no stable build mechanism. In preparation for the `build-std` project adding that support, JSON target specs are being proactively gated to ensure they remain unstable even if `build-std` is stabilized. Cargo now includes the `-Z json-target-spec` CLI flag to automatically pass `-Z unstable-options` to the compiler when needed. See [#150151] (rust-lang/rust#150151), [#151534] (rust-lang/rust#150151), and [rust-lang/cargo#16557] (rust-lang/cargo#16557). - [The arguments of `#[feature]` attributes on invalid targets are now checked] (rust-lang/rust#153764) Internal Changes ---------------- These changes do not affect any public interfaces of Rust, but they represent significant improvements to the performance or internals of rustc and related tools. - [Update to LLVM 22](rust-lang/rust#150722)

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

Comment thread .ignore

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

Merged

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

Closed

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 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

Merged

rustbot added this to the 1.95.0 milestone Jan 31, 2026

BoxyUwU mentioned this pull request Apr 2, 2026

Draft release notes for 1.95 rust-lang/rust#154711

Closed

weihanglo deleted the manpage-for-nested branch April 19, 2026 00:29

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.

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

weihanglo commented Dec 23, 2025 •

edited

Loading

weihanglo Dec 29, 2025 •

edited

Loading