Merge pull request #4125 from epage/sub

fix(help): Shift focus to subcommands, when present

CHANGELOG.md

@@ -85,6 +85,7 @@ MSRV is now 1.60.0
 - *(help)* Show when a flag is `ArgAction::Count` by adding an `...`
 - *(help)* Use a more neutral palette for coloring
 - *(help)* Don't rely on ALL CAPS for help headers
+- *(help)* List subcommands first, focusing the emphasis on them
 - *(version)* Use `Command::display_name` rather than `Command::bin_name`
 - *(parser)* Assert on unknown args when using external subcommands (#3703)
 - *(parser)* Always fill in `""` argument for external subcommands (#3263)

examples/cargo-example-derive.md

@@ -11,13 +11,13 @@ cargo
 Usage:
     cargo <SUBCOMMAND>
 
-Options:
-    -h, --help    Print help information
-
 Subcommands:
     example-derive    A simple to use, efficient, and full-featured Command Line Argument Parser
     help              Print this message or the help of the given subcommand(s)
 
+Options:
+    -h, --help    Print help information
+
 $ cargo-example-derive example-derive --help
 cargo-example-derive [..]
 A simple to use, efficient, and full-featured Command Line Argument Parser

examples/cargo-example.md

@@ -11,13 +11,13 @@ cargo
 Usage:
     cargo <SUBCOMMAND>
 
-Options:
-    -h, --help    Print help information
-
 Subcommands:
     example    A simple to use, efficient, and full-featured Command Line Argument Parser
     help       Print this message or the help of the given subcommand(s)
 
+Options:
+    -h, --help    Print help information
+
 $ cargo-example example --help
 cargo-example [..]
 A simple to use, efficient, and full-featured Command Line Argument Parser

examples/derive_ref/interop_tests.md

@@ -106,15 +106,15 @@ clap
 Usage:
     interop_hand_subcommand[EXE] [OPTIONS] <SUBCOMMAND>
 
-Options:
-    -t, --top-level    
-    -h, --help         Print help information
-
 Subcommands:
     add       
     remove    
     help      Print this message or the help of the given subcommand(s)
 
+Options:
+    -t, --top-level    
+    -h, --help         Print help information
+
 ```
 
 ```console

examples/git-derive.md

@@ -12,33 +12,33 @@ A fictional versioning CLI
 Usage:
     git-derive[EXE] <SUBCOMMAND>
 
-Options:
-    -h, --help    Print help information
-
 Subcommands:
     clone    Clones repos
     push     pushes things
     add      adds things
     stash    
     help     Print this message or the help of the given subcommand(s)
 
+Options:
+    -h, --help    Print help information
+
 $ git-derive help
 git 
 A fictional versioning CLI
 
 Usage:
     git-derive[EXE] <SUBCOMMAND>
 
-Options:
-    -h, --help    Print help information
-
 Subcommands:
     clone    Clones repos
     push     pushes things
     add      adds things
     stash    
     help     Print this message or the help of the given subcommand(s)
 
+Options:
+    -h, --help    Print help information
+
 $ git-derive help add
 git-add 
 adds things
@@ -84,16 +84,16 @@ Usage:
     git-derive[EXE] stash [OPTIONS]
     git-derive[EXE] stash <SUBCOMMAND>
 
-Options:
-    -m, --message <MESSAGE>    
-    -h, --help                 Print help information
-
 Subcommands:
     push     
     pop      
     apply    
     help     Print this message or the help of the given subcommand(s)
 
+Options:
+    -m, --message <MESSAGE>    
+    -h, --help                 Print help information
+
 $ git-derive stash push -h
 git-stash-push 
 

examples/git.md

@@ -10,33 +10,33 @@ A fictional versioning CLI
 Usage:
     git[EXE] <SUBCOMMAND>
 
-Options:
-    -h, --help    Print help information
-
 Subcommands:
     clone    Clones repos
     push     pushes things
     add      adds things
     stash    
     help     Print this message or the help of the given subcommand(s)
 
+Options:
+    -h, --help    Print help information
+
 $ git help
 git 
 A fictional versioning CLI
 
 Usage:
     git[EXE] <SUBCOMMAND>
 
-Options:
-    -h, --help    Print help information
-
 Subcommands:
     clone    Clones repos
     push     pushes things
     add      adds things
     stash    
     help     Print this message or the help of the given subcommand(s)
 
+Options:
+    -h, --help    Print help information
+
 $ git help add
 git-add 
 adds things
@@ -82,16 +82,16 @@ Usage:
     git[EXE] stash [OPTIONS]
     git[EXE] stash <SUBCOMMAND>
 
-Options:
-    -m, --message <MESSAGE>    
-    -h, --help                 Print help information
-
 Subcommands:
     push     
     pop      
     apply    
     help     Print this message or the help of the given subcommand(s)
 
+Options:
+    -m, --message <MESSAGE>    
+    -h, --help                 Print help information
+
 $ git stash push -h
 git-stash-push 
 

examples/multicall-busybox.md

@@ -30,13 +30,13 @@ busybox
 Usage:
     busybox [OPTIONS] [APPLET]
 
-Options:
-        --install <install>    Install hardlinks for all subcommands in path
-    -h, --help                 Print help information
-
 APPLETS:
     true     does nothing successfully
     false    does nothing unsuccessfully
     help     Print this message or the help of the given subcommand(s)
 
+Options:
+        --install <install>    Install hardlinks for all subcommands in path
+    -h, --help                 Print help information
+
 ```

examples/pacman.md

@@ -42,15 +42,15 @@ package manager utility
 Usage:
     pacman[EXE] <SUBCOMMAND>
 
-Options:
-    -h, --help       Print help information
-    -V, --version    Print version information
-
 Subcommands:
     query -Q --query    Query the package database.
     sync -S --sync      Synchronize packages.
     help                Print this message or the help of the given subcommand(s)
 
+Options:
+    -h, --help       Print help information
+    -V, --version    Print version information
+
 $ pacman -S -h
 pacman-sync 
 Synchronize packages.

examples/tutorial_builder/01_quick.md

@@ -6,6 +6,10 @@ A simple to use, efficient, and full-featured Command Line Argument Parser
 Usage:
     01_quick[EXE] [OPTIONS] [name] [SUBCOMMAND]
 
+Subcommands:
+    test    does testing things
+    help    Print this message or the help of the given subcommand(s)
+
 Arguments:
     <name>    Optional name to operate on
 
@@ -15,10 +19,6 @@ Options:
     -h, --help             Print help information
     -V, --version          Print version information
 
-Subcommands:
-    test    does testing things
-    help    Print this message or the help of the given subcommand(s)
-
 ```
 
 By default, the program does nothing:

examples/tutorial_builder/03_04_subcommands.md

@@ -6,14 +6,14 @@ A simple to use, efficient, and full-featured Command Line Argument Parser
 Usage:
     03_04_subcommands[EXE] <SUBCOMMAND>
 
-Options:
-    -h, --help       Print help information
-    -V, --version    Print version information
-
 Subcommands:
     add     Adds files to myapp
     help    Print this message or the help of the given subcommand(s)
 
+Options:
+    -h, --help       Print help information
+    -V, --version    Print version information
+
 $ 03_04_subcommands help add
 clap-add [..]
 Adds files to myapp
@@ -43,14 +43,14 @@ A simple to use, efficient, and full-featured Command Line Argument Parser
 Usage:
     03_04_subcommands[EXE] <SUBCOMMAND>
 
-Options:
-    -h, --help       Print help information
-    -V, --version    Print version information
-
 Subcommands:
     add     Adds files to myapp
     help    Print this message or the help of the given subcommand(s)
 
+Options:
+    -h, --help       Print help information
+    -V, --version    Print version information
+
 ```
 
 Because we set [`Command::propagate_version`][crate::Command::propagate_version]:

examples/tutorial_derive/01_quick.md

@@ -6,6 +6,10 @@ A simple to use, efficient, and full-featured Command Line Argument Parser
 Usage:
     01_quick_derive[EXE] [OPTIONS] [NAME] [SUBCOMMAND]
 
+Subcommands:
+    test    does testing things
+    help    Print this message or the help of the given subcommand(s)
+
 Arguments:
     <NAME>    Optional name to operate on
 
@@ -15,10 +19,6 @@ Options:
     -h, --help             Print help information
     -V, --version          Print version information
 
-Subcommands:
-    test    does testing things
-    help    Print this message or the help of the given subcommand(s)
-
 ```
 
 By default, the program does nothing:

examples/tutorial_derive/03_04_subcommands.md

@@ -6,14 +6,14 @@ A simple to use, efficient, and full-featured Command Line Argument Parser
 Usage:
     03_04_subcommands_derive[EXE] <SUBCOMMAND>
 
-Options:
-    -h, --help       Print help information
-    -V, --version    Print version information
-
 Subcommands:
     add     Adds files to myapp
     help    Print this message or the help of the given subcommand(s)
 
+Options:
+    -h, --help       Print help information
+    -V, --version    Print version information
+
 $ 03_04_subcommands_derive help add
 clap-add [..]
 Adds files to myapp
@@ -43,14 +43,14 @@ A simple to use, efficient, and full-featured Command Line Argument Parser
 Usage:
     03_04_subcommands_derive[EXE] <SUBCOMMAND>
 
-Options:
-    -h, --help       Print help information
-    -V, --version    Print version information
-
 Subcommands:
     add     Adds files to myapp
     help    Print this message or the help of the given subcommand(s)
 
+Options:
+    -h, --help       Print help information
+    -V, --version    Print version information
+
 ```
 
 Because we added `#[clap(propagate_version = true)]`: