feat: add command headings feature #6183

jerusdp · 2025-11-17T12:11:54Z

Implementing issue #1553

Scope of this PR

The objective for this PR is to provide a facility for the user to place their commands under a custom header to allow the grouping of commands such as might be seen in git --help.

The PR will not implement CommandAction which would be required to permit the user to replace the help command with a custom user help command which could be place under a custom header. The user can place help under a custom header by amending the default title using Command::subcommand_help_heading placing the help command and the updated section at the top of the list of commands.

The will not change the scope of the Command::next_help_heading to include processing for commands as this is a breaking change.

Design Statements

Statement	Comment
MUST provide API to specify a custom section header for a user command	The key objective of the change
MUST keep commands with the same header together
MUST display commands with no custom header under the default header
MUST display help command under the standard header	To amend this the user should change the default header
WILL NOT change scope of `Command::next_help_heading` to include subcommands
WILL NOT deprecate `Command::subcommand_help_heading`	It can be used to generate custom section heading for help
WILL NOT implement custom replacement of help	Future solution requiring `CommandAction`

Cargo.toml

epage · 2025-11-18T13:50:38Z

Please clean up the commits for how they should be reviewed and merged.

there are extra commits from master that were rewritten
builds are failing on early commits

epage · 2025-11-18T14:50:49Z

there are extra commits from master that were rewritten

These commits are still around

epage · 2025-11-18T14:51:04Z

Also, be sure to ping me when force-pushing; github doesn't send notifications for it.

jerusdp · 2025-11-18T15:43:03Z

@epage dropped the commits and force pushed

clap_builder/src/builder/command.rs

clap_builder/src/output/help_template.rs

tests/builder/subcommands.rs

epage · 2025-11-19T21:12:30Z

Please clean up commits for how they should be reviewed and merged and not for how this was implemented

clap_builder/src/output/help_template.rs

tests/builder/subcommands.rs

tests/builder/help.rs

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

jerusdp · 2025-11-21T13:37:02Z

@epage Amended and test for flatten introduced; changes introduced to ensure test passes

clap_builder/src/output/help_template.rs

epage · 2025-11-21T18:14:00Z

clap_builder/src/output/help_template.rs

+        // Commands under custom headings
+        if !custom_headings.is_empty() {


This change is overall a lot more complicated than I would have expected and I'll likely need to dig into this a lot further to better understand how inherent the complexity is or isn't before we're able to move forward.

The objective is to preserve the order in which the flattened commands are set out both in the usage and the commands sections so that commands are grouped within their custom headings.

That is a fair point. If people rely on the help headings to logically group their commands, then consistently using that order elsewhere can make sense. There can still be room for discussing whether it is worth it or not. Most likely, we'll need to whittle away at other complexity first to see how much of an impact it really makes.

As for the other complexity, in each case where we are dealing with custom help headings, we are duplicating all of the underlying logic rather than folding the custom and built-in heading cases together, making this more ripe for bugs. This code also special cases help which will make it diverge in order compared to anything else and seems like a potential feature independent of this work.

So, two issues here:

Special casing of help

Need to refactor the similar/same processes to reduce duplication

There is another concern I had last night and that is whether there are any other artefacts that are caused by the feature.

There is another concern I had last night and that is whether there are any other artefacts that are caused by the feature.

What do you mean?

There is another concern I had last night and that is whether there are any other artefacts that are caused by the feature.

What do you mean?

That there would be some other interaction from the help_heading API - I produced a more comprehensive set of tests (all the helps tests with subcommand with a help_heading added) and only found a couple of problems with the flattened versions. One fixed and the other I am still working on.

- add tests for subcommand headings feature - include tests for single and multiple help headers - add test for hiding commands header - add test for mixed standard and custom headers - add test case to verify that mixed headings are flattened correctly - shuffled order in multiple command test - add support for subcommand help headings - display subcommands under their respective headings in help output - only display heading if subcommand has `help_heading` set - Set order for custom headings (as found) - write commands in order under headings in order - update usage and help templates to display in custom headings order - introduce `complex_app_with_help_heading` function - similar to `complex_app` but includes `help_heading` - Test subcmds with `help_heading` - Update tests to include the custom heading in the expected output. - extract the logic for writing a flattened subcommand to a function

epage reviewed Nov 17, 2025

View reviewed changes

Cargo.toml Outdated Show resolved Hide resolved

jerusdp force-pushed the jerusdp/command-help-headings branch 2 times, most recently from 2b3d6c7 to 8c43bdc Compare November 18, 2025 12:03

jerusdp marked this pull request as ready for review November 18, 2025 13:00

jerusdp force-pushed the jerusdp/command-help-headings branch from 45ae543 to 503ebfd Compare November 18, 2025 14:42

jerusdp force-pushed the jerusdp/command-help-headings branch from 503ebfd to 758234f Compare November 18, 2025 15:42

epage reviewed Nov 18, 2025

View reviewed changes

clap_builder/src/builder/command.rs Outdated Show resolved Hide resolved

epage reviewed Nov 18, 2025

View reviewed changes

clap_builder/src/output/help_template.rs Outdated Show resolved Hide resolved

epage reviewed Nov 18, 2025

View reviewed changes

tests/builder/subcommands.rs Outdated Show resolved Hide resolved

epage reviewed Nov 18, 2025

View reviewed changes

tests/builder/subcommands.rs Outdated Show resolved Hide resolved

epage reviewed Nov 18, 2025

View reviewed changes

tests/builder/subcommands.rs Outdated Show resolved Hide resolved