Merge pull request #5206 from epage/flatten

feat(help): Opt-in to flatten subcommands into parent command help

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()

clap_builder/src/output/help_template.rs

@@ -393,9 +393,11 @@ impl<'cmd, 'writer> HelpTemplate<'cmd, 'writer> {
             .filter_map(|arg| arg.get_help_heading())
             .collect::<FlatSet<_>>();
 
+        let flatten = self.cmd.is_flatten_help_set();
+
         let mut first = true;
 
-        if subcmds {
+        if subcmds && !flatten {
             if !first {
                 self.writer.push_str("\n\n");
             }
@@ -474,6 +476,11 @@ impl<'cmd, 'writer> HelpTemplate<'cmd, 'writer> {
                 }
             }
         }
+        if flatten {
+            let mut cmd = self.cmd.clone();
+            cmd.build();
+            self.write_flat_subcommands(&cmd, &mut first);
+        }
     }
 
     /// Sorts arguments by length and display order and write their help to the wrapped stream.
@@ -873,6 +880,70 @@ impl<'cmd, 'writer> HelpTemplate<'cmd, 'writer> {
 
 /// Subcommand handling
 impl<'cmd, 'writer> HelpTemplate<'cmd, 'writer> {
+    /// Writes help for subcommands of a Parser Object to the wrapped stream.
+    fn write_flat_subcommands(&mut self, cmd: &Command, first: &mut bool) {
+        debug!(
+            "HelpTemplate::write_flat_subcommands, cmd={}, first={}",
+            cmd.get_name(),
+            *first
+        );
+        use std::fmt::Write as _;
+        let header = &self.styles.get_header();
+
+        let mut ord_v = Vec::new();
+        for subcommand in cmd
+            .get_subcommands()
+            .filter(|subcommand| should_show_subcommand(subcommand))
+        {
+            ord_v.push((
+                subcommand.get_display_order(),
+                subcommand.get_name(),
+                subcommand,
+            ));
+        }
+        ord_v.sort_by(|a, b| (a.0, &a.1).cmp(&(b.0, &b.1)));
+        for (_, _, subcommand) in ord_v {
+            if !*first {
+                self.writer.push_str("\n\n");
+            }
+            *first = false;
+
+            let heading = subcommand.get_usage_name_fallback();
+            let about = cmd
+                .get_about()
+                .or_else(|| cmd.get_long_about())
+                .unwrap_or_default();
+
+            let _ = write!(
+                self.writer,
+                "{}{heading}:{}\n",
+                header.render(),
+                header.render_reset()
+            );
+            if !about.is_empty() {
+                let _ = write!(self.writer, "{about}\n",);
+            }
+
+            let mut sub_help = HelpTemplate {
+                writer: self.writer,
+                cmd: subcommand,
+                styles: self.styles,
+                usage: self.usage,
+                next_line_help: self.next_line_help,
+                term_w: self.term_w,
+                use_long: self.use_long,
+            };
+            let args = subcommand
+                .get_arguments()
+                .filter(|arg| should_show_arg(self.use_long, arg) && !arg.is_global_set())
+                .collect::<Vec<_>>();
+            sub_help.write_args(&args, heading, option_sort_key);
+            if subcommand.is_flatten_help_set() {
+                sub_help.write_flat_subcommands(subcommand, first);
+            }
+        }
+    }
+
     /// Writes help for subcommands of a Parser Object to the wrapped stream.
     fn write_subcommands(&mut self, cmd: &Command) {
         debug!("HelpTemplate::write_subcommands");

clap_builder/src/output/usage.rs

@@ -101,9 +101,29 @@ impl<'cmd> Usage<'cmd> {
     // Creates a usage string for display in help messages (i.e. not for errors)
     fn write_help_usage(&self, styled: &mut StyledStr) {
         debug!("Usage::write_help_usage");
+        use std::fmt::Write;
 
-        self.write_arg_usage(styled, &[], true);
-        self.write_subcommand_usage(styled);
+        if self.cmd.is_flatten_help_set() {
+            if !self.cmd.is_subcommand_required_set()
+                || self.cmd.is_args_conflicts_with_subcommands_set()
+            {
+                self.write_arg_usage(styled, &[], true);
+                styled.trim_end();
+                let _ = write!(styled, "{}", USAGE_SEP);
+            }
+            let mut cmd = self.cmd.clone();
+            cmd.build();
+            for (i, sub) in cmd.get_subcommands().enumerate() {
+                if i != 0 {
+                    styled.trim_end();
+                    let _ = write!(styled, "{}", USAGE_SEP);
+                }
+                Usage::new(sub).write_usage_no_title(styled, &[]);
+            }
+        } else {
+            self.write_arg_usage(styled, &[], true);
+            self.write_subcommand_usage(styled);
+        }
     }
 
     // Creates a context aware usage string, or "smart usage" from currently used

examples/git-derive.md

@@ -73,18 +73,30 @@ Default subcommand:
 ```console
 $ git-derive stash -h
 Usage: git-derive[EXE] stash [OPTIONS]
-       git-derive[EXE] stash <COMMAND>
-
-Commands:
-  push   
-  pop    
-  apply  
-  help   Print this message or the help of the given subcommand(s)
+       git-derive[EXE] stash push [OPTIONS]
+       git-derive[EXE] stash pop [STASH]
+       git-derive[EXE] stash apply [STASH]
+       git-derive[EXE] stash help [COMMAND]...
 
 Options:
   -m, --message <MESSAGE>  
   -h, --help               Print help
 
+git-derive[EXE] stash push:
+  -m, --message <MESSAGE>  
+  -h, --help               Print help
+
+git-derive[EXE] stash pop:
+  -h, --help   Print help
+  [STASH]  
+
+git-derive[EXE] stash apply:
+  -h, --help   Print help
+  [STASH]  
+
+git-derive[EXE] stash help:
+  [COMMAND]...  Print help for the subcommand(s)
+
 $ git-derive stash push -h
 Usage: git-derive[EXE] stash push [OPTIONS]
 

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.md

@@ -71,18 +71,30 @@ Default subcommand:
 ```console
 $ git stash -h
 Usage: git[EXE] stash [OPTIONS]
-       git[EXE] stash <COMMAND>
-
-Commands:
-  push   
-  pop    
-  apply  
-  help   Print this message or the help of the given subcommand(s)
+       git[EXE] stash push [OPTIONS]
+       git[EXE] stash pop [STASH]
+       git[EXE] stash apply [STASH]
+       git[EXE] stash help [COMMAND]...
 
 Options:
   -m, --message <MESSAGE>  
   -h, --help               Print help
 
+git[EXE] stash push:
+  -m, --message <MESSAGE>  
+  -h, --help               Print help
+
+git[EXE] stash pop:
+  -h, --help   Print help
+  [STASH]  
+
+git[EXE] stash apply:
+  -h, --help   Print help
+  [STASH]  
+
+git[EXE] stash help:
+  [COMMAND]...  Print help for the subcommand(s)
+
 $ git stash push -h
 Usage: git[EXE] stash push [OPTIONS]
 

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])))

