Help sections in clap --help

src/main.rs

@@ -105,36 +105,41 @@ pub enum BaselineStrategy {
 )]
 struct Args {
     /// show cargo output for all invocations (very verbose).
-    #[arg(long)]
+    #[arg(long, help_heading = "Output")]
     all_logs: bool,
 
     /// baseline strategy: check that tests pass in an unmutated tree before testing mutants.
-    #[arg(long, value_enum, default_value_t = BaselineStrategy::Run)]
+    #[arg(long, value_enum, default_value_t = BaselineStrategy::Run, help_heading = "Execution")]
     baseline: BaselineStrategy,
 
     /// print mutants that were caught by tests.
-    #[arg(long, short = 'v')]
+    #[arg(long, short = 'v', help_heading = "Output")]
     caught: bool,
 
     /// cargo check generated mutants, but don't run tests.
-    #[arg(long)]
+    #[arg(long, help_heading = "Execution")]
     check: bool,
 
-    /// generate autocompletions for the given shell.
-    #[arg(long)]
-    completions: Option<Shell>,
-
     /// show the mutation diffs.
-    #[arg(long)]
+    #[arg(long, help_heading = "Filters")]
     diff: bool,
 
     /// rust crate directory to examine.
-    #[arg(long, short = 'd', conflicts_with = "manifest_path")]
+    #[arg(
+        long,
+        short = 'd',
+        conflicts_with = "manifest_path",
+        help_heading = "Input"
+    )]
     dir: Option<Utf8PathBuf>,
 
+    /// generate autocompletions for the given shell.
+    #[arg(long)]
+    completions: Option<Shell>,
+
     /// return this error values from functions returning Result:
     /// for example, `::anyhow::anyhow!("mutated")`.
-    #[arg(long)]
+    #[arg(long, help_heading = "Generate")]
     error: Vec<String>,
 
     /// regex for mutations to examine, matched against the names shown by `--list`.
@@ -143,133 +148,149 @@ struct Args {
         short = 'F',
         alias = "regex",
         alias = "examine-regex",
-        alias = "examine-re"
+        alias = "examine-re",
+        help_heading = "Filters"
     )]
     examine_re: Vec<String>,
 
     /// glob for files to exclude; with no glob, all files are included; globs containing
     /// slash match the entire path. If used together with `--file` argument, then the files to be examined are matched before the files to be excluded.
-    #[arg(long, short = 'e')]
+    #[arg(long, short = 'e', help_heading = "Filters")]
     exclude: Vec<String>,
 
     /// regex for mutations to exclude, matched against the names shown by `--list`.
-    #[arg(long, short = 'E', alias = "exclude-regex")]
+    #[arg(long, short = 'E', alias = "exclude-regex", help_heading = "Filters")]
     exclude_re: Vec<String>,
 
     /// glob for files to examine; with no glob, all files are examined; globs containing
     /// slash match the entire path. If used together with `--exclude` argument, then the files to be examined are matched before the files to be excluded.
-    #[arg(long, short = 'f')]
+    #[arg(long, short = 'f', help_heading = "Filters")]
     file: Vec<String>,
 
     /// don't copy files matching gitignore patterns.
-    #[arg(long, action = ArgAction::Set, default_value = "true")]
+    #[arg(long, action = ArgAction::Set, default_value = "true", help_heading = "Copying")]
     gitignore: bool,
 
     /// run this many cargo build/test jobs in parallel.
-    #[arg(long, short = 'j', env = "CARGO_MUTANTS_JOBS")]
+    #[arg(
+        long,
+        short = 'j',
+        env = "CARGO_MUTANTS_JOBS",
+        help_heading = "Execution"
+    )]
     jobs: Option<usize>,
 
     /// output json (only for --list).
-    #[arg(long)]
+    #[arg(long, help_heading = "Output")]
     json: bool,
 
     /// don't delete the scratch directories, for debugging.
-    #[arg(long)]
+    #[arg(long, help_heading = "Debug")]
     leak_dirs: bool,
 
     /// log level for stdout (trace, debug, info, warn, error).
     #[arg(
         long,
         short = 'L',
         default_value = "info",
