fix: Deprecate Command::trailing_var_arg

Now that we have it on `Arg`, we don't need it on `Command`

CHANGELOG.md

@@ -66,6 +66,7 @@ Deprecated
 - `Arg::number_of_values` in favor of `Arg::num_args`
 - `default_value_os`, `default_values_os`, `default_value_if_os`, and `default_value_ifs_os` as the non `_os` variants now accept either a `str` or an `OsStr`
 - `Command::dont_collapse_args_in_usage` is now the default and is deprecated
+- `Command::trailing_var_arg` in favor of `Arg::trailing_var_arg`
 - *(derive)* `structopt` and `clap` attributes in favor of the more specific `command`, `arg`, and `value`
 
 ### Features

clap_bench/benches/06_rustup.rs

@@ -238,9 +238,13 @@ fn build_cli() -> Command {
             Command::new("run")
                 .about("Run a command with an environment configured for a given toolchain")
                 .after_help(RUN_HELP)
-                .trailing_var_arg(true)
                 .arg(Arg::new("toolchain").required(true))
-                .arg(Arg::new("command").required(true).num_args(1..)),
+                .arg(
+                    Arg::new("command")
+                        .required(true)
+                        .num_args(1..)
+                        .trailing_var_arg(true),
+                ),
         )
         .subcommand(
             Command::new("which")

clap_complete/examples/completion-derive.rs

@@ -19,11 +19,7 @@ use std::io;
 use std::path::PathBuf;
 
 #[derive(Parser, Debug, PartialEq)]
-#[command(
-    name = "value_hints_derive",
-    // Command::trailing_var_ar is required to use ValueHint::CommandWithArguments
-    trailing_var_arg = true,
-)]
+#[command(name = "value_hints_derive")]
 struct Opt {
     /// If provided, outputs the completion file for given shell
     #[arg(long = "generate", value_enum)]
@@ -45,7 +41,8 @@ struct Opt {
     cmd_name: Option<OsString>,
     #[arg(short, long, value_hint = ValueHint::CommandString)]
     cmd: Option<String>,
-    #[arg(value_hint = ValueHint::CommandWithArguments)]
+    // Command::trailing_var_ar is required to use ValueHint::CommandWithArguments
+    #[arg(trailing_var_arg = true, value_hint = ValueHint::CommandWithArguments)]
     command_with_args: Vec<String>,
     #[arg(short, long, value_hint = ValueHint::Username)]
     user: Option<String>,

clap_complete/examples/completion.rs

@@ -18,8 +18,6 @@ use std::io;
 
 fn build_cli() -> Command {
     Command::new("value_hints")
-        // AppSettings::TrailingVarArg is required to use ValueHint::CommandWithArguments
-        .trailing_var_arg(true)
         .arg(
             Arg::new("generator")
                 .long("generate")
@@ -69,6 +67,8 @@ fn build_cli() -> Command {
         .arg(
             Arg::new("command_with_args")
                 .num_args(1..)
+                // AppSettings::TrailingVarArg is required to use ValueHint::CommandWithArguments
+                .trailing_var_arg(true)
                 .value_hint(ValueHint::CommandWithArguments),
         )
         .arg(

clap_complete/tests/common.rs

@@ -169,7 +169,6 @@ pub fn sub_subcommands_command(name: &'static str) -> clap::Command {
 
 pub fn value_hint_command(name: &'static str) -> clap::Command {
     clap::Command::new(name)
-        .trailing_var_arg(true)
         .arg(
             clap::Arg::new("choice")
                 .long("choice")
@@ -225,6 +224,7 @@ pub fn value_hint_command(name: &'static str) -> clap::Command {
             clap::Arg::new("command_with_args")
                 .action(clap::ArgAction::Set)
                 .num_args(1..)
+                .trailing_var_arg(true)
                 .value_hint(clap::ValueHint::CommandWithArguments),
         )
         .arg(

clap_complete_fig/tests/common.rs

@@ -165,7 +165,6 @@ pub fn sub_subcommands_command(name: &'static str) -> clap::Command {
 
 pub fn value_hint_command(name: &'static str) -> clap::Command {
     clap::Command::new(name)
-        .trailing_var_arg(true)
         .arg(
             clap::Arg::new("choice")
                 .long("choice")
@@ -221,6 +220,7 @@ pub fn value_hint_command(name: &'static str) -> clap::Command {
             clap::Arg::new("command_with_args")
                 .action(clap::ArgAction::Set)
                 .num_args(1..)
+                .trailing_var_arg(true)
                 .value_hint(clap::ValueHint::CommandWithArguments),
         )
         .arg(

clap_mangen/tests/common.rs

@@ -163,7 +163,6 @@ pub fn sub_subcommands_command(name: &'static str) -> clap::Command {
 
 pub fn value_hint_command(name: &'static str) -> clap::Command {
     clap::Command::new(name)
-        .trailing_var_arg(true)
         .arg(
             clap::Arg::new("choice")
                 .long("choice")
@@ -219,6 +218,7 @@ pub fn value_hint_command(name: &'static str) -> clap::Command {
             clap::Arg::new("command_with_args")
                 .action(clap::ArgAction::Set)
                 .num_args(1..)
+                .trailing_var_arg(true)
                 .value_hint(clap::ValueHint::CommandWithArguments),
         )
         .arg(
@@ -283,7 +283,6 @@ pub fn assert_matches_path(expected_path: impl AsRef<std::path::Path>, cmd: clap
 
 pub fn possible_values_command(name: &'static str) -> clap::Command {
     clap::Command::new(name)
-        .trailing_var_arg(true)
         .arg(
             clap::Arg::new("choice")
                 .long("choice")

src/builder/command.rs

@@ -2000,28 +2000,11 @@ impl Command {
         }
     }
 
-    /// Specifies that the final positional argument is a "VarArg" and that `clap` should not
-    /// attempt to parse any further args, as if the user had used a `--`.
-    ///
-    /// The values of the trailing positional argument will contain all args from itself on.
-    ///
-    /// **NOTE:** [`Arg::value_delimiter`] still applies if set.
-    ///
-    /// **NOTE:** The final positional argument **must** have [`Arg::num_args(..)`].
-    ///
-    /// # Examples
-    ///
-    /// ```rust
-    /// # use clap::{Command, arg};
-    /// let m = Command::new("myprog")
-    ///     .trailing_var_arg(true)
-    ///     .arg(arg!(<cmd> ... "commands to run"))
-    ///     .get_matches_from(vec!["myprog", "arg1", "-r", "val1"]);
-    ///
-    /// let trail: Vec<_> = m.get_many::<String>("cmd").unwrap().collect();
-    /// assert_eq!(trail, ["arg1", "-r", "val1"]);
-    /// ```
-    /// [`Arg::num_args(..)`]: crate::Arg::num_args()
+    #[doc(hidden)]
+    #[cfg_attr(
+        feature = "deprecated",
+        deprecated(since = "4.0.0", note = "Replaced with `Arg::trailing_var_arg`")
+    )]
     pub fn trailing_var_arg(self, yes: bool) -> Self {
         if yes {
             self.setting(AppSettings::TrailingVarArg)
@@ -3600,7 +3583,11 @@ impl Command {
         self.is_set(AppSettings::AllowNegativeNumbers)
     }
 
-    /// Report whether [`Command::trailing_var_arg`] is set
+    #[doc(hidden)]
+    #[cfg_attr(
+        feature = "deprecated",
+        deprecated(since = "4.0.0", note = "Replaced with `Arg::is_trailing_var_arg_set`")
+    )]
     pub fn is_trailing_var_arg_set(&self) -> bool {
         self.is_set(AppSettings::TrailingVarArg)
     }

tests/builder/app_settings.rs

@@ -336,9 +336,8 @@ fn stop_delim_values_only_pos_follows() {
 #[test]
 fn dont_delim_values_trailingvararg() {
     let m = Command::new("positional")
-        .trailing_var_arg(true)
         .dont_delimit_trailing_values(true)
-        .arg(arg!([opt] ... "some pos"))
+        .arg(arg!([opt] ... "some pos").trailing_var_arg(true))
         .try_get_matches_from(vec!["", "test", "--foo", "-Wl,-bar"])
         .unwrap();
     assert!(m.contains_id("opt"));
@@ -372,8 +371,7 @@ fn delim_values_only_pos_follows() {
 #[test]
 fn delim_values_trailingvararg() {
     let m = Command::new("positional")
-        .trailing_var_arg(true)
-        .arg(arg!([opt] ... "some pos"))
+        .arg(arg!([opt] ... "some pos").trailing_var_arg(true))
         .try_get_matches_from(vec!["", "test", "--foo", "-Wl,-bar"])
         .unwrap();
     assert!(m.contains_id("opt"));
@@ -410,8 +408,11 @@ fn delim_values_only_pos_follows_with_delim() {
 #[test]
 fn delim_values_trailingvararg_with_delim() {
     let m = Command::new("positional")
-        .trailing_var_arg(true)
-        .arg(arg!([opt] ... "some pos").value_delimiter(','))
+        .arg(
+            arg!([opt] ... "some pos")
+                .value_delimiter(',')
+                .trailing_var_arg(true),
+        )
         .try_get_matches_from(vec!["", "test", "--foo", "-Wl,-bar"])
         .unwrap();
     assert!(m.contains_id("opt"));
@@ -520,9 +521,8 @@ fn allow_negative_numbers_fail() {
 #[test]
 fn leading_double_hyphen_trailingvararg() {
     let m = Command::new("positional")
-        .trailing_var_arg(true)
         .allow_hyphen_values(true)
-        .arg(arg!([opt] ... "some pos"))
+        .arg(arg!([opt] ... "some pos").trailing_var_arg(true))
         .try_get_matches_from(vec!["", "--foo", "-Wl", "bar"])
         .unwrap();
     assert!(m.contains_id("opt"));