diff --git a/clap_builder/src/output/help_template.rs b/clap_builder/src/output/help_template.rs index da2e7541328..f8e07adaccc 100644 --- a/clap_builder/src/output/help_template.rs +++ b/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::>(); + 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,60 @@ impl<'cmd, 'writer> HelpTemplate<'cmd, 'writer> { } } } + if flatten { + let mut cmd = self.cmd.clone(); + cmd.build(); + + 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: false, + term_w: self.term_w, + use_long: false, + }; + let args = subcommand + .get_arguments() + .filter(|arg| should_show_arg(self.use_long, arg)) + .collect::>(); + sub_help.write_args(&args, heading, option_sort_key); + } + } } /// Sorts arguments by length and display order and write their help to the wrapped stream. diff --git a/examples/git-derive.md b/examples/git-derive.md index afc4d0c8feb..442498dc603 100644 --- a/examples/git-derive.md +++ b/examples/git-derive.md @@ -78,16 +78,25 @@ Usage: git-derive[EXE] stash [OPTIONS] git-derive[EXE] stash apply [STASH] git-derive[EXE] stash help [COMMAND]... -Commands: - push - pop - apply - help Print this message or the help of the given subcommand(s) - Options: -m, --message -h, --help Print help +git-derive[EXE] stash push: + -m, --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] diff --git a/examples/git.md b/examples/git.md index 66e8baae83b..55acc69c246 100644 --- a/examples/git.md +++ b/examples/git.md @@ -76,16 +76,25 @@ Usage: git[EXE] stash [OPTIONS] git[EXE] stash apply [STASH] git[EXE] stash help [COMMAND]... -Commands: - push - pop - apply - help Print this message or the help of the given subcommand(s) - Options: -m, --message -h, --help Print help +git[EXE] stash push: + -m, --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] diff --git a/tests/builder/help.rs b/tests/builder/help.rs index 22cbaab583c..83bed4b519c 100644 --- a/tests/builder/help.rs +++ b/tests/builder/help.rs @@ -2956,13 +2956,16 @@ Usage: parent [OPTIONS] parent test [OPTIONS] parent help [COMMAND]... -Commands: - test some - help Print this message or the help of the given subcommand(s) - Options: --parent -h, --help Print help + +parent test: + --child + -h, --help Print help + +parent help: + [COMMAND]... Print help for the subcommand(s) "; let cmd = Command::new("parent") .flatten_help(true) @@ -2982,13 +2985,16 @@ Usage: parent [OPTIONS] parent test [OPTIONS] parent help [COMMAND]... -Commands: - test some - help Print this message or the help of the given subcommand(s) - Options: --parent foo -h, --help Print help (see more with '--help') + +parent test: + --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) @@ -3014,16 +3020,19 @@ Usage: parent [OPTIONS] parent test [OPTIONS] parent help [COMMAND]... -Commands: - test some - help Print this message or the help of the given subcommand(s) - Options: --parent bar -h, --help Print help (see a summary with '-h') + +parent test: + --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) @@ -3049,16 +3058,19 @@ Usage: parent [OPTIONS] parent test [OPTIONS] parent help [COMMAND]... -Commands: - test some - help Print this message or the help of the given subcommand(s) - Options: --parent bar -h, --help Print help (see a summary with '-h') + +parent test: + --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) @@ -3084,13 +3096,17 @@ Usage: parent [OPTIONS] parent test [OPTIONS] parent help [COMMAND]... -Commands: - test some - help Print this message or the help of the given subcommand(s) - Options: --parent -h, --help Print help + +parent test: + --child + --parent + -h, --help Print help + +parent help: + [COMMAND]... Print help for the subcommand(s) "; let cmd = Command::new("parent") .flatten_help(true) @@ -3110,13 +3126,16 @@ Usage: parent --parent parent --parent test --child parent --parent help [COMMAND]... -Commands: - test some - help Print this message or the help of the given subcommand(s) - Options: --parent -h, --help Print help + +parent --parent test: + --child + -h, --help Print help + +parent --parent help: + [COMMAND]... Print help for the subcommand(s) "; let cmd = Command::new("parent") .flatten_help(true) @@ -3136,13 +3155,16 @@ Usage: parent [OPTIONS] parent test [OPTIONS] parent help [COMMAND]... -Commands: - test some - help Print this message or the help of the given subcommand(s) - Options: --parent -h, --help Print help + +parent test: + --child + -h, --help Print help + +parent help: + [COMMAND]... Print help for the subcommand(s) "; let cmd = Command::new("parent") .flatten_help(true) @@ -3177,13 +3199,16 @@ fn flatten_with_subcommand_required() { Usage: parent test [OPTIONS] parent help [COMMAND]... -Commands: - test some - help Print this message or the help of the given subcommand(s) - Options: --parent -h, --help Print help + +parent test: + --child + -h, --help Print help + +parent help: + [COMMAND]... Print help for the subcommand(s) "; let cmd = Command::new("parent") .flatten_help(true) @@ -3204,13 +3229,16 @@ Usage: parent [OPTIONS] parent test [OPTIONS] parent help [COMMAND]... -Commands: - test some - help Print this message or the help of the given subcommand(s) - Options: --parent -h, --help Print help + +parent test: + --child + -h, --help Print help + +parent help: + [COMMAND]... Print help for the subcommand(s) "; let cmd = Command::new("parent") .flatten_help(true) @@ -3242,15 +3270,24 @@ Usage: parent [OPTIONS] parent child3 [OPTIONS] parent help [COMMAND]... -Commands: - child1 some 1 - child2 some 2 - child3 some 3 - help Print this message or the help of the given subcommand(s) - Options: --parent -h, --help Print help + +parent child1: + --child1 + -h, --help Print help + +parent child2: + --child2 + -h, --help Print help + +parent child3: + --child3 + -h, --help Print help + +parent help: + [COMMAND]... Print help for the subcommand(s) "; let cmd = Command::new("parent") .flatten_help(true) @@ -3314,15 +3351,24 @@ Usage: parent [OPTIONS] parent child3 [OPTIONS] parent help [COMMAND]... -Commands: - child1 some 1 - child2 some 2 - child3 some 3 - help Print this message or the help of the given subcommand(s) - Options: --parent -h, --help Print help + +parent child1: + --child1 + -h, --help Print help + +parent child2: + --child2 + -h, --help Print help + +parent child3: + --child3 + -h, --help Print help + +parent help: + [COMMAND]... Print help for the subcommand(s) "; let cmd = Command::new("parent") .flatten_help(true)