feat(help): Allow controlling flattening

clap_builder/src/builder/app_settings.rs

@@ -57,6 +57,7 @@ pub(crate) enum AppSettings {
     SubcommandsNegateReqs,
     ArgsNegateSubcommands,
     SubcommandPrecedenceOverArg,
+    FlattenHelp,
     ArgRequiredElseHelp,
     NextLineHelp,
     DisableColoredHelp,

clap_builder/src/builder/command.rs

@@ -2049,6 +2049,21 @@ impl Command {
         self
     }
 
+    /// Flatten subcommand help into the current command's help
+    ///
+    /// This shows a summary of subcommands within the usage and help for the current command, similar to
+    /// `git stash --help` showing information on `push`, `pop`, etc.
+    /// To see more information, a user can still pass `--help` to the individual subcommands.
+    #[inline]
+    #[must_use]
+    pub fn flatten_help(self, yes: bool) -> Self {
+        if yes {
+            self.setting(AppSettings::FlattenHelp)
+        } else {
+            self.unset_setting(AppSettings::FlattenHelp)
+        }
+    }
+
     /// Set the default section heading for future args.
     ///
     /// This will be used for any arg that hasn't had [`Arg::help_heading`] called.
@@ -3430,6 +3445,12 @@ impl Command {
         self.long_about.as_ref()
     }
 
+    /// Get the custom section heading specified via [`Command::flatten_help`].
+    #[inline]
+    pub fn is_flatten_help_set(&self) -> bool {
+        self.is_set(AppSettings::FlattenHelp)
+    }
+
     /// Get the custom section heading specified via [`Command::next_help_heading`].
     ///
     /// [`Command::help_heading`]: Command::help_heading()

examples/git-derive.rs

@@ -76,6 +76,7 @@ impl std::fmt::Display for ColorWhen {
 
 #[derive(Debug, Args)]
 #[command(args_conflicts_with_subcommands = true)]
+#[command(flatten_help = true)]
 struct StashArgs {
     #[command(subcommand)]
     command: Option<StashCommands>,

examples/git.rs

@@ -45,6 +45,7 @@ fn cli() -> Command {
         .subcommand(
             Command::new("stash")
                 .args_conflicts_with_subcommands(true)
+                .flatten_help(true)
                 .args(push_args())
                 .subcommand(Command::new("push").args(push_args()))
                 .subcommand(Command::new("pop").arg(arg!([STASH])))