Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR contains the following updates:
3.2.25
->4.0.0
Warning
Some dependencies could not be looked up. Check the Dependency Dashboard for more information.
Release Notes
clap-rs/clap (clap)
v4.5.16
Compare Source
Fixes
derive
feature is missingv4.5.15
Compare Source
Compatiblity
Arg::remove
changed return typesFixes
Arg::remove
return the removed itemv4.5.14
Compare Source
Features
Arg::add
for attaching arbitrary state, like completion hints, toArg
withoutArg
knowing about itv4.5.13
Compare Source
Fixes
#[flatten]
ing an optional#[group(skip)]
v4.5.12
Compare Source
v4.5.11
Compare Source
v4.5.10
Compare Source
v4.5.9
Compare Source
Fixes
v4.5.8
Compare Source
Fixes
v4.5.7
Compare Source
Fixes
num_args
v4.5.6
Compare Source
v4.5.5
Compare Source
Fixes
exclusive
to overriderequired_unless_present
,required_unless_present_any
,required_unless_present_all
v4.5.4
Compare Source
Fixes
#[arg(id)]
attributes againv4.5.3
Compare Source
Internal
heck
v4.5.2
Compare Source
Fixes
v4.5.1
Compare Source
Fixes
derive
feature is missingv4.5.0
Compare Source
Compatibility
v4.4.18
Compare Source
Fixes
usage
feature, ensure the list of required arguments is uniquev4.4.17
Compare Source
Fixes
panic!
when mixingargs_conflicts_with_subcommands
withArgGroup
(which is implicit withderive
) introduced in 4.4.15v4.4.16
Compare Source
Fixes
v4.4.15
Compare Source
Fixes
args_conflicts_with_subcommands
args_conflicts_with_subcommands
when using subcommand short and long flagsv4.4.14
Compare Source
Documentation
find
cookbook entry to allow repeats of flags/optionsFeatures
num_args(0)
on options which allows making them emulate being a flag for position-tracking flagsv4.4.13
Compare Source
Documentation
v4.4.12
Compare Source
Performance
TypedValueParser
for possible values if neededv4.4.11
Compare Source
Features
Command::mut_group
v4.4.10
Compare Source
Documentation
v4.4.9
Compare Source
Fixes
Command::about
under flattened headingshide
when flattening subcommandsv4.4.8
Compare Source
Features
Command::flatten_help
to allowgit stash -h
like help for subcommandsv4.4.7
Compare Source
Performance
v4.4.6
Compare Source
Internal
anstream
v4.4.5
Compare Source
Fixes
name
orlong_flag
, allow ambiguous-looking matches that unambiguously map back to the same commandlong_flag
, don't panicv4.4.4
Compare Source
Internal
terminal_size
to 0.3v4.4.3
Compare Source
Documentation
v4.4.2
Compare Source
Performance
once_cell
dependencyv4.4.1
Compare Source
Fixes
usage
feature, ensure the list of required arguments is uniquev4.4.0
Compare Source
compatibility
v4.3.24
Compare Source
Fixes
--help
with custom templatesv4.3.23
Compare Source
Fixes
UnknownArgumentValueParser
to not error on flag's absencev4.3.22
Compare Source
Features
UnknownArgumentValueParser
for injecting errors for improving the experience with errorsv4.3.21
Compare Source
Features
TryMapValueParser
so the type can be namedv4.3.20
Compare Source
Features
Command::mut_args
for modifying all arguments en massev4.3.19
Compare Source
Fixes
value_terminator
even in the presence of later multiple-value positional argumentsv4.3.18
Compare Source
Fixes
--
in fewer places where it won't workv4.3.17
Compare Source
Fixes
PossibleValue
descriptions in--help
v4.3.16
Compare Source
Fixes
v4.3.15
Compare Source
Features
anstyle
Documentation
v4.3.14
Compare Source
Features
ArgAction::HelpShort
andArgAction::HelpLong
for explicitly specifying which style of help to displayFixes
[OPTIONS]
in usage if a help or versionArgAction
is usedv4.3.13
Compare Source
v4.3.12
Compare Source
Fixes
v4.3.11
Compare Source
Features
num::Wrapping
,Box
, orArc
Box<str>
,Box<OsStr>
, andBox<Path>
v4.3.10
Compare Source
Performance
v4.3.9
Compare Source
Fixes
Command::ignore_errors
no longer masks help/versionv4.3.8
Compare Source
Fixes
infer_long_arg
, rather than arbitrarily picking one, matching the documentation and subcommand's behaviorv4.3.7
Compare Source
Documentation
v4.3.6
Compare Source
Documentation
clio
v4.3.5
Compare Source
ColorChoice::possible_values
is added to simplify things for builder usersFixes
ColorChoice::to_possible_value
no longer includes descriptions, encouraging shorter help where possiblev4.3.4
Compare Source
Features
Error::exit_code
v4.3.3
Compare Source
Features
Command::defer
for delayed initialization of subcommands to reduce startup times of large applications like denov4.3.2
Compare Source
Fixes
--help
with custom templatesv4.3.1
Compare Source
Fixes
value_terminator
even in the presence of later multiple-value positional argumentsv4.3.0
Compare Source
Fixes
last
assertionvalue_terminator
has higher precedence thanallow_hyphen_values
--help
v4.2.7
Compare Source
Fixes
ArgMatches
v4.2.6
Compare Source
Features
impl Eq<std::any::TypeId> for clap_builder::util::AnyValueId
v4.2.5
Compare Source
Fixes
v4.2.4
Compare Source
Documentation
Command::style
v4.2.3
Compare Source
Features
Command::styles
for theming help/errors (behindunstable-styles
)v4.2.2
Compare Source
Internal
v4.2.1
Compare Source
Fixes
v4.2.0
Compare Source
Compatibility
unstable-replace
feature (open to discussion at #2836)unstable-grouped
featureFeatures
StyledStr
to accept text styled with ANSI escape codesCLICOLOR
,CLICOLOR_FORCE
Fixes
v4.1.14
Compare Source
Features
#[group]
raw attribute supportPerformance
clap_builder
was pulled out ofclap
so it could build in parallel toclap_derive
os_str_bytes
dependency was removed for faster builds and smaller binariesv4.1.13
Compare Source
Performance
Command
v4.1.12
Compare Source
Internal
syn
v2Performance
proc-macro-error
dependencyv4.1.11
Compare Source
Internal
bitflags
v4.1.10
Compare Source
Fixes
v4.1.9
Compare Source
Fixes
get_count
/get_flag
v4.1.8
Compare Source
Fixes
deny
lints on the users behalfv4.1.7
Compare Source
Fixes
v4.1.6
Compare Source
Fixes
--help
just because hidden possible values include a descriptionv4.1.5
Compare Source
Fixes
--help
just because a hidden arg has a possible value with a descriptionv4.1.4
Compare Source
Fixes
disable_colored_help
when usingarg_required_else_help
Performance
arg!
macrov4.1.3
Compare Source
Fixes
subcommands
, rather thansubcommand
v4.1.2
Compare Source
Fixes
get_flag
, rather thanget_one::<bool>
v4.1.1
Compare Source
Features
#[group]
raw attribute supportPerformance
clap_builder
was pulled out ofclap
so it could build in parallel toclap_derive
os_str_bytes
dependency was removed for faster builds and smaller binariesv4.1.0
Compare Source
Compatibility
MSRV changed to 1.64.0
For apps with custom
--help
and--version
flags:--help
and--version
changedWhen apps have errors imitating clap's error style:
Features
ArgMatches::get_occurrences
support for argument values to be grouped by their occurrenceFixes
upgrade_from
when arguments / subcommands are explicitly marked as required--help
and--version
(also helps with overflow)v4.0.32
Compare Source
Fixes
required(true)
, consider args that conflict with its groupv4.0.31
Compare Source
Performance
v4.0.30
Compare Source
Fixes
args_conflicts_with_subcommand
v4.0.29
Compare Source
v4.0.28
Compare Source
Fixes
v4.0.27
Compare Source
Features
Arg::value_parser
acceptVec<impl Into<PossibleValue>>
Display
andFromStr
forColorChoice
Fixes
atty
tois-terminal
v4.0.26
Compare Source
Fixes
ContextKind::as_str
v4.0.25
Compare Source
Features
v4.0.24
Compare Source
Fixes
v4.0.23
Compare Source
Fixes
help
subcommandv4.0.22
Compare Source
Fixes
v4.0.21
Compare Source
Features
long_about
andlong_help
attributes, without a value, force using doc comment (before it wouldn't be set if there wasn't anything different than the short help)v4.0.20
Compare Source
Fixes
v4.0.19
Compare Source
Features
ColorChoice
now implementsValueEnum
v4.0.18
Compare Source
Fixes
#[command(skip)]
to also work with enum variants with a valuev4.0.17
Compare Source
Fixes
Arg::last(true)
withArg::value_hint(ValueHint::CommandWithArguments)
v4.0.16
Compare Source
Fixes
Arg::exclusive(true)
should not be exclusive with the argument's ownArgGroup
v4.0.15
Compare Source
Fixes
--
when it doesn't helpv4.0.14
Compare Source
Fixes
ArgGroup
inArgMatches
when explicitly specified, fixing derives handling of option-flattened fields (#4375)v4.0.13
Compare Source
Features
()
for fields to mean "don't read" (#4371)v4.0.12
Compare Source
Features
TypedValueParser::try_map
for when adapting an existingTypedValueParser
can failError::new
,Error::with_cmd
, andError::insert
v4.0.11
Compare Source
Fixes
v4.0.10
Compare Source
Features
#[arg(flatten)]
onOption
types (#4211, #4350)v4.0.9
Compare Source
Fixes
#[command(subcommand)]
like in clap v3v4.0.8
Compare Source
Fixes
Help
andVersion
actionsv4.0.7
Compare Source
Features
Fixes
#[group(skip)]
onParser
derivev4.0.6
Compare Source
Features
#[group(skip)]
(#4279, #4301)v4.0.5
Compare Source
v4.0.4
Compare Source
Fixes
v4.0.3
Compare Source
Fixes
required(true)
, consider args that conflict with its groupv4.0.2
Compare Source
v4.0.1
Compare Source
Features
ColorChoice
now implementsValueEnum
v4.0.0
Compare Source
Highlights
Arg::num_args(range)
Clap has had several ways for controlling how many values will be captured without always being clear on how they interacted, including
Arg::multiple_values(true)
Arg::number_of_values(4)
Arg::min_values(2)
Arg::max_values(20)
Arg::takes_value(true)
These have now all been collapsed into
Arg::num_args
which accepts bothsingle values and ranges of values.
num_args
controls how many raw argumentson the command line will be captured as values per occurrence and independent
of value delimiters.
See Issue 2688 for more background.
Polishing Help
Clap strives to give a polished CLI experience out of the box with little
ceremony. With some feedback that has accumulated over time, we took this
release as an opportunity to re-evaluate our
--help
output to make sure it ismeeting that goal.
In doing this evaluation, we wanted to keep in mind:
Before:
After:
--version
is available for showing the same thing (if the program has a version set)In talking to users, we found some that liked clap's
man
-like experience.When deviating from this, we are making the assumption that those are more
power users and that the majority of users wouldn't look as favorably on being
consistent with
man
.See Issue 4132 for more background.
More Dynamicism
Clap's API has focused on
&str
for performance but this can makedealing with owned data difficult, like
#[arg(default_value_t)]
generating aString from the default value.
Additionally, to avoid
ArgMatches
from borrowing (and for some features wedecided to forgo), clap took the
&str
argument IDs and hashed them. Thisprevented us from providing a usable API for iterating over existing arguments.
Now clap has switched to a string newtype that gives us the flexibility to
decide whether to use
&'static str
,Cow<'static, str>
for fast dynamic behavior, orBox<str>
for dynamic behavior with small binary size.As an extension of that work, you can now call
ArgMatches::ids
to iterateover the arguments and groups that were found when parsing. The newtype
Id
was used to prevent some classes of bugs and to make it easier to understand
when opaque Ids are used vs user-visible strings.
Clearing Out Deprecations
Instead of doing all development on clap 4.0.0, we implemented a lot of new features during clap 3's development, deprecating the old API while introducing the new API, including:
ArgAction
ValueParser
APIPathBuf
(allowing invalid UTF-8)AppSettings
andArgSettings
enums with getters/settersMigrating
Steps:
-h
and--help
output at a minimum (recommendation: trycmd for snapshot testing)arg.action(ArgAction::...)
on each argument (StoreValue
for options andIncOccurrences
for flags)cargo check --features clap/deprecated
and resolve all deprecation warningsdefault-features = false
, runcargo add clap -F help,usage,error-context
cargo add clap -F wrap_help
unless you want to hard code line wrapsExample test (derive):
Example test (builder):
Note: the idiomatic / recommended way of specifying different types of args in the Builder API has changed:
Before
After:
In particular,
num_args
(the replacement fortakes_value
) will default appropriatelyfrom the
ArgAction
and generally only needs to be set explicitly for theother
num_args
use cases.Breaking Changes
Subtle changes (i.e. compiler won't catch):
arg!
now sets one of (#3795):ArgAction::SetTrue
, requiringArgMatches::get_flag
instead ofArgMatches::is_present
ArgAction::Count
, requiringArgMatches::get_count
instead ofArgMatches::occurrences_of
ArgAction::Set
, requiringArgMatches::get_one
instead ofArgMatches::value_of
ArgAction::Append
, requiringArgMatches::get_many
instead ofArgMatches::values_of
ArgAction::Set
,ArgAction::SetTrue
, andArg::Action::SetFalse
nowconflict by default to be like
ArgAction::StoreValue
andArgAction::IncOccurrences
, requiringcmd.args_override_self(true)
to override instead (#4261)Arg
s default action isArgAction::Set
, rather thanArgAction::IncOccurrence
to reduce confusing magic through consistency (#2687, #4032, see also #3977)mut_arg
can no longer be used to customize help and version arguments, instead disable them (Command::disable_help_flag
,Command::disable_version_flag
) and provide your own (#4056)Command
,Arg
,ArgGroup
, andPossibleValue
, assuming'static
.string
feature flag will enable support forString
s (#1041, #2150, #4223)arg!(--flag <value>)
is now optional, instead of required. Add.required(true)
at the end to restore the original behavior (#4206)help
,usage
anderror-context
, requiring adding them back in ifdefault-features = false
(#4236)""
argument for external subcommands to make it easier to distinguish them from built-in commands (#3263)Arg::allow_hyphen_values
, to be consistent withCommand::allow_hyphen_values
(#4187)Arg::value_terminator
must be its own argument on the CLI rather than being in a delimited list (#4025)wrap_help
feature flag, either enable it or hard code your wraps (#4258)DeriveDisplayOrder
the default and removed the setting. To sort help, setnext_display_order(None)
(#2808)Command::next_display_order
instead ofDeriveDisplayOrder
and using its own initial display order value (#2808)Command::help_template
(#4132)Command::help_template
,Arg::help_heading
, andCommand::subcommand_help_heading
(#4132)COMMAND
for the value name. To get the old behavior, seeCommand::subcommand_help_heading
andArg::subcommand_value_name
(#4132, #4155)Command::help_template
. (#4132, #4160)--help
and--version
like anyArgAction::SetTrue
flag (#3776)Arg::id
asverbatim
casing, requiring updating of string references to other args like inconflicts_with
orrequires
(#3282)ValueEnum
variants will now show up in--help
(#3312)Args
, andArgGroup
is created using the type's name, reserving it for future use (#2621, #4209)next_help_heading
can now leak out of a#[clap(flatten)]
, like all other command settings (#4222)Easier to catch changes:
ArgMatches
now returns the argId
s, rather than the values to reduce overhead and offer more flexibility. (#4072)Arg::number_of_values
(average-across-occurrences) toArg::num_args
(per-occurrence) (raw CLI args, not parsed values) (#2688, #4023)num_args(0)
no longer impliestakes_value(true).multiple_values(true)
(#4023)num_args(1)
no longer impliesmultiple_values(true)
(#4023)Arg::min_values
(across all occurrences) withArg::num_args(N..)
(per occurrence) to reduce confusion over different value count APIs (#4023)Arg::max_values
(across all occurrences) withArg::num_args(1..=M)
(per occurrence) to reduce confusion over different value count APIs (#4023)Arg::multiple_values(true)
withArg::num_args(1..)
andArg::multiple_values(false)
withArg::num_args(0)
to reduce confusion over different value count APIs (#4023)Arg::takes_value(true)
withArg::num_args(1)
andArg::takes_value(false)
withArg::num_args(0)
to reduce confusion over different value count APIsArg::require_value_delimiter
, either users could useArg::value_delimiter
or implement a custom parser withTypedValueParser
as it was mostly to makemultiple_values(true)
act likemultiple_values(false)
and isn't needed anymore (#4026)Arg::new("help")
andArg::new("version")
no longer implicitly disable thebuilt-in flags and be copied to all subcommands, instead disable
the built-in flags (
Command::disable_help_flag
,Command::disable_version_flag
) and mark the custom flags asglobal(true)
. (#4056)Arg::short('h')
no longer implicitly disables the short flag for help,instead disable
the built-in flags (
Command::disable_help_flag
,Command::disable_version_flag
) provide your ownArg::new("help").long("help").action(ArgAction::Help).global(true)
. (#4056)ArgAction::SetTrue
andArgAction::SetFalse
now prioritizeArg::default_missing_value
over their standard behavior (#4000)Arg::requires_ifs
andArg::default_value*_ifs*
to taking anArgPredicate
, removing ambiguity withNone
when accepting owned and borrowed types (#4084)PartialEq
andEq
fromCommand
so we could change external subcommands to use aValueParser
(#3990)Arg
,Command
, andArgGroup
calls were switched from accepting&[]
to[]
viaIntoIterator
to be more flexible (#4072)Arg::short_aliases
and other builder functions that took&[]
need the&
dropped (#4081)ErrorKind
andResult
moved into theerror
moduleErrorKind::EmptyValue
replaced withErrorKind::InvalidValue
to remove an unnecessary special case (#3676, #3968)ErrorKind::UnrecognizedSubcommand
replaced withErrorKind::InvalidSubcommand
to remove an unnecessary special case (#3676)allow_external_subcommands
fromString
toOsString
as that is less likely to cause bugs in user applications (#3990)Command::render_usage
now returns aStyledStr
(#4248)parse
tovalue_parser
, removingparse
support (#3827, #3981)#[clap(value_parser)]
and#[clap(action)]
are now redundantsubcommand_required(true).arg_required_else_help(true)
is set instead ofSubcommandRequiredElseHelp
to give more meaningful errors when subcommands are missing and to reduce redundancy (#3280)arg_enum
attribute in favor ofvalue_enum
to match the new name (we didn't have support in v3 to mark it deprecated) (#4127)Arg::default_missing_value
didn't requirenum_args(0..=N)
, now it does (#4023)Arg::long
are no longer allowed (#3691)value_names
thannum_args
(#2695)ArgAction::Version
is used#[track_caller]
s to make it easier to debug assertsoverrides_with
IDs are validoverrides_with
now that Actions replace itmut_arg
receiving an invalid arg ID ormut_subcommand
receiving an invalid command nameCompatibility
MSRV is now 1.60.0
Deprecated
Arg::use_value_delimiter
in favor ofArg::value_delimiter
to avoid having multiple ways of doing the same thingArg::requires_all
in favor ofArg::requires_ifs
now that it takes anArgPredicate
to avoid having multiple ways of doing the same thingArg::number_of_values
in favor ofArg::num_args
to clarify semantic differencesdefault_value_os
,default_values_os
,default_value_if_os
, anddefault_value_ifs_os
as the non_os
variants now accept either astr
or anOsStr
(#4141)Arg::env_os
in favor ofArg::env
Command::dont_collapse_args_in_usage
is now the default (#4151)Command::trailing_var_arg
in favor ofArg::trailing_var_arg
to make it clearer which arg it is meant to apply to (#4187)Command::allow_hyphen_values
in favor ofArg::allow_hyphen_values
to make it clearer which arg it is meant to apply to (#4187)Command::allow_negative_numbers
in favor ofArg::allow_negative_numbers
to make it clearer which arg it is meant to apply to (#4187)Command::write_help
andCommand::write_long_help
in favor ofCommand::render_help
andCommand::render_long_help
(#4248)structopt
andclap
attributes in favor of the more specificcommand
,arg
, andvalue
to open the door for more features and clarify relationship to the builder (#1807, #4180)#[clap(value_parser)]
and#[clap(action)]
defaulted attributes (its the default) (#3976)Behavior Changes
wrap_help
feature, if the terminal size cannot be determined,LINES
andCOLUMNS
variables are used (#4186)Features
Arg::num_args
now accepts ranges, allowing setting both the minimum and maximum number of values per occurrence (#2688, #4023)value_parser
s forArgAction::SetTrue
/ArgAction::SetFalse
(#4092)From<&OsStr>
,From<OsString>
,From<&str>
, andFrom<String>
tovalue_parser!
(#4257)Command
,Arg
,ArgGroup
,PossibleValue
, etc without managing lifetimes with thestring
feature flag (#2150, #4223)error-context
,help
andusage
feature flags that can be turned off for smaller binaries (#4236)StyledStr::ansi()
toDisplay
with ANSI escape codes (#4248)Error::apply
for changing the formatter for dropping binary size (#4111)Error::render
for formatting the error into aStyledStr
PossibleValue::help
in long help (--help
) (#3312){tab}
variable forCommand::help_template
(#4161)Command::render_help
andCommand::render_long_help
for formatting the error into aStyledStr
(#3873, #4248)Command::render_usage
now returns aStyledStr
(#4248)Fixes
required
is not used with conditional required settings (#3660)cmd.allow_invalid_for_utf8_external_subcommands
withcmd.external_subcommand_value_parser
(#3733)Arg::default_missing_value
now applies per occurrence rather than if a value is missing across all occurrences (#3998)arg!(--long [value])
to accept0..=1
per occurrence rather than across all occurrences, making it safe to use withArgAction::Append
(#4001)OsStr
s forArg::{required_if_eq,required_if_eq_any,required_if_eq_all}
(#4084)wrap_help
feature, if the terminal size cannot be determined,LINES
andCOLUMNS
variables are used (#4186)Command::display_name
in the help title rather thanCommand::bin_name
ArgAction::Count
by adding an...
(#4003)cmd help help
(#4131)[positional]
in list when relevant (#4144)[positional]
in usage (#4151)Configuration
📅 Schedule: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).
🚦 Automerge: Disabled by config. Please merge this manually once you are satisfied.
♻ Rebasing: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 Ignore: Close this PR and you won't be reminded about this update again.
This PR was generated by Mend Renovate. View the repository job log.