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>,
 
-    /// Custom config file
-    #[arg(short = 'c', long = "config")]
-    pub(crate) custom_config: Option<std::path::PathBuf>,
-
-    /// Ignore implicit configuration files.
-    #[arg(long)]
-    pub(crate) isolated: bool,
-
-    /// Print a diff of what would change
-    #[arg(long, group = "mode")]
-    pub(crate) diff: bool,
-
-    /// Write fixes out
-    #[arg(long, short = 'w', group = "mode")]
-    pub(crate) write_changes: bool,
-
-    /// Debug: Print each file that would be spellchecked.
-    #[arg(long, group = "mode")]
-    pub(crate) files: bool,
-
-    /// Debug: Print each file's type
-    #[arg(long, group = "mode")]
-    pub(crate) file_types: bool,
-
-    /// Debug: Print each identifier that would be spellchecked.
-    #[arg(long, group = "mode")]
-    pub(crate) identifiers: bool,
-
-    /// Debug: Print each word that would be spellchecked.
-    #[arg(long, group = "mode")]
-    pub(crate) words: bool,
-
-    /// Write the current configuration to file with `-` for stdout
-    #[arg(long, group = "mode")]
-    pub(crate) dump_config: Option<std::path::PathBuf>,
-
-    /// Show all supported file types.
-    #[arg(long, group = "mode")]
-    pub(crate) type_list: bool,
-
-    #[arg(long, value_enum, ignore_case = true, default_value("long"))]
-    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)]
+    /// Custom config file
+    #[arg(short = 'c', long = "config", help_heading = "Config")]
+    pub(crate) custom_config: Option<std::path::PathBuf>,
+
+    /// Ignore implicit configuration files.
+    #[arg(long, help_heading = "Config")]
+    pub(crate) isolated: bool,
+
+    #[command(flatten, next_help_heading = "Config")]
     pub(crate) config: ConfigArgs,
 
-    #[command(flatten)]
+    /// Print a diff of what would change
+    #[arg(long, group = "mode", help_heading = "Mode")]
+    pub(crate) diff: bool,
+
+    /// Write fixes out
+    #[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", help_heading = "Mode")]
+    pub(crate) files: bool,
+
+    /// Debug: Print each file's type
+    #[arg(long, group = "mode", help_heading = "Mode")]
+    pub(crate) file_types: bool,
+
+    /// Debug: Print each identifier that would be spellchecked.
+    #[arg(long, group = "mode", help_heading = "Mode")]
+    pub(crate) identifiers: bool,
+
+    /// Debug: Print each word that would be spellchecked.
+    #[arg(long, group = "mode", help_heading = "Mode")]
+    pub(crate) words: bool,
+
+    /// Write the current configuration to file with `-` for stdout
+    #[arg(long, group = "mode", help_heading = "Mode")]
+    pub(crate) dump_config: Option<std::path::PathBuf>,
+
+    /// Show all supported file types.
+    #[arg(long, group = "mode", help_heading = "Mode")]
+    pub(crate) type_list: bool,
+
+    /// Render style for messages
+    #[arg(
+        long,
+        value_enum,
+        ignore_case = true,
+        default_value("long"),
+        help_heading = "Output"
+    )]
+    pub(crate) format: Format,
+
+    #[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

@@ -3,14 +3,33 @@ args = "--help"
 stdout = """
 Source Code Spelling Correction
 
-Usage: typos [OPTIONS] [PATH]...
+Usage: typos[EXE] [OPTIONS] [PATH]...
 
 Arguments:
   [PATH]...  Paths to check with `-` for stdin [default: .]
 
 Options:
-  -c, --config <CUSTOM_CONFIG>     Custom config file
+  -j, --threads <THREADS>  The approximate number of threads to use [default: 0]
-      --isolated                   Ignore implicit configuration files
+  -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
@@ -19,24 +38,11 @@ Options:
       --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
-      --format <FORMAT>            [default: long] [possible values: silent, brief, long, json]
+
-  -j, --threads <THREADS>          The approximate number of threads to use [default: 0]
+Output:
-      --exclude <GLOB>             Ignore files & directories matching the glob
+      --format <FORMAT>  Render style for messages [default: long] [possible values: silent, brief, long, json]
-      --hidden                     Search hidden files and directories
+      --color <WHEN>     Controls when to use color [default: auto] [possible values: auto, always, never]
-      --no-ignore                  Don't respect ignore files
+  -v, --verbose...       More output per occurrence
-      --no-ignore-dot              Don't respect .ignore files
+  -q, --quiet...         Less output per occurrence
-      --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>            [possible values: en, en-us, en-gb, en-ca, en-au]
-      --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
-  -h, --help                       Print help
-  -V, --version                    Print version
 """
 stderr = ""