Default Subcommand fails with required options

[esemeniuc]

I worked with the git derive example, however I could not make it work with required parameters. For example changing the message parameter of stash subcommand to type String:

clap/examples/git-derive.rs

Line 97 in c7e929e

message: Option<String>,

Explicit subcommand:

➜  clap-demo git:(master) ✗ cargo b && target/debug/clap-demo stash -m foo
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
Pushing StashPushArgs { message: "foo" }

Implicit subcommand:

➜  clap-demo git:(master) ✗ cargo b && target/debug/clap-demo -m foo      
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
error: unexpected argument '-m' found

Usage: clap-demo <COMMAND>

For more information, try '--help'.

This is using clap 4.1.8 like so: clap = { version = "4", features = ["derive", "env"] }

[epage]

I think those example cases you showed are missing a level. What is labeled as "Explicit subcommand" is the implicit subcommand. What is labeled as "implicit subcommand" is unrelated to this.

I'm assuming you meant to show that it errors when you do clap-demo stash push -m foo with an error about -m not being used?

Internally to clap, it is likely doing everything that you expected as conflicts override requires. You can confirm this by using cargo run -F clap/debug.

Most likely, the problem is in the code that clap_derive generates. When it is trying to put something in the message: String field, what does it do? When its Option<String>, it knows to put in None. We have decided to make this also report as "missing required arg" error as something like this slipping out to end-users, that is likely the best error clap can produce.

The way to resolve this is to keep the field as an Option<String> and to explicitly mark it as #[arg(required = true)]. Alternatively, you might be to change push: StashPushArgs, to push: Option<StashPushArgs>,

#4736 is the discussion for brainstorming how to improve the developer experience for this issue.

[esemeniuc]

Same outcome if I try both modifications together :(

[epage]

Thanks for the suggestions! In my (perhaps incorrect) view of things, the subcommand was stash. Yes I would like to have -m be required in both cases (with and without stash)

Unless you have further deviated from the example than stated, git stash is defaulted to mean git stash push. This example is based on the real-world use case of git stash which is a git subcommand that has its own subcommands with the push one being defaulted.

Note the code

#[derive(Debug, Parser)] // requires `derive` feature
#[command(name = "git")]
#[command(about = "A fictional versioning CLI", long_about = None)]
struct Cli {
    #[command(subcommand)]
    command: Commands,
}

The top-level command git has no support for arguments like -m.

When we instead look at the stash command, we see

#[derive(Debug, Args)]
#[command(args_conflicts_with_subcommands = true)]
struct StashArgs {
    #[command(subcommand)]
    command: Option<StashCommands>,

    #[command(flatten)]
    push: StashPushArgs,
}

This supports either subcommands like push or the same argument set as push.

This means the error

➜  clap-demo git:(master) ✗ cargo b && target/debug/clap-demo -m foo    
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
error: unexpected argument '-m' found

Usage: clap-demo <COMMAND>

For more information, try '--help'.

is 100% correct

What you need to do instead is

➜  clap-demo git:(master) ✗ cargo b && target/debug/clap-demo stash -m foo
➜  clap-demo git:(master) ✗ cargo b && target/debug/clap-demo stash push -m foo

Note later in the example documentation, we provided tested interactions with the stash subcommand:

$ git-derive stash -h
Usage: git-derive[EXE] stash [OPTIONS]
       git-derive[EXE] stash <COMMAND>

Commands:
  push   
  pop    
  apply  
  help   Print this message or the help of the given subcommand(s)

Options:
  -m, --message <MESSAGE>  
  -h, --help               Print help

$ git-derive stash push -h
Usage: git-derive[EXE] stash push [OPTIONS]

Options:
  -m, --message <MESSAGE>  
  -h, --help               Print help

$ git-derive stash pop -h
Usage: git-derive[EXE] stash pop [STASH]

Arguments:
  [STASH]  

Options:
  -h, --help  Print help

$ git-derive stash -m "Prototype"
Pushing StashPushArgs { message: Some("Prototype") }

$ git-derive stash pop
Popping None

$ git-derive stash push -m "Prototype"
Pushing StashPushArgs { message: Some("Prototype") }

$ git-derive stash pop
Popping None

[esemeniuc]

Apologies for the (big!) oversight, I'll retry your suggestions!

[esemeniuc]

For posterity, here's the results

Using required = true (without any other changes) only:

#[derive(Debug, Args)]
struct StashPushArgs {
    #[arg(short, long, required=true)]
    message: Option<String>,
}

Explicit

➜  clap-demo git:(master) ✗ cargo b && target/debug/clap-demo stash push -m foo
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
thread 'main' panicked at 'called `Option::unwrap()` on a `None` value', src/main.rs:145:84
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
➜  clap-demo git:(master) ✗ cargo b && target/debug/clap-demo stash push -m foo
   Compiling clap-demo v0.1.0 (/home/eric/dev/clap-demo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.52s
Pushing StashPushArgs { message: Some("foo") }
➜  clap-demo git:(master) ✗ cargo b && target/debug/clap-demo stash push       
    Finished dev [unoptimized + debuginfo] target(s) in 0.03s
error: the following required arguments were not provided:
  --message <MESSAGE>

Usage: clap-demo stash push --message <MESSAGE>

For more information, try '--help'.

Implicit

➜  clap-demo git:(master) ✗ cargo b && target/debug/clap-demo stash -m foo
    Finished dev [unoptimized + debuginfo] target(s) in 0.03s
Pushing StashPushArgs { message: Some("foo") }
➜  clap-demo git:(master) ✗ cargo b && target/debug/clap-demo stash       
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
error: the following required arguments were not provided:
  --message <MESSAGE>

Usage: clap-demo stash --message <MESSAGE>

For more information, try '--help'.
➜  clap-demo git:(master) ✗ 

[esemeniuc]

Method 2:

    #[command(flatten)]
    push: Option<StashPushArgs>,

// snip...

    let stash_cmd = stash.command.unwrap_or(StashCommands::Push(stash.push.unwrap()));

Explicit

➜  clap-demo git:(master) ✗ cargo b && target/debug/clap-demo stash push -m foo
   Compiling clap-demo v0.1.0 (/home/eric/dev/clap-demo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.20s
thread 'main' panicked at 'called `Option::unwrap()` on a `None` value', src/main.rs:145:84
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
➜  clap-demo git:(master) ✗ cargo b && target/debug/clap-demo stash push       
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
thread 'main' panicked at 'called `Option::unwrap()` on a `None` value', src/main.rs:145:84
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Implicit

➜  clap-demo git:(master) ✗ cargo b && target/debug/clap-demo stash -m foo
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
Pushing StashPushArgs { message: Some("foo") }
➜  clap-demo git:(master) ✗ cargo b && target/debug/clap-demo stash       
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
thread 'main' panicked at 'called `Option::unwrap()` on a `None` value', src/main.rs:145:84
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
➜  clap-demo git:(master) ✗ 

[esemeniuc]

Method 1 works great, see #4755 (reply in thread) for answer