Merge pull request #4155 from epage/command

fix(help): Use Command in place of Subcommand

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)

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)
 

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)
 

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
 

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    

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    

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)

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)
 

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)
 

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)
 

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)
 

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"),
                 )
             };

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()

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,

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

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)

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