-        env = "CARGO_MUTANTS_TRACE_LEVEL"
+        env = "CARGO_MUTANTS_TRACE_LEVEL",
+        help_heading = "Debug"
     )]
     level: tracing::Level,
 
     /// just list possible mutants, don't run them.
-    #[arg(long)]
+    #[arg(long, help_heading = "Execution")]
     list: bool,
 
     /// list source files, don't run anything.
-    #[arg(long)]
+    #[arg(long, help_heading = "Execution")]
     list_files: bool,
 
     /// path to Cargo.toml for the package to mutate.
-    #[arg(long)]
+    #[arg(long, help_heading = "Input")]
     manifest_path: Option<Utf8PathBuf>,
 
     /// don't read .cargo/mutants.toml.
-    #[arg(long)]
+    #[arg(long, help_heading = "Input")]
     no_config: bool,
 
     /// don't copy the /target directory, and don't build the source tree first.
-    #[arg(long)]
+    #[arg(long, help_heading = "Copying")]
     no_copy_target: bool,
 
     /// don't print times or tree sizes, to make output deterministic.
-    #[arg(long)]
+    #[arg(long, help_heading = "Output")]
     no_times: bool,
 
     /// include line & column numbers in the mutation list.
-    #[arg(long, action = ArgAction::Set, default_value = "true")]
+    #[arg(long, action = ArgAction::Set, default_value = "true", help_heading = "Output")]
     line_col: bool,
 
     /// create mutants.out within this directory.
-    #[arg(long, short = 'o')]
+    #[arg(long, short = 'o', help_heading = "Output")]
     output: Option<Utf8PathBuf>,
 
     /// include only mutants in code touched by this diff.
-    #[arg(long, short = 'D')]
+    #[arg(long, short = 'D', help_heading = "Filters")]
     in_diff: Option<Utf8PathBuf>,
 
     /// minimum timeout for tests, in seconds, as a lower bound on the auto-set time.
-    #[arg(long, env = "CARGO_MUTANTS_MINIMUM_TEST_TIMEOUT")]
+    #[arg(
+        long,
+        env = "CARGO_MUTANTS_MINIMUM_TEST_TIMEOUT",
+        help_heading = "Execution"
+    )]
     minimum_test_timeout: Option<f64>,
 
     /// only test mutants from these packages.
-    #[arg(id = "package", long, short = 'p')]
+    #[arg(id = "package", long, short = 'p', help_heading = "Filters")]
     mutate_packages: Vec<String>,
 
     /// run mutants in random order.
-    #[arg(long)]
+    #[arg(long, help_heading = "Execution")]
     shuffle: bool,
 
     /// run mutants in the fixed order they occur in the source tree.
-    #[arg(long)]
+    #[arg(long, help_heading = "Execution")]
     no_shuffle: bool,
 
     /// run only one shard of all generated mutants: specify as e.g. 1/4.
-    #[arg(long)]
+    #[arg(long, help_heading = "Execution")]
     shard: Option<Shard>,
 
     /// tool used to run test suites: cargo or nextest.
-    #[arg(long)]
+    #[arg(long, help_heading = "Execution")]
     test_tool: Option<TestTool>,
 
     /// maximum run time for all cargo commands, in seconds.
-    #[arg(long, short = 't')]
+    #[arg(long, short = 't', help_heading = "Execution")]
     timeout: Option<f64>,
 
     /// print mutations that failed to check or build.
-    #[arg(long, short = 'V')]
+    #[arg(long, short = 'V', help_heading = "Output")]
     unviable: bool,
 
     /// show version and quit.
     #[arg(long, action = clap::ArgAction::SetTrue)]
     version: bool,
 
     /// test every package in the workspace.
-    #[arg(long)]
+    #[arg(long, help_heading = "Filters")]
     workspace: bool,
 
     /// additional args for all cargo invocations.
-    #[arg(long, short = 'C', allow_hyphen_values = true)]
+    #[arg(
+        long,
+        short = 'C',
+        allow_hyphen_values = true,
+        help_heading = "Execution"
+    )]
     cargo_arg: Vec<String>,
 
     // The following option captures all the remaining non-option args, to
     // send to cargo.
     /// pass remaining arguments to cargo test after all options and after `--`.
-    #[arg(last = true)]
+    #[arg(last = true, help_heading = "Execution")]
     cargo_test_args: Vec<String>,
 }