fix(cli): Improve help layout

crates/typos-cli/src/bin/typos-cli/args.rs

@@ -42,60 +42,67 @@ pub(crate) struct Args {
     #[arg(default_value = ".")]
     pub(crate) path: Vec<std::path::PathBuf>,
 
+    /// The approximate number of threads to use.
+    #[arg(short = 'j', long = "threads", default_value = "0")]
+    pub(crate) threads: usize,
+
     /// Custom config file
-    #[arg(short = 'c', long = "config")]
+    #[arg(short = 'c', long = "config", help_heading = "Config")]
     pub(crate) custom_config: Option<std::path::PathBuf>,
 
     /// Ignore implicit configuration files.
-    #[arg(long)]
+    #[arg(long, help_heading = "Config")]
     pub(crate) isolated: bool,
 
+    #[command(flatten, next_help_heading = "Config")]
+    pub(crate) config: ConfigArgs,
+
     /// Print a diff of what would change
-    #[arg(long, group = "mode")]
+    #[arg(long, group = "mode", help_heading = "Mode")]
     pub(crate) diff: bool,
 
     /// Write fixes out
-    #[arg(long, short = 'w', group = "mode")]
+    #[arg(long, short = 'w', group = "mode", help_heading = "Mode")]
     pub(crate) write_changes: bool,
 
     /// Debug: Print each file that would be spellchecked.
-    #[arg(long, group = "mode")]
+    #[arg(long, group = "mode", help_heading = "Mode")]
     pub(crate) files: bool,
 
     /// Debug: Print each file's type
-    #[arg(long, group = "mode")]
+    #[arg(long, group = "mode", help_heading = "Mode")]
     pub(crate) file_types: bool,
 
     /// Debug: Print each identifier that would be spellchecked.
-    #[arg(long, group = "mode")]
+    #[arg(long, group = "mode", help_heading = "Mode")]
     pub(crate) identifiers: bool,
 
     /// Debug: Print each word that would be spellchecked.
-    #[arg(long, group = "mode")]
+    #[arg(long, group = "mode", help_heading = "Mode")]
     pub(crate) words: bool,
 
     /// Write the current configuration to file with `-` for stdout
-    #[arg(long, group = "mode")]
+    #[arg(long, group = "mode", help_heading = "Mode")]
     pub(crate) dump_config: Option<std::path::PathBuf>,
 
     /// Show all supported file types.
-    #[arg(long, group = "mode")]
+    #[arg(long, group = "mode", help_heading = "Mode")]
     pub(crate) type_list: bool,
 
-    #[arg(long, value_enum, ignore_case = true, default_value("long"))]
+    /// Render style for messages
+    #[arg(
+        long,
+        value_enum,
+        ignore_case = true,
+        default_value("long"),
+        help_heading = "Output"
+    )]
     pub(crate) format: Format,
 
-    /// The approximate number of threads to use.
-    #[arg(short = 'j', long = "threads", default_value = "0")]
-    pub(crate) threads: usize,
-
-    #[command(flatten)]
-    pub(crate) config: ConfigArgs,
-
-    #[command(flatten)]
+    #[command(flatten, next_help_heading = "Output")]
     pub(crate) color: colorchoice_clap::Color,
 
-    #[command(flatten)]
+    #[command(flatten, next_help_heading = "Output")]
     pub(crate) verbose: clap_verbosity_flag::Verbosity,
 }
 
@@ -126,6 +133,7 @@ pub(crate) struct FileArgs {
     #[arg(long, overrides_with("unicode"))]
     no_unicode: bool,
 
+    /// Language locale to suggest corrections for
     #[arg(long)]
     #[arg(
         value_parser = clap::builder::PossibleValuesParser::new(config::Locale::variants())

crates/typos-cli/tests/cmd/help.toml

@@ -0,0 +1,48 @@
+bin.name = "typos"
+args = "--help"
+stdout = """
+Source Code Spelling Correction
+
+Usage: typos[EXE] [OPTIONS] [PATH]...
+
+Arguments:
+  [PATH]...  Paths to check with `-` for stdin [default: .]
+
+Options:
+  -j, --threads <THREADS>  The approximate number of threads to use [default: 0]
+  -h, --help               Print help
+  -V, --version            Print version
+
+Config:
+  -c, --config <CUSTOM_CONFIG>  Custom config file
+      --isolated                Ignore implicit configuration files
+      --exclude <GLOB>          Ignore files & directories matching the glob
+      --hidden                  Search hidden files and directories
+      --no-ignore               Don't respect ignore files
+      --no-ignore-dot           Don't respect .ignore files
+      --no-ignore-global        Don't respect global ignore files
+      --no-ignore-parent        Don't respect ignore files in parent directories
+      --no-ignore-vcs           Don't respect ignore files in vcs directories
+      --binary                  Search binary files
+      --no-check-filenames      Skip verifying spelling in file names
+      --no-check-files          Skip verifying spelling in files
+      --no-unicode              Only allow ASCII characters in identifiers
+      --locale <LOCALE>         Language locale to suggest corrections for [possible values: en, en-us, en-gb, en-ca, en-au]
+
+Mode:
+      --diff                       Print a diff of what would change
+  -w, --write-changes              Write fixes out
+      --files                      Debug: Print each file that would be spellchecked
+      --file-types                 Debug: Print each file's type
+      --identifiers                Debug: Print each identifier that would be spellchecked
+      --words                      Debug: Print each word that would be spellchecked
+      --dump-config <DUMP_CONFIG>  Write the current configuration to file with `-` for stdout
+      --type-list                  Show all supported file types
+
+Output:
+      --format <FORMAT>  Render style for messages [default: long] [possible values: silent, brief, long, json]
+      --color <WHEN>     Controls when to use color [default: auto] [possible values: auto, always, never]
+  -v, --verbose...       More output per occurrence
+  -q, --quiet...         Less output per occurrence
+"""
+stderr = ""