Auto merge of #11905 - epage:help_heading, r=weihanglo

fix(cli): Make `--help` easier to browse

This mirrors some of the categories from `cargo help` (the man pages) using [`clap::Arg::help_heading`](https://docs.rs/clap/latest/clap/struct.Arg.html#method.help_heading).
There are fewer categories to avoid extra vertical space.  Instead, they
are left int the `Options` category but put first.

The goal is to try to make it easier to scan `--help` output as the list of flags can get quite long and its easy to miss what features are there.

src/bin/cargo/cli.rs

@@ -523,7 +523,9 @@ pub fn cli() -> Command {
     Command::new("cargo")
         // Subcommands all count their args' display order independently (from 0),
         // which makes their args interspersed with global args. This puts global args last.
-        .next_display_order(1000)
+        //
+        // We also want these to come before auto-generated `--help`
+        .next_display_order(800)
         .allow_external_subcommands(true)
         // Doesn't mix well with our list of common cargo commands.  See clap-rs/clap#3108 for
         // opening clap up to allow us to style our help template
@@ -586,9 +588,21 @@ See 'cargo help <command>' for more information on a specific command.\n",
                 .value_hint(clap::ValueHint::DirPath)
                 .value_parser(clap::builder::ValueParser::path_buf()),
         )
-        .arg(flag("frozen", "Require Cargo.lock and cache are up to date").global(true))
-        .arg(flag("locked", "Require Cargo.lock is up to date").global(true))
-        .arg(flag("offline", "Run without accessing the network").global(true))
+        .arg(
+            flag("frozen", "Require Cargo.lock and cache are up to date")
+                .help_heading(heading::MANIFEST_OPTIONS)
+                .global(true),
+        )
+        .arg(
+            flag("locked", "Require Cargo.lock is up to date")
+                .help_heading(heading::MANIFEST_OPTIONS)
+                .global(true),
+        )
+        .arg(
+            flag("offline", "Run without accessing the network")
+                .help_heading(heading::MANIFEST_OPTIONS)
+                .global(true),
+        )
         .arg(multi_opt("config", "KEY=VALUE", "Override a configuration value").global(true))
         .arg(
             Arg::new("unstable-features")

src/bin/cargo/commands/add.rs

@@ -79,8 +79,8 @@ Example uses:
         ])
         .arg_manifest_path()
         .arg_package("Package to modify")
-        .arg_quiet()
         .arg_dry_run("Don't actually write the manifest")
