Parsing two var args separated by `--`

[mkovaxx]

Please complete the following tasks

• I have searched the discussions
• I have searched the open and rejected issues

Rust Version

rustc 1.90.0 (1159e78c4 2025-09-14)

Clap Version

4.5.53

Minimal reproducible code

repo: https://github.com/mkovaxx/repro-clap-two-varargs

use clap::Parser;

fn main() {
    let args = CliWithTwoVarArgs::parse_from(std::env::args());
    println!("BEFORE: {:?}", args.before);
    println!("AFTER: {:?}", args.after);
}

#[derive(Clone, Debug, Parser)]
pub struct CliWithTwoVarArgs {
    #[arg(
        value_name = "ARGS_BEFORE",
        num_args = 0..,
        allow_hyphen_values = true,
        help = "Options before `--`",
    )]
    pub before: Vec<String>,

    #[arg(
        value_name = "ARGS_AFTER",
        last = true,
        num_args = 0..,
        allow_hyphen_values = true,
        help = "Options after `--`",
    )]
    pub after: Vec<String>,
}

#[cfg(test)]
mod test {
    use super::*;

    const BIN_NAME: &str = "main";

    #[test]
    fn parse_some_stuff() {
        let args = CliWithTwoVarArgs::parse_from([
            BIN_NAME,
            "--release",
            "--",
            "--expand-errors",
            "--rlimit=100",
        ]);

        assert_eq!(args.before, vec!["--release".to_owned()]);
        assert_eq!(
            args.after,
            vec!["--expand-errors".to_owned(), "--rlimit=100".to_owned()]
        );
    }
}

Steps to reproduce the bug with the above code

cargo test

Actual Behaviour

All arguments, including the --, are in the before field, and after is empty.

Expected Behaviour

Arguments before the -- marker should be in the before field, and arguments after in the after field.

Additional Context

The expectation above is informed by the output of --help:

Usage: repro-clap-two-varargs [ARGS_BEFORE]... [-- [ARGS_AFTER]...]

Arguments:
  [ARGS_BEFORE]...  Options before `--`
  [ARGS_AFTER]...   Options after `--`

Options:
  -h, --help  Print help

Debug Output

