New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Don't show global options #5355
Comments
If the argument truly is global, the user needs some kind of indication that it is supported on the command. You mention having a pointer to users about this. This is somewhat like #5354 where the approach is we give developer the option to not show something and the developer is responsible for adding the Another option not mentioned is to put the globals under their own You'd then get
A workaround for any of this is to re-define your globals in the subcommand but hidden. Clap will still propagate the value for these options up to the parent command, behaving the same. For an example of cargo taking advantage of this overriding of globals, see rust-lang/cargo#12959. Considering the alternatives, the workarounds, and the niche nature of this (from my perspective), I would be hesitant to add a new toggle within clap. Each toggle comes with a binary size, compile time, and API bloat cost and we try to weigh that against the value added. In this case, I'm not seeing enough value. |
Thanks for the pointers. I'll take a look and see if I can come up with something that works for us! |
Here's what we ended up doing. Basically, If you have ideas on how to further improve this, I'd be happy to hear them! let mut cli = cli::build(true);
let matches = cli.clone().try_get_matches();
let c = match matches {
Ok(matches) => {
cli::SqCommand::from_arg_matches(&matches)?
}
Err(err) => {
use clap::error::ErrorKind;
if err.kind() == ErrorKind::DisplayHelp
|| err.kind() == ErrorKind::DisplayHelpOnMissingArgumentOrSubcommand
{
let output = err.render();
let output = if output == cli.render_long_help() {
Some(cli::build(false).render_long_help())
} else if output == cli.render_help() {
Some(cli::build(false).render_help())
} else {
None
};
if let Some(output) = output {
if err.use_stderr() {
eprint!("{}", output);
} else {
print!("{}", output);
}
std::process::exit(err.exit_code());
}
}
err.exit();
}
}; |
... that seems a lot more brittle than what I suggested earlier
|
Please complete the following tasks
Clap Version
4.5.0
Describe your use case
sq
, the command-line frontend for sequoia-openpgp, has a number of global options. These are shown in the help output of all subcommands, which makes the--help
output of the subcommands hard to read. In particular, the salient information is hidden. Consider:sq cert
has one option,--help
; all of the other options are global options.We'd like the output of
--help
to make it easier for readers to find the most relevant information.Describe the solution you'd like
One idea we had is that clap could provide a mechanism to have
--help
only show local arguments, and perhaps mention that global arguments are described in the top-level--help
output. Doing this, the above output would be changed to something like:from which we think it is easier to extract the most important information.
I see several two ways to add support for this to
clap
:There could be an option for
Command
s similar toCommand::hide_possible_values
, perhapsCommand::hide_non_local_arguments
.Command::help_template
could distinguish between local and global options. That is, in addition to{options}
, which currently shows the local and global options, there could be{local-options}
,{global-options}
, and{see-global-options}
. The third would expand to the empty string if there are no global options and otherwise to a section, as above.Alternatives, if applicable
Another way to hide the global options in
--help
would be to change the global options into top-level options. This changes the CLI, but may be worth it.We could also have a struct for all of the global options in which each argument is hidden, and then manually include and flatten it into each subcommand. The disadvantage is that it results in a bit of code duplication.
Additional Context
No response
The text was updated successfully, but these errors were encountered: