Auto merge of #12841 - epage:help, r=weihanglo

fix(help):Clarify install's positional ### What does this PR try to resolve? - That a version is accepted - That you are selecting from the source a package which led to part of the confusion in #4830 I wonder if we should rename our `CRATE` value names to `PKG`/`PACKAGE` While doing this, I decided to fix the inconsistency in how we handle value names in help. ### How should we test and review this PR? ### Additional information
rust-lang · Oct 18, 2023 · 1416678 · 1416678
2 parents 16629e6 + 5f05969
commit 1416678
Show file tree

Hide file tree

Showing 34 changed files with 69 additions and 46 deletions.
diff --git a/src/bin/cargo/commands/bench.rs b/src/bin/cargo/commands/bench.rs
@@ -12,6 +12,7 @@ pub fn cli() -> Command {
         )
         .arg(
             Arg::new("args")
+                .value_name("ARGS")
                 .help("Arguments for the bench binary")
                 .num_args(0..)
                 .last(true),

diff --git a/src/bin/cargo/commands/init.rs b/src/bin/cargo/commands/init.rs
@@ -5,7 +5,12 @@ use cargo::ops;
 pub fn cli() -> Command {
     subcommand("init")
         .about("Create a new cargo package in an existing directory")
-        .arg(Arg::new("path").action(ArgAction::Set).default_value("."))
+        .arg(
+            Arg::new("path")
+                .value_name("PATH")
+                .action(ArgAction::Set)
+                .default_value("."),
+        )
         .arg_new_opts()
         .arg_registry("Registry to use")
         .arg_quiet()

diff --git a/src/bin/cargo/commands/install.rs b/src/bin/cargo/commands/install.rs
@@ -16,7 +16,13 @@ use cargo_util::paths;
 pub fn cli() -> Command {
     subcommand("install")
         .about("Install a Rust binary. Default location is $HOME/.cargo/bin")
-        .arg(Arg::new("crate").value_parser(parse_crate).num_args(0..))
+        .arg(
+            Arg::new("crate")
+                .value_name("CRATE[@<VER>]")
+                .help("Select the package from the given source")
+                .value_parser(parse_crate)
+                .num_args(0..),
+        )
         .arg(
             opt("version", "Specify a version to install")
                 .alias("vers")

diff --git a/src/bin/cargo/commands/login.rs b/src/bin/cargo/commands/login.rs
@@ -6,7 +6,7 @@ use crate::command_prelude::*;
 pub fn cli() -> Command {
     subcommand("login")
         .about("Log in to a registry.")
-        .arg(Arg::new("token").action(ArgAction::Set))
+        .arg(Arg::new("token").value_name("TOKEN").action(ArgAction::Set))
         .arg_registry("Registry to use")
         .arg(
             Arg::new("args")

diff --git a/src/bin/cargo/commands/new.rs b/src/bin/cargo/commands/new.rs
@@ -5,7 +5,12 @@ use cargo::ops;
 pub fn cli() -> Command {
     subcommand("new")
         .about("Create a new cargo package at <path>")
-        .arg(Arg::new("path").action(ArgAction::Set).required(true))
+        .arg(
+            Arg::new("path")
+                .value_name("PATH")
+                .action(ArgAction::Set)
+                .required(true),
+        )
         .arg_new_opts()
         .arg_registry("Registry to use")
         .arg_quiet()

diff --git a/src/bin/cargo/commands/owner.rs b/src/bin/cargo/commands/owner.rs
@@ -6,7 +6,7 @@ use cargo_credential::Secret;
 pub fn cli() -> Command {
     subcommand("owner")
         .about("Manage the owners of a crate on the registry")
-        .arg(Arg::new("crate").action(ArgAction::Set))
+        .arg(Arg::new("crate").value_name("CRATE").action(ArgAction::Set))
         .arg(
             multi_opt(
                 "add",

diff --git a/src/bin/cargo/commands/pkgid.rs b/src/bin/cargo/commands/pkgid.rs
@@ -6,7 +6,7 @@ use cargo::util::print_available_packages;
 pub fn cli() -> Command {
     subcommand("pkgid")
         .about("Print a fully qualified package specification")
-        .arg(Arg::new("spec").action(ArgAction::Set))
+        .arg(Arg::new("spec").value_name("SPEC").action(ArgAction::Set))
         .arg_quiet()
         .arg_package("Argument to get the package ID specifier for")
         .arg_manifest_path()

diff --git a/src/bin/cargo/commands/run.rs b/src/bin/cargo/commands/run.rs
@@ -16,6 +16,7 @@ pub fn cli() -> Command {
         .about("Run a binary or example of the local package")
         .arg(
             Arg::new("args")
+                .value_name("ARGS")
                 .help("Arguments for the binary or example to run")
                 .value_parser(value_parser!(OsString))
                 .num_args(0..)

diff --git a/src/bin/cargo/commands/rustc.rs b/src/bin/cargo/commands/rustc.rs
@@ -10,6 +10,7 @@ pub fn cli() -> Command {
         .about("Compile a package, and pass extra options to the compiler")
         .arg(
             Arg::new("args")
+                .value_name("ARGS")
                 .num_args(0..)
                 .help("Extra rustc flags")
                 .trailing_var_arg(true),

diff --git a/src/bin/cargo/commands/rustdoc.rs b/src/bin/cargo/commands/rustdoc.rs
@@ -7,6 +7,7 @@ pub fn cli() -> Command {
         .about("Build a package's documentation, using specified custom flags.")
         .arg(
             Arg::new("args")
+                .value_name("ARGS")
                 .help("Extra rustdoc flags")
                 .num_args(0..)
                 .trailing_var_arg(true),

diff --git a/src/bin/cargo/commands/search.rs b/src/bin/cargo/commands/search.rs
@@ -7,7 +7,7 @@ use cargo::ops;
 pub fn cli() -> Command {
     subcommand("search")
         .about("Search packages in crates.io")
-        .arg(Arg::new("query").num_args(0..))
+        .arg(Arg::new("query").value_name("QUERY").num_args(0..))
         .arg(
             opt(
                 "limit",

diff --git a/src/bin/cargo/commands/test.rs b/src/bin/cargo/commands/test.rs
@@ -13,6 +13,7 @@ pub fn cli() -> Command {
         )
         .arg(
             Arg::new("args")
+                .value_name("ARGS")
                 .help("Arguments for the test binary")
                 .num_args(0..)
                 .last(true),

diff --git a/src/bin/cargo/commands/uninstall.rs b/src/bin/cargo/commands/uninstall.rs
@@ -5,7 +5,7 @@ use cargo::ops;
 pub fn cli() -> Command {
     subcommand("uninstall")
         .about("Remove a Rust binary")
-        .arg(Arg::new("spec").num_args(0..))
+        .arg(Arg::new("spec").value_name("SPEC").num_args(0..))
         .arg(opt("root", "Directory to uninstall packages from").value_name("DIR"))
         .arg_quiet()
         .arg_package_spec_simple("Package to uninstall")

diff --git a/src/bin/cargo/commands/yank.rs b/src/bin/cargo/commands/yank.rs
@@ -6,7 +6,7 @@ use cargo_credential::Secret;
 pub fn cli() -> Command {
     subcommand("yank")
         .about("Remove a pushed crate from the index")
-        .arg(Arg::new("crate").action(ArgAction::Set))
+        .arg(Arg::new("crate").value_name("CRATE").action(ArgAction::Set))
         .arg(
             opt("version", "The version to yank or un-yank")
                 .alias("vers")

diff --git a/tests/testsuite/cargo_bench/help/stdout.log b/tests/testsuite/cargo_bench/help/stdout.log
@@ -1,10 +1,10 @@
 Execute all benchmarks of a local package
 
-Usage: cargo[EXE] bench [OPTIONS] [BENCHNAME] [-- [args]...]
+Usage: cargo[EXE] bench [OPTIONS] [BENCHNAME] [-- [ARGS]...]
 
 Arguments:
   [BENCHNAME]  If specified, only run benches containing this string in their names
-  [args]...    Arguments for the bench binary
+  [ARGS]...    Arguments for the bench binary
 
 Options:
       --no-run                Compile, but don't run benchmarks

diff --git a/tests/testsuite/cargo_bench/no_keep_going/stderr.log b/tests/testsuite/cargo_bench/no_keep_going/stderr.log
@@ -2,6 +2,6 @@ error: unexpected argument '--keep-going' found
 
   tip: use `--no-fail-fast` to run as many tests as possible regardless of failure
 
-Usage: cargo[EXE] bench [OPTIONS] [BENCHNAME] [-- [args]...]
+Usage: cargo[EXE] bench [OPTIONS] [BENCHNAME] [-- [ARGS]...]
 
 For more information, try '--help'.
diff --git a/tests/testsuite/cargo_init/help/stdout.log b/tests/testsuite/cargo_init/help/stdout.log
@@ -1,9 +1,9 @@
 Create a new cargo package in an existing directory
 
-Usage: cargo[EXE] init [OPTIONS] [path]
+Usage: cargo[EXE] init [OPTIONS] [PATH]
 
 Arguments:
-  [path]  [default: .]
+  [PATH]  [default: .]
 
 Options:
       --vcs <VCS>            Initialize a new repository for the given version control system,

diff --git a/tests/testsuite/cargo_init/unknown_flags/stderr.log b/tests/testsuite/cargo_init/unknown_flags/stderr.log
@@ -2,6 +2,6 @@ error: unexpected argument '--flag' found
 
   tip: to pass '--flag' as a value, use '-- --flag'
 
-Usage: cargo[EXE] init <path>
+Usage: cargo[EXE] init <PATH>
 
 For more information, try '--help'.
diff --git a/tests/testsuite/cargo_install/help/stdout.log b/tests/testsuite/cargo_install/help/stdout.log
@@ -1,9 +1,9 @@
 Install a Rust binary. Default location is $HOME/.cargo/bin
 
-Usage: cargo[EXE] install [OPTIONS] [crate]...
+Usage: cargo[EXE] install [OPTIONS] [CRATE[@<VER>]]...
 
 Arguments:
-  [crate]...  
+  [CRATE[@<VER>]]...  Select the package from the given source
 
 Options:
       --version <VERSION>     Specify a version to install

diff --git a/tests/testsuite/cargo_login/help/stdout.log b/tests/testsuite/cargo_login/help/stdout.log
@@ -1,9 +1,9 @@
 Log in to a registry.
 
-Usage: cargo[EXE] login [OPTIONS] [token] [-- [args]...]
+Usage: cargo[EXE] login [OPTIONS] [TOKEN] [-- [args]...]
 
 Arguments:
-  [token]    
+  [TOKEN]    
   [args]...  Additional arguments for the credential provider
 
 Options:

diff --git a/tests/testsuite/cargo_new/help/stdout.log b/tests/testsuite/cargo_new/help/stdout.log
@@ -1,9 +1,9 @@
 Create a new cargo package at <path>
 
-Usage: cargo[EXE] new [OPTIONS] <path>
+Usage: cargo[EXE] new [OPTIONS] <PATH>
 
 Arguments:
-  <path>  
+  <PATH>  
 
 Options:
       --vcs <VCS>            Initialize a new repository for the given version control system,

diff --git a/tests/testsuite/cargo_owner/help/stdout.log b/tests/testsuite/cargo_owner/help/stdout.log
@@ -1,9 +1,9 @@
 Manage the owners of a crate on the registry
 
-Usage: cargo[EXE] owner [OPTIONS] [crate]
+Usage: cargo[EXE] owner [OPTIONS] [CRATE]
 
 Arguments:
-  [crate]  
+  [CRATE]  
 
 Options:
   -a, --add <LOGIN>          Name of a user or team to invite as an owner

diff --git a/tests/testsuite/cargo_pkgid/help/stdout.log b/tests/testsuite/cargo_pkgid/help/stdout.log
@@ -1,9 +1,9 @@
 Print a fully qualified package specification
 
-Usage: cargo[EXE] pkgid [OPTIONS] [spec]
+Usage: cargo[EXE] pkgid [OPTIONS] [SPEC]
 
 Arguments:
-  [spec]  
+  [SPEC]  
 
 Options:
   -q, --quiet               Do not print cargo log messages

diff --git a/tests/testsuite/cargo_run/help/stdout.log b/tests/testsuite/cargo_run/help/stdout.log
@@ -1,9 +1,9 @@
 Run a binary or example of the local package
 
-Usage: cargo[EXE] run [OPTIONS] [args]...
+Usage: cargo[EXE] run [OPTIONS] [ARGS]...
 
 Arguments:
-  [args]...  Arguments for the binary or example to run
+  [ARGS]...  Arguments for the binary or example to run
 
 Options:
       --ignore-rust-version   Ignore `rust-version` specification in packages

diff --git a/tests/testsuite/cargo_rustc/help/stdout.log b/tests/testsuite/cargo_rustc/help/stdout.log
@@ -1,9 +1,9 @@
 Compile a package, and pass extra options to the compiler
 
-Usage: cargo[EXE] rustc [OPTIONS] [args]...
+Usage: cargo[EXE] rustc [OPTIONS] [ARGS]...
 
 Arguments:
-  [args]...  Extra rustc flags
+  [ARGS]...  Extra rustc flags
 
 Options:
       --print <INFO>             Output compiler information without compiling

diff --git a/tests/testsuite/cargo_rustdoc/help/stdout.log b/tests/testsuite/cargo_rustdoc/help/stdout.log
@@ -1,9 +1,9 @@
 Build a package's documentation, using specified custom flags.
 
-Usage: cargo[EXE] rustdoc [OPTIONS] [args]...
+Usage: cargo[EXE] rustdoc [OPTIONS] [ARGS]...
 
 Arguments:
-  [args]...  Extra rustdoc flags
+  [ARGS]...  Extra rustdoc flags
 
 Options:
       --open                  Opens the docs in a browser after the operation

diff --git a/tests/testsuite/cargo_search/help/stdout.log b/tests/testsuite/cargo_search/help/stdout.log
@@ -1,9 +1,9 @@
 Search packages in crates.io
 
-Usage: cargo[EXE] search [OPTIONS] [query]...
+Usage: cargo[EXE] search [OPTIONS] [QUERY]...
 
 Arguments:
-  [query]...  
+  [QUERY]...  
 
 Options:
       --limit <LIMIT>        Limit the number of results (default: 10, max: 100)

diff --git a/tests/testsuite/cargo_test/help/stdout.log b/tests/testsuite/cargo_test/help/stdout.log
@@ -1,10 +1,10 @@
 Execute all unit and integration tests and build examples of a local package
 
-Usage: cargo[EXE] test [OPTIONS] [TESTNAME] [-- [args]...]
+Usage: cargo[EXE] test [OPTIONS] [TESTNAME] [-- [ARGS]...]
 
 Arguments:
   [TESTNAME]  If specified, only run tests containing this string in their names
-  [args]...   Arguments for the test binary
+  [ARGS]...   Arguments for the test binary
 
 Options:
       --doc                     Test only this library's documentation

diff --git a/tests/testsuite/cargo_test/no_keep_going/stderr.log b/tests/testsuite/cargo_test/no_keep_going/stderr.log
@@ -2,6 +2,6 @@ error: unexpected argument '--keep-going' found
 
   tip: use `--no-fail-fast` to run as many tests as possible regardless of failure
 
-Usage: cargo[EXE] test [OPTIONS] [TESTNAME] [-- [args]...]
+Usage: cargo[EXE] test [OPTIONS] [TESTNAME] [-- [ARGS]...]
 
 For more information, try '--help'.
diff --git a/tests/testsuite/cargo_uninstall/help/stdout.log b/tests/testsuite/cargo_uninstall/help/stdout.log
@@ -1,9 +1,9 @@
 Remove a Rust binary
 
-Usage: cargo[EXE] uninstall [OPTIONS] [spec]...
+Usage: cargo[EXE] uninstall [OPTIONS] [SPEC]...
 
 Arguments:
-  [spec]...  
+  [SPEC]...  
 
 Options:
       --root <DIR>          Directory to uninstall packages from

diff --git a/tests/testsuite/cargo_yank/help/stdout.log b/tests/testsuite/cargo_yank/help/stdout.log
@@ -1,9 +1,9 @@
 Remove a pushed crate from the index
 
-Usage: cargo[EXE] yank [OPTIONS] [crate]
+Usage: cargo[EXE] yank [OPTIONS] [CRATE]
 
 Arguments:
-  [crate]  
+  [CRATE]  
 
 Options:
       --version <VERSION>    The version to yank or un-yank

diff --git a/tests/testsuite/install.rs b/tests/testsuite/install.rs
@@ -1614,7 +1614,7 @@ fn inline_version_without_name() {
     cargo_process("install @0.1.1")
         .with_status(1)
         .with_stderr(
-            "error: invalid value '@0.1.1' for '[crate]...': missing crate name before '@'
+            "error: invalid value '@0.1.1' for '[CRATE[@<VER>]]...': missing crate name before '@'
 
 For more information, try '--help'.
 ",
@@ -1844,7 +1844,9 @@ fn install_empty_argument() {
     cargo_process("install")
         .arg("")
         .with_status(1)
-        .with_stderr_contains("[ERROR] invalid value '' for '[crate]...': crate name is empty")
+        .with_stderr_contains(
+            "[ERROR] invalid value '' for '[CRATE[@<VER>]]...': crate name is empty",
+        )
         .run();
 }
 
@@ -2455,7 +2457,7 @@ error: unexpected argument '--release' found
 
   tip: `--release` is the default for `cargo install`; instead `--debug` is supported
 
-Usage: cargo[EXE] install [OPTIONS] [crate]...
+Usage: cargo[EXE] install [OPTIONS] [CRATE[@<VER>]]...
 
 For more information, try '--help'.
 ",

diff --git a/tests/testsuite/new.rs b/tests/testsuite/new.rs
@@ -124,7 +124,7 @@ fn no_argument() {
         .with_stderr_contains(
             "\
 error: the following required arguments were not provided:
-  <path>
+  <PATH>
 ",
         )
         .run();

diff --git a/tests/testsuite/run.rs b/tests/testsuite/run.rs
@@ -50,7 +50,7 @@ error: unexpected argument '--silent' found
 
   tip: a similar argument exists: '--quiet'
 
-Usage: cargo[EXE] run [OPTIONS] [args]...
+Usage: cargo[EXE] run [OPTIONS] [ARGS]...
 
 For more information, try '--help'.
 ",
@@ -65,7 +65,7 @@ error: unexpected argument '--silent' found
 
   tip: a similar argument exists: '--quiet'
 
-Usage: cargo[EXE] run [OPTIONS] [args]...
+Usage: cargo[EXE] run [OPTIONS] [ARGS]...
 
 For more information, try '--help'.
 ",
-Original file line number
+Diff line change
@@ Expand Up / @@ -124,7 +124,7 @@ fn no_argument() { @@
             .with_stderr_contains(
                 "\
     error: the following required arguments were not provided:
-      <path>
+      <PATH>
     ",
             )
             .run();
@@ Expand Down @@