running 1 test
[clap_builder::builder::command]Command::_do_parse
[clap_builder::builder::command]Command::_build: name="repro-clap-two-varargs"
[clap_builder::builder::command]Command::_propagate:repro-clap-two-varargs
[clap_builder::builder::command]Command::_check_help_and_version:repro-clap-two-varargs expand_help_tree=false
[clap_builder::builder::command]Command::long_help_exists
[clap_builder::builder::command]Command::_check_help_and_version: Building default --help
[clap_builder::builder::command]Command::_propagate_global_args:repro-clap-two-varargs
[clap_builder::builder::debug_asserts]Command::_debug_asserts
[clap_builder::builder::debug_asserts]Arg::_debug_asserts:before
[clap_builder::builder::debug_asserts]Arg::_debug_asserts:after
[clap_builder::builder::debug_asserts]Arg::_debug_asserts:help
[clap_builder::builder::debug_asserts]Command::_verify_positionals
[clap_builder::parser::parser]Parser::get_matches_with
[clap_builder::parser::parser]Parser::parse
[clap_builder::parser::parser]Parser::get_matches_with: Begin parsing '"--release"'
[clap_builder::parser::parser]Parser::possible_subcommand: arg=Ok("--release")
[clap_builder::parser::parser]Parser::get_matches_with: sc=None
[clap_builder::parser::parser]Parser::parse_long_arg
[clap_builder::parser::parser]Parser::parse_long_arg: Does it contain '='...
[clap_builder::parser::parser]Parser::possible_long_flag_subcommand: arg="release"
[clap_builder::parser::parser]Parser::parse_long_args: positional at 1 allows hyphens
[clap_builder::parser::parser]Parser::get_matches_with: After parse_long_arg MaybeHyphenValue
[clap_builder::parser::parser]Parser::get_matches_with: Positional counter...1
[clap_builder::parser::parser]Parser::get_matches_with: Low index multiples...false
[clap_builder::parser::parser]Parser::get_matches_with: Begin parsing '"--"'
[clap_builder::parser::parser]Parser::get_matches_with: Positional counter...1
[clap_builder::parser::parser]Parser::get_matches_with: Low index multiples...false
[clap_builder::parser::parser]Parser::get_matches_with: Begin parsing '"--expand-errors"'
[clap_builder::parser::parser]Parser::parse_long_arg
[clap_builder::parser::parser]Parser::parse_long_arg: prior arg accepts hyphenated values
[clap_builder::parser::parser]Parser::get_matches_with: After parse_long_arg MaybeHyphenValue
[clap_builder::parser::parser]Parser::get_matches_with: Positional counter...1
[clap_builder::parser::parser]Parser::get_matches_with: Low index multiples...false
[clap_builder::parser::parser]Parser::get_matches_with: Begin parsing '"--rlimit=100"'
[clap_builder::parser::parser]Parser::parse_long_arg
[clap_builder::parser::parser]Parser::parse_long_arg: prior arg accepts hyphenated values
[clap_builder::parser::parser]Parser::get_matches_with: After parse_long_arg MaybeHyphenValue
[clap_builder::parser::parser]Parser::get_matches_with: Positional counter...1
[clap_builder::parser::parser]Parser::get_matches_with: Low index multiples...false
[clap_builder::parser::parser]Parser::resolve_pending: id="before"
[clap_builder::parser::parser]Parser::react action=Append, identifier=Some(Index), source=CommandLine
[clap_builder::parser::parser]Parser::remove_overrides: id="before"
[clap_builder::parser::arg_matcher]ArgMatcher::start_custom_arg: id="before", source=CommandLine
[clap_builder::builder::command]Command::groups_for_arg: id="before"
[clap_builder::parser::arg_matcher]ArgMatcher::start_custom_arg: id="CliWithTwoVarArgs", source=CommandLine
[clap_builder::parser::parser]Parser::push_arg_values: ["--release", "--", "--expand-errors", "--rlimit=100"]
[clap_builder::parser::parser]Parser::add_single_val_to_arg: cur_idx:=1
[clap_builder::parser::parser]Parser::add_single_val_to_arg: cur_idx:=2
[clap_builder::parser::parser]Parser::add_single_val_to_arg: cur_idx:=3
[clap_builder::parser::parser]Parser::add_single_val_to_arg: cur_idx:=4
[clap_builder::parser::arg_matcher]ArgMatcher::needs_more_vals: o=before, pending=0
[clap_builder::parser::arg_matcher]ArgMatcher::needs_more_vals: expected=0.., actual=0
[clap_builder::parser::parser]Parser::react not enough values passed in, leaving it to the validator to complain
[clap_builder::parser::parser]Parser::add_defaults
[clap_builder::parser::parser]Parser::add_defaults:iter:before:
[clap_builder::parser::parser]Parser::add_default_value: doesn't have conditional defaults
[clap_builder::parser::parser]Parser::add_default_value:iter:before: doesn't have default vals
[clap_builder::parser::parser]Parser::add_defaults:iter:after:
[clap_builder::parser::parser]Parser::add_default_value: doesn't have conditional defaults
[clap_builder::parser::parser]Parser::add_default_value:iter:after: doesn't have default vals
[clap_builder::parser::parser]Parser::add_defaults:iter:help:
[clap_builder::parser::parser]Parser::add_default_value: doesn't have conditional defaults
[clap_builder::parser::parser]Parser::add_default_value:iter:help: doesn't have default vals
[clap_builder::parser::validator]Validator::validate
[clap_builder::builder::command]Command::groups_for_arg: id="before"
[clap_builder::parser::validator]Conflicts::gather_direct_conflicts id="before", conflicts=[]
[clap_builder::parser::validator]Conflicts::gather_direct_conflicts id="CliWithTwoVarArgs", conflicts=[]
[clap_builder::parser::validator]Validator::validate_conflicts
[clap_builder::parser::validator]Validator::validate_exclusive
[clap_builder::parser::validator]Validator::validate_conflicts::iter: id="before"
[clap_builder::parser::validator]Conflicts::gather_conflicts: arg="before"
[clap_builder::parser::validator]Conflicts::gather_conflicts: conflicts=[]
[clap_builder::parser::validator]Validator::validate_required: required=ChildGraph([])
[clap_builder::parser::validator]Validator::gather_requires
[clap_builder::parser::validator]Validator::gather_requires:iter:"before"
[clap_builder::parser::validator]Validator::gather_requires:iter:"CliWithTwoVarArgs"
[clap_builder::parser::validator]Validator::gather_requires:iter:"CliWithTwoVarArgs":group
[clap_builder::parser::validator]Validator::validate_required: is_exclusive_present=false
[clap_builder::parser::arg_matcher]ArgMatcher::get_global_values: global_arg_vec=[]
test test::parse_some_stuff ... FAILED