+        .arg_quiet()
         .next_help_heading("Source")
         .args([
             clap::Arg::new("path")

src/bin/cargo/commands/bench.rs

@@ -4,7 +4,7 @@ use cargo::ops::{self, TestOptions};
 pub fn cli() -> Command {
     subcommand("bench")
         .about("Execute all benchmarks of a local package")
-        .arg_quiet()
+        .next_display_order(0)
         .arg(
             Arg::new("BENCHNAME")
                 .action(ArgAction::Set)
@@ -16,6 +16,19 @@ pub fn cli() -> Command {
                 .num_args(0..)
                 .last(true),
         )
+        .arg(flag("no-run", "Compile, but don't run benchmarks"))
+        .arg(flag(
+            "no-fail-fast",
+            "Run all benchmarks regardless of failure",
+        ))
+        .arg_ignore_rust_version()
+        .arg_message_format()
+        .arg_quiet()
+        .arg_package_spec(
+            "Package to run benchmarks for",
+            "Benchmark all packages in the workspace",
+            "Exclude packages from the benchmark",
+        )
         .arg_targets_all(
             "Benchmark only this package's library",
             "Benchmark only the specified binary",
@@ -28,26 +41,14 @@ pub fn cli() -> Command {
             "Benchmark all benches",
             "Benchmark all targets",
         )
-        .arg(flag("no-run", "Compile, but don't run benchmarks"))
-        .arg_package_spec(
-            "Package to run benchmarks for",
-            "Benchmark all packages in the workspace",
-            "Exclude packages from the benchmark",
-        )
+        .arg_features()
         .arg_jobs()
         .arg_profile("Build artifacts with the specified profile")
-        .arg_features()
         .arg_target_triple("Build for the target triple")
         .arg_target_dir()
-        .arg_manifest_path()
-        .arg_ignore_rust_version()
-        .arg_message_format()
-        .arg(flag(
-            "no-fail-fast",
-            "Run all benchmarks regardless of failure",
-        ))
         .arg_unit_graph()
         .arg_timings()
+        .arg_manifest_path()
         .after_help("Run `cargo help bench` for more detailed information.\n")
 }
 

src/bin/cargo/commands/build.rs

@@ -7,13 +7,15 @@ pub fn cli() -> Command {
         // subcommand aliases are handled in aliased_command()
         // .alias("b")
         .about("Compile a local package and all of its dependencies")
+        .arg_ignore_rust_version()
+        .arg_future_incompat_report()
+        .arg_message_format()
         .arg_quiet()
         .arg_package_spec(
             "Package to build (see `cargo help pkgid`)",
             "Build all packages in the workspace",
             "Exclude packages from the build",
         )
-        .arg_jobs()
         .arg_targets_all(
             "Build only this package's library",
             "Build only the specified binary",
@@ -26,25 +28,24 @@ pub fn cli() -> Command {
             "Build all benches",
             "Build all targets",
         )
+        .arg_features()
         .arg_release("Build artifacts in release mode, with optimizations")
         .arg_profile("Build artifacts with the specified profile")
-        .arg_features()
+        .arg_jobs()
         .arg_target_triple("Build for the target triple")
         .arg_target_dir()
         .arg(
             opt(
                 "out-dir",
                 "Copy final artifacts to this directory (unstable)",
             )
-            .value_name("PATH"),
+            .value_name("PATH")
+            .help_heading(heading::COMPILATION_OPTIONS),
         )
-        .arg_manifest_path()
-        .arg_ignore_rust_version()
-        .arg_message_format()
         .arg_build_plan()
         .arg_unit_graph()
-        .arg_future_incompat_report()
         .arg_timings()
+        .arg_manifest_path()
         .after_help("Run `cargo help build` for more detailed information.\n")
 }
 

src/bin/cargo/commands/check.rs

@@ -7,13 +7,15 @@ pub fn cli() -> Command {
         // subcommand aliases are handled in aliased_command()
         // .alias("c")
         .about("Check a local package and all of its dependencies for errors")
+        .arg_ignore_rust_version()
+        .arg_future_incompat_report()
+        .arg_message_format()
         .arg_quiet()
         .arg_package_spec(
             "Package(s) to check",
             "Check all packages in the workspace",
             "Exclude packages from the check",
         )
-        .arg_jobs()
         .arg_targets_all(
             "Check only this package's library",
             "Check only the specified binary",
@@ -26,17 +28,15 @@ pub fn cli() -> Command {
             "Check all benches",
             "Check all targets",
         )
+        .arg_features()
+        .arg_jobs()
         .arg_release("Check artifacts in release mode, with optimizations")
         .arg_profile("Check artifacts with the specified profile")
-        .arg_features()
         .arg_target_triple("Check for the target triple")
         .arg_target_dir()
-        .arg_manifest_path()
-        .arg_ignore_rust_version()
-        .arg_message_format()
         .arg_unit_graph()
-        .arg_future_incompat_report()
         .arg_timings()
+        .arg_manifest_path()
         .after_help("Run `cargo help check` for more detailed information.\n")
 }
 

src/bin/cargo/commands/clean.rs

@@ -6,14 +6,14 @@ use cargo::util::print_available_packages;
 pub fn cli() -> Command {
     subcommand("clean")
         .about("Remove artifacts that cargo has generated in the past")
+        .arg_doc("Whether or not to clean just the documentation directory")
         .arg_quiet()
         .arg_package_spec_simple("Package to clean artifacts for")
-        .arg_manifest_path()
-        .arg_target_triple("Target triple to clean output for")
-        .arg_target_dir()
         .arg_release("Whether or not to clean release artifacts")
         .arg_profile("Clean artifacts of the specified profile")
-        .arg_doc("Whether or not to clean just the documentation directory")
+        .arg_target_triple("Target triple to clean output for")
+        .arg_target_dir()
+        .arg_manifest_path()
         .after_help("Run `cargo help clean` for more detailed information.\n")
 }
 

src/bin/cargo/commands/doc.rs

@@ -7,39 +7,39 @@ pub fn cli() -> Command {
         // subcommand aliases are handled in aliased_command()
         // .alias("d")
         .about("Build a package's documentation")
-        .arg_quiet()
         .arg(flag(
             "open",
             "Opens the docs in a browser after the operation",
         ))
-        .arg_package_spec(
-            "Package to document",
-            "Document all packages in the workspace",
-            "Exclude packages from the build",
-        )
         .arg(flag(
             "no-deps",
             "Don't build documentation for dependencies",
         ))
         .arg(flag("document-private-items", "Document private items"))
-        .arg_jobs()
+        .arg_ignore_rust_version()
+        .arg_message_format()
+        .arg_quiet()
+        .arg_package_spec(
+            "Package to document",
+            "Document all packages in the workspace",
+            "Exclude packages from the build",
+        )
+        .arg_features()
         .arg_targets_lib_bin_example(
             "Document only this package's library",
             "Document only the specified binary",
             "Document all binaries",
             "Document only the specified example",
             "Document all examples",
         )
+        .arg_jobs()
         .arg_release("Build artifacts in release mode, with optimizations")
         .arg_profile("Build artifacts with the specified profile")
-        .arg_features()
         .arg_target_triple("Build for the target triple")
         .arg_target_dir()
-        .arg_manifest_path()
-        .arg_message_format()
-        .arg_ignore_rust_version()
         .arg_unit_graph()
         .arg_timings()
+        .arg_manifest_path()
         .after_help("Run `cargo help doc` for more detailed information.\n")
 }
 

src/bin/cargo/commands/fetch.rs

@@ -7,8 +7,8 @@ pub fn cli() -> Command {
     subcommand("fetch")
         .about("Fetch dependencies of a package from the network")
         .arg_quiet()
-        .arg_manifest_path()
         .arg_target_triple("Fetch dependencies for the target triple")
+        .arg_manifest_path()
         .after_help("Run `cargo help fetch` for more detailed information.\n")
 }
 

src/bin/cargo/commands/fix.rs

@@ -5,13 +5,35 @@ use cargo::ops;
 pub fn cli() -> Command {
     subcommand("fix")
         .about("Automatically fix lint warnings reported by rustc")
+        .arg(flag("edition", "Fix in preparation for the next edition"))
+        .arg(flag(
+            "edition-idioms",
+            "Fix warnings to migrate to the idioms of an edition",
+        ))
+        .arg(flag(
+            "broken-code",
+            "Fix code even if it already has compiler errors",
+        ))
+        .arg(flag(
+            "allow-no-vcs",
+            "Fix code even if a VCS was not detected",
+        ))
+        .arg(flag(
+            "allow-dirty",
+            "Fix code even if the working directory is dirty",
+        ))
+        .arg(flag(
+            "allow-staged",
+            "Fix code even if the working directory has staged changes",
+        ))
+        .arg_ignore_rust_version()
+        .arg_message_format()
         .arg_quiet()
         .arg_package_spec(
             "Package(s) to fix",
             "Fix all packages in the workspace",
             "Exclude packages from the fixes",
         )
-        .arg_jobs()
         .arg_targets_all(
             "Fix only this package's library",
             "Fix only the specified binary",
@@ -24,36 +46,14 @@ pub fn cli() -> Command {
             "Fix all benches",
             "Fix all targets (default)",
         )
+        .arg_features()
+        .arg_jobs()
         .arg_release("Fix artifacts in release mode, with optimizations")
         .arg_profile("Build artifacts with the specified profile")
-        .arg_features()
         .arg_target_triple("Fix for the target triple")
         .arg_target_dir()
-        .arg_manifest_path()
-        .arg_message_format()
-        .arg(flag(
-            "broken-code",
-            "Fix code even if it already has compiler errors",
-        ))
-        .arg(flag("edition", "Fix in preparation for the next edition"))
-        .arg(flag(
-            "edition-idioms",
-            "Fix warnings to migrate to the idioms of an edition",
-        ))
-        .arg(flag(
-            "allow-no-vcs",
-            "Fix code even if a VCS was not detected",
-        ))
-        .arg(flag(
-            "allow-dirty",
-            "Fix code even if the working directory is dirty",
-        ))
-        .arg(flag(
-            "allow-staged",
-            "Fix code even if the working directory has staged changes",
-        ))
-        .arg_ignore_rust_version()
         .arg_timings()
+        .arg_manifest_path()
         .after_help("Run `cargo help fix` for more detailed information.\n")
 }
 

src/bin/cargo/commands/init.rs

@@ -5,10 +5,10 @@ use cargo::ops;
 pub fn cli() -> Command {
     subcommand("init")
         .about("Create a new cargo package in an existing directory")
-        .arg_quiet()
         .arg(Arg::new("path").action(ArgAction::Set).default_value("."))
-        .arg(opt("registry", "Registry to use").value_name("REGISTRY"))
         .arg_new_opts()
+        .arg(opt("registry", "Registry to use").value_name("REGISTRY"))
+        .arg_quiet()
         .after_help("Run `cargo help init` for more detailed information.\n")
 }