fix(usage): Make dont_collapse_args_in_usage the default

The setting was added to resolve clap-rs#769.  The reason it was optional is out
of concern for applications with a lot of positional arguments.  I think
those cases are rare enough that we should just push people to override
the usage.  Positional arguments are generally important enough, even if
optional, to show.

As a side effect, this fixed some bugs with
`dont_collapse_args_in_usage` where it would repeat an argument in a
smart usage.

As a side effect, smart usage now shows `--` when it should

CHANGELOG.md

@@ -61,6 +61,7 @@ MSRV is now 1.60.0
 
 Deprecated
 - `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
 
 ### Features
 
@@ -92,7 +93,8 @@ Deprecated
 - *(help)* Don't rely on ALL CAPS for help headers
 - *(help)* List subcommands first, focusing the emphasis on them
 - *(help)* Do not include global args in `cmd help help` (#4131)
-- *(help)* Use `[positional]` in argument list when relevant (#4145)
+- *(help)* Use `[positional]` in list when relevant (#4145)
+- *(help)* Show all `[positional]` in usage
 - *(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/tutorial_builder/04_03_relations.md

@@ -25,7 +25,7 @@ error: The following required arguments were not provided:
     <--set-ver <VER>|--major|--minor|--patch>
 
 Usage:
-    04_03_relations[EXE] <--set-ver <VER>|--major|--minor|--patch>
+    04_03_relations[EXE] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE]
 
 For more information try --help
 
@@ -37,7 +37,7 @@ $ 04_03_relations --major --minor
 error: The argument '--major' cannot be used with '--minor'
 
 Usage:
-    04_03_relations[EXE] <--set-ver <VER>|--major|--minor|--patch>
+    04_03_relations[EXE] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE]
 
 For more information try --help
 

examples/tutorial_derive/04_03_relations.md

@@ -25,7 +25,7 @@ error: The following required arguments were not provided:
     <--set-ver <VER>|--major|--minor|--patch>
 
 Usage:
-    04_03_relations_derive[EXE] <--set-ver <VER>|--major|--minor|--patch>
+    04_03_relations_derive[EXE] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE]
 
 For more information try --help
 
@@ -37,7 +37,7 @@ $ 04_03_relations_derive --major --minor
 error: The argument '--major' cannot be used with '--minor'
 
 Usage:
-    04_03_relations_derive[EXE] <--set-ver <VER>|--major|--minor|--patch>
+    04_03_relations_derive[EXE] <--set-ver <VER>|--major|--minor|--patch> [INPUT_FILE]
 
 For more information try --help
 

src/builder/app_settings.rs

@@ -43,7 +43,6 @@ pub(crate) enum AppSettings {
     ArgsNegateSubcommands,
     SubcommandPrecedenceOverArg,
     ArgRequiredElseHelp,
-    DontCollapseArgsInUsage,
     NextLineHelp,
     DisableColoredHelp,
     DisableHelpFlag,
@@ -86,7 +85,6 @@ bitflags! {
         const DONT_DELIM_TRAIL               = 1 << 24;
         const ALLOW_NEG_NUMS                 = 1 << 25;
         const DISABLE_HELP_SC                = 1 << 27;
-        const DONT_COLLAPSE_ARGS             = 1 << 28;
         const ARGS_NEGATE_SCS                = 1 << 29;
         const PROPAGATE_VALS_DOWN            = 1 << 30;
         const ALLOW_MISSING_POS              = 1 << 31;
@@ -130,8 +128,6 @@ impl_settings! { AppSettings, AppFlags,
         => Flags::COLOR_NEVER,
     DontDelimitTrailingValues
         => Flags::DONT_DELIM_TRAIL,
-    DontCollapseArgsInUsage
-        => Flags::DONT_COLLAPSE_ARGS,
     DisableColoredHelp
         => Flags::DISABLE_COLORED_HELP,
     DisableHelpSubcommand

src/builder/command.rs

@@ -1242,25 +1242,13 @@ impl Command {
         }
     }
 
-    /// Disables the automatic collapsing of positional args into `[ARGS]` inside the usage string.
-    ///
-    /// **NOTE:** This choice is propagated to all child subcommands.
-    ///
-    /// # Examples
-    ///
-    /// ```no_run
-    /// # use clap::{Command, Arg};
-    /// Command::new("myprog")
-    ///     .dont_collapse_args_in_usage(true)
-    ///     .get_matches();
-    /// ```
-    #[inline]
-    pub fn dont_collapse_args_in_usage(self, yes: bool) -> Self {
-        if yes {
-            self.global_setting(AppSettings::DontCollapseArgsInUsage)
-        } else {
-            self.unset_global_setting(AppSettings::DontCollapseArgsInUsage)
-        }
+    #[doc(hidden)]
+    #[cfg_attr(
+        feature = "deprecated",
+        deprecated(since = "4.0.0", note = "This is now the default")
+    )]
+    pub fn dont_collapse_args_in_usage(self, _yes: bool) -> Self {
+        self
     }
 
     /// Tells `clap` *not* to print possible values when displaying help information.
@@ -3574,9 +3562,13 @@ impl Command {
         self.is_set(AppSettings::HelpExpected)
     }
 
-    /// Report whether [`Command::dont_collapse_args_in_usage`] is set
+    #[doc(hidden)]
+    #[cfg_attr(
+        feature = "deprecated",
+        deprecated(since = "4.0.0", note = "This is now the default")
+    )]
     pub fn is_dont_collapse_args_in_usage_set(&self) -> bool {
-        self.is_set(AppSettings::DontCollapseArgsInUsage)
+        true
     }
 
     /// Report whether [`Command::infer_long_args`] is set
@@ -3808,11 +3800,6 @@ impl Command {
                 }
 
                 // Figure out implied settings
-                if a.is_last_set() {
-                    // if an arg has `Last` set, we need to imply DontCollapseArgsInUsage so that args
-                    // in the usage string don't get confused or left out.
-                    self.settings.set(AppSettings::DontCollapseArgsInUsage);
-                }
                 a._build();
                 if hide_pv && a.is_takes_value_set() {
                     a.settings.set(ArgSettings::HidePossibleValues);
@@ -4305,10 +4292,6 @@ impl Command {
         !self.args.is_empty()
     }
 
-    pub(crate) fn has_positionals(&self) -> bool {
-        self.args.keys().any(|x| x.is_position())
-    }
-
     pub(crate) fn has_visible_subcommands(&self) -> bool {
         self.subcommands
             .iter()