failures:

---- test::parse_some_stuff stdout ----

thread 'test::parse_some_stuff' panicked at src/main.rs:45:9:
assertion left == right failed
left: ["--release", "--", "--expand-errors", "--rlimit=100"]
right: ["--release"]
note: run with RUST_BACKTRACE=1 environment variable to display a backtrace

failures:
test::parse_some_stuff

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

error: test failed, to rerun pass --bin repro-clap-two-varargs

[epage]

You can parse two arguments separated by a -- but the problem is that by using allow_hyphen_values, you are telling clap to accept -flag, --flag, and even --.

One workaround is to have just one positional argument and to do the splitting yourself after the fact.

Adding a flag to specialize the behavior of allow_hyphen_values seems to specialized, especially in light of there being a workaround.

[bsdinis]

One relevant issue with the workaround is that it removes the helpful message on the generated cli help.

[mkovaxx]

Proposal: allow_dash_dash_as_value

Motivation

On Unix-like systems, a bare -- has a long-standing conventional meaning as the end-of-options delimiter. Many users rely on -- to reliably terminate option parsing and do not expect it to be treated as a positional value.

The POSIX Utility Syntax Guidelines explicitly describe this convention. Guideline 10 states:

The first -- argument that is not an option-argument should be accepted as a delimiter indicating the end of options.

This framing treats -- as a syntactic marker, not as an ordinary operand. While POSIX does not formally forbid a utility from interpreting -- as a value, decades of practice and user expectation rely on -- having this special meaning.

Currently, enabling allow_hyphen_values causes -- to be accepted as a value for a positional argument. While this may be useful in some specialized CLIs, it breaks with common conventions and makes the behavior of -- less predictable in otherwise standard command-line interfaces.

Proposal

Introduce an explicit per-argument setting, allow_dash_dash_as_value, to control whether a bare -- may be consumed as a value:

• Default: enabled, preserving current behavior for compatibility.
• When disabled: -- always acts as the end-of-options delimiter, even when allow_hyphen_values is enabled.

This separates two concerns that are currently conflated:

• accepting option-looking tokens as values
• whether the special -- sentinel may be treated as a literal value

Benefits

• Helps align clap's behavior with widely held Unix CLI conventions in the common case.
• Keeps the "-- as a value" behavior available for specialized CLIs.
• Remains fully backwards-compatible.
• Enables standard argument-forwarding and ---split patterns.

Draft Changes

#6222

[epage]

Clap already treats it as a syntax, just like -shorts and --longs. The caller has already opted out of that with allow_hyphen_values which can be useful for forwarding arguments to another program. Sometimes people want to only capture values that happen to start with a - and we have limited support via allow_negative_numbers.

What I've not seen is a description of the end-user problem being solved here. An example cli was given and I gave a workaround.

I've also already said that, at least with the info on hand so far, the example CLI seems too specialized to bake in.

[mkovaxx]

What I've not seen is a description of the end-user problem being solved here.

Given the following help output:

Usage: cli [ARGS_BEFORE]... [-- [ARGS_AFTER]...]

and the following invocation:

cli one two three -- four five

what would a user expect regarding the values assigned to ARGS_BEFORE and ARGS_AFTER?

What about the following invocation?

cli --one --two --three -- --four --five

[epage]

That is not an end-user problem but an implementation problem