test: Add test for flatten with mixed headings

gortavoher · gortavoher · commit 870ff30ad2f3 · 2025-11-21T08:55:01.000Z
- add test case to verify that mixed headings are flattened correctly
- update usage and help templates to display in custom headings order
diff --git a/clap_builder/src/output/help_template.rs b/clap_builder/src/output/help_template.rs
@@ -892,7 +892,18 @@ impl HelpTemplate<'_, '_> {
                 subcommand,
             );
         }
-        for (_, subcommand) in ord_v {
+
+        let custom_headings = self
+            .cmd
+            .get_subcommands()
+            .filter_map(|cmd| cmd.get_help_heading())
+            .collect::<FlatSet<_>>();
+
+        // Write commands that have no custom heading
+        for (_, subcommand) in ord_v
+            .iter()
+            .filter(|item| item.1.get_help_heading().is_none())
+        {
             if !*first {
                 self.writer.push_str("\n\n");
             }
@@ -931,6 +942,71 @@ impl HelpTemplate<'_, '_> {
                 sub_help.write_flat_subcommands(subcommand, first);
             }
         }
+
+        // Commands under custom headings
+        if !custom_headings.is_empty() {
+            for heading in custom_headings {
+                let cmds = self
+                    .cmd
+                    .get_subcommands()
+                    .filter(|sc| {
+                        if let Some(help_heading) = sc.get_help_heading() {
+                            return help_heading == heading;
+                        }
+                        false
+                    })
+                    .filter(|sc| should_show_subcommand(sc))
+                    .collect::<Vec<_>>();
+
+                if !cmds.is_empty() {
+                    for (_, subcommand) in ord_v
+                        .clone()
+                        .into_iter()
+                        .filter(|item| item.1.get_help_heading() == Some(heading))
+                    {
+                        if !*first {
+                            self.writer.push_str("\n\n");
+                        }
+                        *first = false;
+
+                        let heading = subcommand.get_usage_name_fallback();
+                        let about = subcommand
+                            .get_about()
+                            .or_else(|| subcommand.get_long_about())
+                            .unwrap_or_default();
+
+                        let _ = write!(self.writer, "{header}{heading}:{header:#}",);
+                        if !about.is_empty() {
+                            let _ = write!(self.writer, "\n{about}",);
+                        }
+
+                        let args = subcommand
+                            .get_arguments()
+                            .filter(|arg| {
+                                should_show_arg(self.use_long, arg) && !arg.is_global_set()
+                            })
+                            .collect::<Vec<_>>();
+                        if !args.is_empty() {
+                            self.writer.push_str("\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,
+                        };
+                        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.
@@ -968,7 +1044,7 @@ impl HelpTemplate<'_, '_> {
 
         let next_line_help = self.will_subcommands_wrap(cmd.get_subcommands(), longest);
 
-        let command_custom_headings = self
+        let custom_headings = self
             .cmd
             .get_subcommands()
             .filter_map(|cmd| cmd.get_help_heading())
@@ -988,8 +1064,9 @@ impl HelpTemplate<'_, '_> {
             self.write_subcommand(sc_str.1, sc, next_line_help, longest);
         }
 
-        if !command_custom_headings.is_empty() {
-            for heading in command_custom_headings {
+        // Commands under custom headings
+        if !custom_headings.is_empty() {
+            for heading in custom_headings {
                 let cmds = self
                     .cmd
                     .get_subcommands()
diff --git a/clap_builder/src/output/usage.rs b/clap_builder/src/output/usage.rs
@@ -113,17 +113,53 @@ impl Usage<'_> {
             }
             let mut cmd = self.cmd.clone();
             cmd.build();
+
+            // Get the custom headings
+            let custom_headings = cmd
+                .get_subcommands()
+                .filter_map(|sc| sc.get_help_heading())
+                .collect::<FlatSet<_>>();
+
+            // Write commands without headings
             for (i, sub) in cmd
                 .get_subcommands()
                 .filter(|c| !c.is_hide_set())
+                .filter(|c| c.get_help_heading().is_none())
                 .enumerate()
             {
+                if sub.get_name() == "help" {
+                    continue;
+                }
                 if i != 0 {
                     styled.trim_end();
                     let _ = write!(styled, "{USAGE_SEP}");
                 }
                 Usage::new(sub).write_usage_no_title(styled, &[]);
             }
+
+            // Write commands with headings
+            for heading in custom_headings {
+                for sub in cmd
+                    .get_subcommands()
+                    .filter(|c| !c.is_hide_set())
+                    .filter(|c| c.get_help_heading() == Some(heading))
+                {
+                    if sub.get_name() == "help" {
+                        continue;
+                    }
+                    styled.trim_end();
+                    let _ = write!(styled, "{USAGE_SEP}");
+                    Usage::new(sub).write_usage_no_title(styled, &[]);
+                }
+            }
+
+            // Write help command last (regardless of custom headings)
+            if let Some(sub) = cmd.find_subcommand("help") {
+
+                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);
diff --git a/tests/builder/help.rs b/tests/builder/help.rs
@@ -4756,7 +4756,7 @@ Options:
 }
 
 #[test]
-    fn test_multiple_commands_mixed_standard_and_custom_headers() {
+fn test_multiple_commands_mixed_standard_and_custom_headers() {
     static VISIBLE_ALIAS_HELP: &str = "\
 Usage: clap-test [COMMAND]
 
@@ -4853,6 +4853,90 @@ Options:
         utils::assert_output(cmd, "clap-test --help", VISIBLE_ALIAS_HELP, false);
     }
 
+#[test]
+fn test_multiple_commands_mixed_headings_flatten() {
+    static VISIBLE_ALIAS_HELP: &str = "\
+Usage: clap-test
+       clap-test def_cmd1
+       clap-test def_cmd2
+       clap-test cust_cmd1
+       clap-test cust_cmd2 --child <child>
+       clap-test other_cmd1
+       clap-test other_cmd2 --child <child>
+       clap-test help [COMMAND]...
+
+Options:
+  -h, --help     Print help
+  -V, --version  Print version
+
+clap-test def_cmd1:
+Def_cmd1 under default command heading
+  -h, --help  Print help
+
+clap-test def_cmd2:
+Def_cmd2 under default command heading
+  -h, --help  Print help
+
+clap-test help:
+Print this message or the help of the given subcommand(s)
+  [COMMAND]...  Print help for the subcommand(s)
+
+clap-test cust_cmd1:
+Cust_cmd1 under custom command heading
+  -h, --help  Print help
+
+clap-test cust_cmd2:
+Cust_cmd2 under custom command heading
+      --child <child>  child help
+  -h, --help           Print help
+
+clap-test other_cmd1:
+Other_cmd1 under other command heading
+  -h, --help  Print help
+
+clap-test other_cmd2:
+Other_cmd2 under other command heading
+      --child <child>  
+  -h, --help           Print help
+";
+    
+    let cmd = Command::new("clap-test")
+        .version("2.6")
+        .flatten_help(true)
+        .subcommand(
+            Command::new("def_cmd1")
+                .about("Def_cmd1 under default command heading")
+        )
+        .subcommand(
+            Command::new("cust_cmd1")
+            .about("Cust_cmd1 under custom command heading")
+            .help_heading("Custom Heading"),
+        )
+        .subcommand(
+            Command::new("other_cmd1")
+            .about("Other_cmd1 under other command heading")
+            .help_heading("Other Heading"),
+        )
+        .subcommand(
+            Command::new("other_cmd2")
+            .about("Other_cmd2 under other command heading")
+            .help_heading("Other Heading")
+            .arg(Arg::new("child").long("child").required(true)),
+        )
+        .subcommand(
+            Command::new("def_cmd2")
+                .about("Def_cmd2 under default command heading")
+        )
+        .subcommand(
+            Command::new("cust_cmd2")
+                .about("Cust_cmd2 under custom command heading")
+                .help_heading("Custom Heading")
+                .arg(Arg::new("child").long("child").required(true).help("child help")),
+        );
+
+    utils::assert_output(cmd, "clap-test --help", VISIBLE_ALIAS_HELP, false);
+}
+
 
 #[test]
 fn test_help_header_hide_commands_header() {
