clap
clap copied to clipboard
clap-rs
Add Subcommand help headings
Group subcommands displayed in help (https://github.com/clap-rs/clap/issues/1553) This is for help only, does not affect matching.
I've done the builder part, still figuring out derive support (ah - it works automatically by setting subcommand_help_header=Some("foo"). I'd probably should just document it somewhere).
This is done the same way grouping args works: subcommand has optional subcommand_help_heading. If provided, it will be used to group commands visually when displaying subcommand help.
so that we can go from
Commands: cmd1 ... cmd2 ... help ...
to
Commands: help ...
Utility commands: cmd1 ... cmd2 ....
Nothing changes if groups aren't used. See tests for examples.
Issues: having subcommand_heading and subcommand_help_heading may be confusing, maybe naming should change.
Hey, I needed this feature for a tool I am writing, that has a lot of complex commands. So I rebased the PR in https://github.com/Kamuno/clap/commit/400dd8538d48332f2e563b1344ea55e32fd6206a
Thank you all for the hard work you are doing. :) Great library and really useful PR!
Please merge this, it fixes a painful problem.
Without it, I would need a serious code enshittification to change my code from declarative derive subcommands (all 27 of them) to an ugly mix with builder patterns that will not work well anyway, just to show these section headings.
Please merge this, it fixes a painful problem.
This can't be merged as is. Someone will need to step up and finish this work
Without it, I would need a serious code enshittification to change my code from declarative derive subcommands (all 27 of them) to an ugly mix with builder patterns that will not work well anyway, just to show these section headings.
Why would the lack of this require mixing derive with builder?
Why would the lack of this require mixing derive with builder?
Because I cannot make section headings on subcommands enum in current clap version. If you look at the setup here.
The disparate bits and pieces of clap suggestions are saying something like "You can have subcommand section headings if you use builder, but not derive, so if you have a bunch of derived structures, you will have to glue them with builder to have the section headings". It loses abiiltiy to make back Opts structure from parsed args though, so will require a lot of noisy refactoring anyway.
With the changes in this PR I can make section headings, the only two thing that are not possible is to 1) order them properly like I need to, 2) rename section headings back to "Commands" in the subcommand helps (it looks weird).
This can't be merged as is. Someone will need to step up and finish this work
What is the process for taking over the PR to finish up the work and get it ready to merge? I see the PR is already many commits behind the master so perhaps starting from a fresh master is best? - if there is some git "magic" to help with this a steer towards it would be good.
I am interested in seeing this to merging if possible.
Note that there is still design discussion that needs to happen before moving forward on this PR, see https://github.com/clap-rs/clap/pull/5819#discussion_r1844637715 (the issue is marked "waiting on design", not one of our "ready to implement labels).
After that, I've not checked to see how bad the conflicts are to see if this just needs a git rebase master or if it would be easier to port the concepts over.