derive: Is there a way to opt out of help subcommands in clap 4?

[philipahlberg]

I'm using a fairly basic setup with the derive feature:

#[derive(Debug, Parser)]
#[clap(name = "cli")]
pub enum Cli {
    #[clap(subcommand)]
    Sub(Sub)
}

#[derive(Debug, Subcommand)]
pub enum Sub {
    One,
    Two,
}

Playground link here for the example above as well as completions via clap_complete and clap_complete_nushell.

This results in all the following help-related commands and flags to be generated:

• Help for missing arguments:
  • cli
  • cli sub
• help subcommands (for all subcommands):
  • cli help
  • cli help help (I can't tell if this one is intentional?)
  • cli help sub
  • cli help sub one
  • cli help sub two
  • cli sub help
  • cli sub help help (same as with cli help help)
  • cli sub help one
  • cli sub help two
• Flags for all commands and subcommands:
  • cli --help
  • cli sub --help
  • cli sub one -h
  • cli sub one --help
  • cli sub two -h
  • cli sub two --help

While I appreciate the accessibility, the number of variations results in a lot of noise. For example, in nushell, with completions generated using clap_complete and clap_complete_nushell, I'll see the following completions for cli:

That is:

• 2 functioning commands (cli sub one and cli sub two)
• 2 implicitly help-related commands (cli and cli sub)
• 8 explicitly help-related commands
• 4 help flags (8 if counting both -h and --help)

Is there any way to opt out of one or more of these variations? Ideally I'd like just the top-level cli help <COMMAND> and help for missing arguments.

[epage]

You can set the disable_help_subcommand raw attribute.

I'm a bit surprised it lists all depths of subcommands when just completing the command. Is that a general behavior in nushell (e.g. does git\t include git stash pop?) or is that a bug in our completer?

[philipahlberg]

You can set the disable_help_subcommand raw attribute.

Thanks! I actually looked at the available functions on Command , but I somehow still missed it.

I'm a bit surprised it lists all depths of subcommands when just completing the command. Is that a general behavior in nushell (e.g. does git\t include git stash pop?) or is that a bug in our completer?

I'm not sure. My git completions seems to be broken - git\t just lists the files in my current directory 🤷 FWIW the completions file generated in the example above seems to be valid. I initially thought it might be invalid since it includes e.g. cli help help, but I was surprised to learn that that's also consistent with the resulting executable. What's the rationale behind that anyway?

[epage]

The rationale behind allowing you to complete cli help sub is to help raise visibility and make it easier.

When we implemented support for that, my expectation was that you'd get something like

$ cli \t
sub
help
$ cli help \t
sub
help
$ cli sub \t
one
two
help

not

$ cli \t
sub
sub one
sub two
sub help
...

This isn't a question of whether the script is "invalid" but what expectations are for completions in nushell and whether we have control to make completions more like the first case than the second.

Hopefully #3166 will work with nushell which would give us complete control.

[philipahlberg]

This isn't a question of whether the script is "invalid" but what expectations are for completions in nushell and whether we have control to make completions more like the first case than the second.

I see. I wanted to address this question:

or is that a bug in our completer?

What I ment was that the completion file lists all the available commands, and it doesn't list any invalid commands, so it's not doing anything incorrect, per se. With that said, I think it is possible to get the behavior you want by using Context aware custom completions. Not sure how that would work, though. A simple record-based approach like the one given in the examples would work for simple subcommands like we're looking at here, but it would fall apart if flags are interspersed with subcommand I guess. For a thorough solution I imagine you'd have to either emulate a lot of the parsing logic from clap in nushell, or somehow reuse the command itself to generate the suggestions (the executable would have to include a command for this I suppose).