fix(help): Use Command in place of Subcommand

In switching to title case for help headings (#4123), it caused me to look at "subcommand" in a fresh light. I can't quite put my finger on it but "Subcommand" looks a bit sloppy. I also have recently been surveying other CLIs and they just use "command" as well. All of them are commands anyways, just some are children of others (subcommands) while others are not (root or top-level commands, or just command). Context is good enough for clarifying subcommands from root commands. This is part of #4132
clap-rs · Aug 31, 2022 · 42c9438 · 42c9438
1 parent c2f9ecd
commit 42c9438
Show file tree

Hide file tree

Showing 26 changed files with 110 additions and 108 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -47,6 +47,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - *(help)* Make `DeriveDisplayOrder` the default and removed the setting.  To sort help, set `next_display_order(None)` (#2808)
 - *(help)* Subcommand display order respects `Command::next_display_order` instead of `DeriveDisplayOrder` and using its own initial display order value (#2808)
 - *(help)* Help headings are now title cased, making any user-provided help headings inconsistent.  To get the old behavior, see `Command::help_template`, `Arg::help_heading`, and `Command::subcommand_help_heading`
+- *(help)* "Command" is used as the section heading for subcommands and `COMMAND` for the value name.  To get the old behavior, see  `Command::subcommand_help_heading` and `Arg::subcommand_value_name`
 - *(env)* Parse `--help` and `--version` like any `ArgAction::SetTrue` flag (#3776)
 - *(derive)* Changed the default for arguments from `parse` to `value_parser`., removing `parse` support
 - *(derive)* `subcommand_required(true).arg_required_else_help(true)` is set instead of `SubcommandRequiredElseHelp` (#3280)
@@ -96,6 +97,7 @@ Deprecated
 - *(help)* Do not include global args in `cmd help help` (#4131)
 - *(help)* Use `[positional]` in list when relevant (#4144)
 - *(help)* Show all `[positional]` in usage
+- *(help)* Polish up subcommands by referring to them as commands
 - *(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)

diff --git a/examples/cargo-example-derive.md b/examples/cargo-example-derive.md
@@ -9,9 +9,9 @@ $ cargo-example-derive --help
 cargo 
 
 Usage:
-    cargo <SUBCOMMAND>
+    cargo <COMMAND>
 
-Subcommands:
+Commands:
     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)
 

diff --git a/examples/cargo-example.md b/examples/cargo-example.md
@@ -9,9 +9,9 @@ $ cargo-example --help
 cargo 
 
 Usage:
-    cargo <SUBCOMMAND>
+    cargo <COMMAND>
 
-Subcommands:
+Commands:
     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)
 

diff --git a/examples/derive_ref/interop_tests.md b/examples/derive_ref/interop_tests.md
@@ -90,7 +90,7 @@ $ interop_augment_subcommands unknown
 error: Found argument 'unknown' which wasn't expected, or isn't valid in this context
 
 Usage:
-    interop_augment_subcommands[EXE] [SUBCOMMAND]
+    interop_augment_subcommands[EXE] [COMMAND]
 
 For more information try --help
 
@@ -104,9 +104,9 @@ $ interop_hand_subcommand
 clap 
 
 Usage:
-    interop_hand_subcommand[EXE] [OPTIONS] <SUBCOMMAND>
+    interop_hand_subcommand[EXE] [OPTIONS] <COMMAND>
 
-Subcommands:
+Commands:
     add       
     remove    
     help      Print this message or the help of the given subcommand(s)
@@ -199,7 +199,7 @@ $ interop_hand_subcommand unknown
 error: Found argument 'unknown' which wasn't expected, or isn't valid in this context
 
 Usage:
-    interop_hand_subcommand[EXE] [OPTIONS] <SUBCOMMAND>
+    interop_hand_subcommand[EXE] [OPTIONS] <COMMAND>
 
 For more information try --help
 

diff --git a/examples/git-derive.md b/examples/git-derive.md
@@ -10,9 +10,9 @@ git
 A fictional versioning CLI
 
 Usage:
-    git-derive[EXE] <SUBCOMMAND>
+    git-derive[EXE] <COMMAND>
 
-Subcommands:
+Commands:
     clone    Clones repos
     push     pushes things
     add      adds things
@@ -27,9 +27,9 @@ git
 A fictional versioning CLI
 
 Usage:
-    git-derive[EXE] <SUBCOMMAND>
+    git-derive[EXE] <COMMAND>
 
-Subcommands:
+Commands:
     clone    Clones repos
     push     pushes things
     add      adds things
@@ -82,9 +82,9 @@ git-stash
 
 Usage:
     git-derive[EXE] stash [OPTIONS]
-    git-derive[EXE] stash <SUBCOMMAND>
+    git-derive[EXE] stash <COMMAND>
 
-Subcommands:
+Commands:
     push     
     pop      
     apply    

diff --git a/examples/git.md b/examples/git.md
@@ -8,9 +8,9 @@ git
 A fictional versioning CLI
 
 Usage:
-    git[EXE] <SUBCOMMAND>
+    git[EXE] <COMMAND>
 
-Subcommands:
+Commands:
     clone    Clones repos
     push     pushes things
     add      adds things
@@ -25,9 +25,9 @@ git
 A fictional versioning CLI
 
 Usage:
-    git[EXE] <SUBCOMMAND>
+    git[EXE] <COMMAND>
 
-Subcommands:
+Commands:
     clone    Clones repos
     push     pushes things
     add      adds things
@@ -80,9 +80,9 @@ git-stash
 
 Usage:
     git[EXE] stash [OPTIONS]
-    git[EXE] stash <SUBCOMMAND>
+    git[EXE] stash <COMMAND>
 
-Subcommands:
+Commands:
     push     
     pop      
     apply    

diff --git a/examples/pacman.md b/examples/pacman.md
@@ -40,9 +40,9 @@ Pacman Development Team
 package manager utility
 
 Usage:
-    pacman[EXE] <SUBCOMMAND>
+    pacman[EXE] <COMMAND>
 
-Subcommands:
+Commands:
     query -Q --query    Query the package database.
     sync -S --sync      Synchronize packages.
     help                Print this message or the help of the given subcommand(s)

diff --git a/examples/tutorial_builder/01_quick.md b/examples/tutorial_builder/01_quick.md
@@ -4,9 +4,9 @@ clap [..]
 A simple to use, efficient, and full-featured Command Line Argument Parser
 
 Usage:
-    01_quick[EXE] [OPTIONS] [name] [SUBCOMMAND]
+    01_quick[EXE] [OPTIONS] [name] [COMMAND]
 
-Subcommands:
+Commands:
     test    does testing things
     help    Print this message or the help of the given subcommand(s)
 

diff --git a/examples/tutorial_builder/03_04_subcommands.md b/examples/tutorial_builder/03_04_subcommands.md
@@ -4,9 +4,9 @@ clap [..]
 A simple to use, efficient, and full-featured Command Line Argument Parser
 
 Usage:
-    03_04_subcommands[EXE] <SUBCOMMAND>
+    03_04_subcommands[EXE] <COMMAND>
 
-Subcommands:
+Commands:
     add     Adds files to myapp
     help    Print this message or the help of the given subcommand(s)
 
@@ -41,9 +41,9 @@ clap [..]
 A simple to use, efficient, and full-featured Command Line Argument Parser
 
 Usage:
-    03_04_subcommands[EXE] <SUBCOMMAND>
+    03_04_subcommands[EXE] <COMMAND>
 
-Subcommands:
+Commands:
     add     Adds files to myapp
     help    Print this message or the help of the given subcommand(s)
 

diff --git a/examples/tutorial_derive/01_quick.md b/examples/tutorial_derive/01_quick.md
@@ -4,9 +4,9 @@ clap [..]
 A simple to use, efficient, and full-featured Command Line Argument Parser
 
 Usage:
-    01_quick_derive[EXE] [OPTIONS] [NAME] [SUBCOMMAND]
+    01_quick_derive[EXE] [OPTIONS] [NAME] [COMMAND]
 
-Subcommands:
+Commands:
     test    does testing things
     help    Print this message or the help of the given subcommand(s)
 

diff --git a/examples/tutorial_derive/03_04_subcommands.md b/examples/tutorial_derive/03_04_subcommands.md
@@ -4,9 +4,9 @@ clap [..]
 A simple to use, efficient, and full-featured Command Line Argument Parser
 
 Usage:
-    03_04_subcommands_derive[EXE] <SUBCOMMAND>
+    03_04_subcommands_derive[EXE] <COMMAND>
 
-Subcommands:
+Commands:
     add     Adds files to myapp
     help    Print this message or the help of the given subcommand(s)
 
@@ -41,9 +41,9 @@ clap [..]
 A simple to use, efficient, and full-featured Command Line Argument Parser
 
 Usage:
-    03_04_subcommands_derive[EXE] <SUBCOMMAND>
+    03_04_subcommands_derive[EXE] <COMMAND>
 
-Subcommands:
+Commands:
     add     Adds files to myapp
     help    Print this message or the help of the given subcommand(s)
 

diff --git a/src/builder/command.rs b/src/builder/command.rs
@@ -2588,7 +2588,7 @@ impl Command {
     /// Usage:
     ///     cust-ord [OPTIONS]
     ///
-    /// Subcommands:
+    /// Commands:
     ///     beta    I should be first!
     ///     alpha   Some help and text
     ///
@@ -3034,7 +3034,7 @@ impl Command {
 
     /// Sets the value name used for subcommands when printing usage and help.
     ///
-    /// By default, this is "SUBCOMMAND".
+    /// By default, this is "COMMAND".
     ///
     /// See also [`Command::subcommand_help_heading`]
     ///
@@ -3054,9 +3054,9 @@ impl Command {
     /// myprog
     ///
     /// Usage:
-    ///     myprog [SUBCOMMAND]
+    ///     myprog [COMMAND]
     ///
-    /// Subcommands:
+    /// Commands:
     ///     help    Print this message or the help of the given subcommand(s)
     ///     sub1
     ///
@@ -3088,7 +3088,7 @@ impl Command {
     ///     -h, --help       Print help information
     ///     -V, --version    Print version information
     ///
-    /// Subcommands:
+    /// Commands:
     ///     help    Print this message or the help of the given subcommand(s)
     ///     sub1
     /// ```
@@ -3100,7 +3100,7 @@ impl Command {
 
     /// Sets the help heading used for subcommands when printing usage and help.
     ///
-    /// By default, this is "Subcommands".
+    /// By default, this is "Commands".
     ///
     /// See also [`Command::subcommand_value_name`]
     ///
@@ -3120,13 +3120,13 @@ impl Command {
     /// myprog
     ///
     /// Usage:
-    ///     myprog [SUBCOMMAND]
+    ///     myprog [COMMAND]
     ///
     /// Options:
     ///     -h, --help       Print help information
     ///     -V, --version    Print version information
     ///
-    /// Subcommands:
+    /// Commands:
     ///     help    Print this message or the help of the given subcommand(s)
     ///     sub1
     /// ```
@@ -3148,7 +3148,7 @@ impl Command {
     /// myprog
     ///
     /// Usage:
-    ///     myprog [SUBCOMMAND]
+    ///     myprog [COMMAND]
     ///
     /// Options:
     ///     -h, --help       Print help information
@@ -4171,7 +4171,7 @@ impl Command {
                     Arg::new("subcommand")
                         .action(ArgAction::Append)
                         .num_args(..)
-                        .value_name("SUBCOMMAND")
+                        .value_name("COMMAND")
                         .help("The subcommand whose help message to display"),
                 )
             };

diff --git a/src/output/help.rs b/src/output/help.rs
@@ -345,7 +345,7 @@ impl<'cmd, 'writer> Help<'cmd, 'writer> {
                 self.none("\n\n");
             }
             first = false;
-            let default_help_heading = Str::from("Subcommands");
+            let default_help_heading = Str::from("Commands");
             self.header(
                 self.cmd
                     .get_subcommand_help_heading()

diff --git a/src/output/usage.rs b/src/output/usage.rs
@@ -6,7 +6,7 @@ use crate::util::ChildGraph;
 use crate::util::FlatSet;
 use crate::util::Id;
 
-static DEFAULT_SUB_VALUE_NAME: &str = "SUBCOMMAND";
+static DEFAULT_SUB_VALUE_NAME: &str = "COMMAND";
 
 pub(crate) struct Usage<'cmd> {
     cmd: &'cmd Command,

diff --git a/tests/builder/app_settings.rs b/tests/builder/app_settings.rs
@@ -7,7 +7,7 @@ use clap::{arg, error::ErrorKind, Arg, ArgAction, Command};
 static ALLOW_EXT_SC: &str = "clap-test v1.4.8
 
 Usage:
-    clap-test [SUBCOMMAND]
+    clap-test [COMMAND]
 
 Options:
     -h, --help       Print help information

diff --git a/tests/builder/derive_order.rs b/tests/builder/derive_order.rs
@@ -269,9 +269,9 @@ fn subcommand_sorted_display_order() {
     static SUBCMD_ALPHA_ORDER: &str = "test 1
 
 Usage:
-    test [SUBCOMMAND]
+    test [COMMAND]
 
-Subcommands:
+Commands:
     a1      blah a1
     b1      blah b1
     help    Print this message or the help of the given subcommand(s)
@@ -306,9 +306,9 @@ fn subcommand_derived_display_order() {
     static SUBCMD_DECL_ORDER: &str = "test 1
 
 Usage:
-    test [SUBCOMMAND]
+    test [COMMAND]
 
-Subcommands:
+Commands:
     b1      blah b1
     a1      blah a1
     help    Print this message or the help of the given subcommand(s)

diff --git a/tests/builder/display_order.rs b/tests/builder/display_order.rs
@@ -12,9 +12,9 @@ fn very_large_display_order() {
         "test 
 
 Usage:
-    test [SUBCOMMAND]
+    test [COMMAND]
 
-Subcommands:
+Commands:
     help    Print this message or the help of the given subcommand(s)
     sub