Skip to content

Commit

Permalink
fix(help): Use Command in place of Subcommand
Browse files Browse the repository at this point in the history
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
  • Loading branch information
epage committed Aug 31, 2022
1 parent c2f9ecd commit 42c9438
Show file tree
Hide file tree
Showing 26 changed files with 110 additions and 108 deletions.
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down
4 changes: 2 additions & 2 deletions examples/cargo-example-derive.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
4 changes: 2 additions & 2 deletions examples/cargo-example.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
8 changes: 4 additions & 4 deletions examples/derive_ref/interop_tests.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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)
Expand Down Expand Up @@ -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

Expand Down
12 changes: 6 additions & 6 deletions examples/git-derive.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
12 changes: 6 additions & 6 deletions examples/git.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -80,9 +80,9 @@ git-stash

Usage:
git[EXE] stash [OPTIONS]
git[EXE] stash <SUBCOMMAND>
git[EXE] stash <COMMAND>

Subcommands:
Commands:
push
pop
apply
Expand Down
4 changes: 2 additions & 2 deletions examples/pacman.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
4 changes: 2 additions & 2 deletions examples/tutorial_builder/01_quick.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
8 changes: 4 additions & 4 deletions examples/tutorial_builder/03_04_subcommands.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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)

Expand Down
4 changes: 2 additions & 2 deletions examples/tutorial_derive/01_quick.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
8 changes: 4 additions & 4 deletions examples/tutorial_derive/03_04_subcommands.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down Expand Up @@ -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)

Expand Down
20 changes: 10 additions & 10 deletions src/builder/command.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2588,7 +2588,7 @@ impl Command {
/// Usage:
/// cust-ord [OPTIONS]
///
/// Subcommands:
/// Commands:
/// beta I should be first!
/// alpha Some help and text
///
Expand Down Expand Up @@ -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`]
///
Expand All @@ -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
///
Expand Down Expand Up @@ -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
/// ```
Expand All @@ -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`]
///
Expand All @@ -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
/// ```
Expand All @@ -3148,7 +3148,7 @@ impl Command {
/// myprog
///
/// Usage:
/// myprog [SUBCOMMAND]
/// myprog [COMMAND]
///
/// Options:
/// -h, --help Print help information
Expand Down Expand Up @@ -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"),
)
};
Expand Down
2 changes: 1 addition & 1 deletion src/output/help.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
2 changes: 1 addition & 1 deletion src/output/usage.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion tests/builder/app_settings.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions tests/builder/derive_order.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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)
Expand Down
4 changes: 2 additions & 2 deletions tests/builder/display_order.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading

0 comments on commit 42c9438

Please sign in to comment.