tests/builder/help.rs

@@ -2948,3 +2948,505 @@ fn display_name_subcommand_explicit() {
         Some("child.display")
     );
 }
+
+#[test]
+fn flatten_basic() {
+    static EXPECTED: &str = "\
+Usage: parent [OPTIONS]
+       parent test [OPTIONS]
+       parent help [COMMAND]...
+
+Options:
+      --parent <parent>  
+  -h, --help             Print help
+
+parent test:
+      --child <child>  
+  -h, --help           Print help
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
+";
+    let cmd = Command::new("parent")
+        .flatten_help(true)
+        .arg(Arg::new("parent").long("parent"))
+        .subcommand(
+            Command::new("test")
+                .about("some")
+                .arg(Arg::new("child").long("child")),
+        );
+    utils::assert_output(cmd, "parent -h", EXPECTED, false);
+}
+
+#[test]
+fn flatten_short_help() {
+    static EXPECTED: &str = "\
+Usage: parent [OPTIONS]
+       parent test [OPTIONS]
+       parent help [COMMAND]...
+
+Options:
+      --parent <parent>  foo
+  -h, --help             Print help (see more with '--help')
+
+parent test:
+      --child <child>  foo
+  -h, --help           Print help (see more with '--help')
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
+";
+    let cmd = Command::new("parent")
+        .flatten_help(true)
+        .arg(
+            Arg::new("parent")
+                .long("parent")
+                .help("foo")
+                .long_help("bar"),
+        )
+        .subcommand(
+            Command::new("test")
+                .about("some")
+                .long_about("long some")
+                .arg(Arg::new("child").long("child").help("foo").long_help("bar")),
+        );
+    utils::assert_output(cmd, "parent -h", EXPECTED, false);
+}
+
+#[test]
+fn flatten_long_help() {
+    static EXPECTED: &str = "\
+Usage: parent [OPTIONS]
+       parent test [OPTIONS]
+       parent help [COMMAND]...
+
+Options:
+      --parent <parent>
+          bar
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+parent test:
+      --child <child>
+          bar
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+parent help:
+  [COMMAND]...
+          Print help for the subcommand(s)
+";
+    let cmd = Command::new("parent")
+        .flatten_help(true)
+        .arg(
+            Arg::new("parent")
+                .long("parent")
+                .help("foo")
+                .long_help("bar"),
+        )
+        .subcommand(
+            Command::new("test")
+                .about("some")
+                .long_about("long some")
+                .arg(Arg::new("child").long("child").help("foo").long_help("bar")),
+        );
+    utils::assert_output(cmd, "parent --help", EXPECTED, false);
+}
+
+#[test]
+fn flatten_help_cmd() {
+    static EXPECTED: &str = "\
+Usage: parent [OPTIONS]
+       parent test [OPTIONS]
+       parent help [COMMAND]...
+
+Options:
+      --parent <parent>
+          bar
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+parent test:
+      --child <child>
+          bar
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+parent help:
+  [COMMAND]...
+          Print help for the subcommand(s)
+";
+    let cmd = Command::new("parent")
+        .flatten_help(true)
+        .arg(
+            Arg::new("parent")
+                .long("parent")
+                .help("foo")
+                .long_help("bar"),
+        )
+        .subcommand(
+            Command::new("test")
+                .about("some")
+                .long_about("long some")
+                .arg(Arg::new("child").long("child").help("foo").long_help("bar")),
+        );
+    utils::assert_output(cmd, "parent help", EXPECTED, false);
+}
+
+#[test]
+fn flatten_with_global() {
+    static EXPECTED: &str = "\
+Usage: parent [OPTIONS]
+       parent test [OPTIONS]
+       parent help [COMMAND]...
+
+Options:
+      --parent <parent>  
+  -h, --help             Print help
+
+parent test:
+      --child <child>  
+  -h, --help           Print help
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
+";
+    let cmd = Command::new("parent")
+        .flatten_help(true)
+        .arg(Arg::new("parent").long("parent").global(true))
+        .subcommand(
+            Command::new("test")
+                .about("some")
+                .arg(Arg::new("child").long("child")),
+        );
+    utils::assert_output(cmd, "parent -h", EXPECTED, false);
+}
+
+#[test]
+fn flatten_arg_required() {
+    static EXPECTED: &str = "\
+Usage: parent --parent <parent>
+       parent --parent <parent> test --child <child>
+       parent --parent <parent> help [COMMAND]...
+
+Options:
+      --parent <parent>  
+  -h, --help             Print help
+
+parent --parent <parent> test:
+      --child <child>  
+  -h, --help           Print help
+
+parent --parent <parent> help:
+  [COMMAND]...  Print help for the subcommand(s)
+";
+    let cmd = Command::new("parent")
+        .flatten_help(true)
+        .arg(Arg::new("parent").long("parent").required(true))
+        .subcommand(
+            Command::new("test")
+                .about("some")
+                .arg(Arg::new("child").long("child").required(true)),
+        );
+    utils::assert_output(cmd, "parent -h", EXPECTED, false);
+}
+
+#[test]
+fn flatten_with_external_subcommand() {
+    static EXPECTED: &str = "\
+Usage: parent [OPTIONS]
+       parent test [OPTIONS]
+       parent help [COMMAND]...
+
+Options:
+      --parent <parent>  
+  -h, --help             Print help
+
+parent test:
+      --child <child>  
+  -h, --help           Print help
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
+";
+    let cmd = Command::new("parent")
+        .flatten_help(true)
+        .allow_external_subcommands(true)
+        .arg(Arg::new("parent").long("parent"))
+        .subcommand(
+            Command::new("test")
+                .about("some")
+                .arg(Arg::new("child").long("child")),
+        );
+    utils::assert_output(cmd, "parent -h", EXPECTED, false);
+}
+
+#[test]
+fn flatten_without_subcommands() {
+    static EXPECTED: &str = "\
+Usage: parent [OPTIONS]
+
+Options:
+      --parent <parent>  
+  -h, --help             Print help
+";
+    let cmd = Command::new("parent")
+        .flatten_help(true)
+        .arg(Arg::new("parent").long("parent"));
+    utils::assert_output(cmd, "parent -h", EXPECTED, false);
+}
+
+#[test]
+fn flatten_with_subcommand_required() {
+    static EXPECTED: &str = "\
+Usage: parent test [OPTIONS]
+       parent help [COMMAND]...
+
+Options:
+      --parent <parent>  
+  -h, --help             Print help
+
+parent test:
+      --child <child>  
+  -h, --help           Print help
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
+";
+    let cmd = Command::new("parent")
+        .flatten_help(true)
+        .subcommand_required(true)
+        .arg(Arg::new("parent").long("parent"))
+        .subcommand(
+            Command::new("test")
+                .about("some")
+                .arg(Arg::new("child").long("child")),
+        );
+    utils::assert_output(cmd, "parent -h", EXPECTED, false);
+}
+
+#[test]
+fn flatten_with_args_conflicts_with_subcommands() {
+    static EXPECTED: &str = "\
+Usage: parent [OPTIONS]
+       parent test [OPTIONS]
+       parent help [COMMAND]...
+
+Options:
+      --parent <parent>  
+  -h, --help             Print help
+
+parent test:
+      --child <child>  
+  -h, --help           Print help
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
+";
+    let cmd = Command::new("parent")
+        .flatten_help(true)
+        .subcommand_required(true)
+        .args_conflicts_with_subcommands(true)
+        .arg(Arg::new("parent").long("parent"))
+        .subcommand(
+            Command::new("test")
+                .about("some")
+                .arg(Arg::new("child").long("child")),
+        );
+    utils::assert_output(cmd, "parent -h", EXPECTED, false);
+}
+
+#[test]
+fn flatten_recursive() {
+    static EXPECTED: &str = "\
+Usage: parent [OPTIONS]
+       parent child1 [OPTIONS]
+       parent child1 grandchild1 [OPTIONS]
+       parent child1 grandchild1 greatgrandchild1 [OPTIONS]
+       parent child1 grandchild1 greatgrandchild2 [OPTIONS]
+       parent child1 grandchild1 greatgrandchild3 [OPTIONS]
+       parent child1 grandchild1 help [COMMAND]
+       parent child1 grandchild2 [OPTIONS]
+       parent child1 grandchild3 [OPTIONS]
+       parent child1 help [COMMAND]
+       parent child2 [OPTIONS]
+       parent child3 [OPTIONS]
+       parent help [COMMAND]...
+
+Options:
+      --parent <parent>  
+  -h, --help             Print help
+
+parent child1:
+      --child1 <child>  
+  -h, --help            Print help
+
+parent child1 grandchild1:
+some 1
+      --grandchild1 <grandchild>  
+  -h, --help                      Print help
+
+parent child1 grandchild1 greatgrandchild1:
+some 1
+      --greatgrandchild1 <greatgrandchild>  
+  -h, --help                                Print help
+
+parent child1 grandchild1 greatgrandchild2:
+some 1
+      --greatgrandchild2 <greatgrandchild>  
+  -h, --help                                Print help
+
+parent child1 grandchild1 greatgrandchild3:
+some 1
+      --greatgrandchild3 <greatgrandchild>  
+  -h, --help                                Print help
+
+parent child1 grandchild1 help:
+some 1
+
+
+parent child1 grandchild2:
+some 1
+      --grandchild2 <grandchild>  
+  -h, --help                      Print help
+
+parent child1 grandchild3:
+some 1
+      --grandchild3 <grandchild>  
+  -h, --help                      Print help
+
+parent child1 help:
+some 1
+
+
+parent child2:
+      --child2 <child>  
+  -h, --help            Print help
+
+parent child3:
+      --child3 <child>  
+  -h, --help            Print help
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
+";
+    let cmd = Command::new("parent")
+        .flatten_help(true)
+        .arg(Arg::new("parent").long("parent"))
+        .subcommand(
+            Command::new("child1")
+                .flatten_help(true)
+                .about("some 1")
+                .arg(Arg::new("child").long("child1"))
+                .subcommand(
+                    Command::new("grandchild1")
+                        .flatten_help(true)
+                        .about("some 1")
+                        .arg(Arg::new("grandchild").long("grandchild1"))
+                        .subcommand(
+                            Command::new("greatgrandchild1")
+                                .about("some 1")
+                                .arg(Arg::new("greatgrandchild").long("greatgrandchild1")),
+                        )
+                        .subcommand(
+                            Command::new("greatgrandchild2")
+                                .about("some 2")
+                                .arg(Arg::new("greatgrandchild").long("greatgrandchild2")),
+                        )
+                        .subcommand(
+                            Command::new("greatgrandchild3")
+                                .about("some 3")
+                                .arg(Arg::new("greatgrandchild").long("greatgrandchild3")),
+                        ),
+                )
+                .subcommand(
+                    Command::new("grandchild2")
+                        .about("some 2")
+                        .arg(Arg::new("grandchild").long("grandchild2")),
+                )
+                .subcommand(
+                    Command::new("grandchild3")
+                        .about("some 3")
+                        .arg(Arg::new("grandchild").long("grandchild3")),
+                ),
+        )
+        .subcommand(
+            Command::new("child2")
+                .about("some 2")
+                .arg(Arg::new("child").long("child2")),
+        )
+        .subcommand(
+            Command::new("child3")
+                .about("some 3")
+                .arg(Arg::new("child").long("child3")),
+        );
+    utils::assert_output(cmd, "parent -h", EXPECTED, false);
+}
+
+#[test]
+fn flatten_not_recursive() {
+    static EXPECTED: &str = "\
+Usage: parent [OPTIONS]
+       parent child1 [OPTIONS] [COMMAND]
+       parent child2 [OPTIONS]
+       parent child3 [OPTIONS]
+       parent help [COMMAND]...
+
+Options:
+      --parent <parent>  
+  -h, --help             Print help
+
+parent child1:
+      --child1 <child>  
+  -h, --help            Print help
+
+parent child2:
+      --child2 <child>  
+  -h, --help            Print help
+
+parent child3:
+      --child3 <child>  
+  -h, --help            Print help
+
+parent help:
+  [COMMAND]...  Print help for the subcommand(s)
+";
+    let cmd = Command::new("parent")
+        .flatten_help(true)
+        .arg(Arg::new("parent").long("parent"))
+        .subcommand(
+            Command::new("child1")
+                .about("some 1")
+                .arg(Arg::new("child").long("child1"))
+                .subcommand(
+                    Command::new("grandchild1")
+                        .about("some 1")
+                        .arg(Arg::new("grandchild").long("grandchild1")),
+                )
+                .subcommand(
+                    Command::new("grandchild2")
+                        .about("some 2")
+                        .arg(Arg::new("grandchild").long("grandchild2")),
+                )
+                .subcommand(
+                    Command::new("grandchild3")
+                        .about("some 3")
+                        .arg(Arg::new("grandchild").long("grandchild3")),
+                ),
+        )
+        .subcommand(
+            Command::new("child2")
+                .about("some 2")
+                .arg(Arg::new("child").long("child2")),
+        )
+        .subcommand(
+            Command::new("child3")
+                .about("some 3")
+                .arg(Arg::new("child").long("child3")),
+        );
+    utils::assert_output(cmd, "parent -h", EXPECTED, false);
+}