How to add an extra, separate help option that overrides required arguments?

[obskyr]

--help overrides any required arguments – instead simply printing the help and exiting. Is there an idiomatic way to add a separate option that does the same? Say, something akin to ffmpeg -formats – a command that lists specific options that you don't want to include in the general help.

This may (or may not?) be possible to accomplish by putting all your required arguments into an ArgGroup and making that mutually exclusive with the new help option, but that seems clunky, and I haven't managed to figure out whether it's possible to make groups mutually exclusive – I figured there might be a simpler way that I'm missing!

A minimal example setup:

#[derive(clap::Parser)]
struct Args {
    required_1: String,
    required_2: String,

    // How to make this override the required arguments and
    // simply print a different help page and exit?
    // There doesn't seem to be an `ArgAction` for it.
    #[arg(default_value_t=false)]
    different_help: bool
}

fn main() {
    let _args: Args = clap::Parser::parse();
    // Can't check for `_args.different_help` here, since it'll error out
    // due to the required arguments being missing.
}

Is --help implemented in a way that's possible to imitate on the user end…?

[epage]

--help is processed during the parsing process. A particularly important aspect id that this is processed before the struct is populated.

We offer exclusive but that has challenges with the derive API because the struct needs to be populated. You can switch the struct to using Option fields with explicit required = true to make that work.

Members of a group are exclusive by default. You can also declare groups to conflict with other groups. #2621 would help with some things but could run into #4697.

[obskyr]

Thank you immensely kindly for the exhaustive answer! 😊 The “exclusive + Option + required = true” approach worked a charm – since my actual setup for required arguments used required_unless_present, I ran into a new bug (#5507), but it was one I managed managed to work around.

Here's the equivalent of what I ended up with:

#[derive(clap::Parser)]
struct Args {
    #[arg(long, required_unless_present_any(["alternative_arg", "different_help"]))]
    required_arg: Option<String>,
    #[arg(long)]
    alternative_arg: Option<String>,

    #[arg(exclusive = true, long, default_value_t=false)]
    different_help: bool
}

fn main() {
    let args: Args = clap::Parser::parse();
    if args.different_help {
        // …
        return;
    }
}