fix(deps): update rust crate clap to v4
-
Review changes -
-
Download -
Patches
-
Plain diff
This MR contains the following updates:
Package | Type | Update | Change |
---|---|---|---|
clap | dependencies | major |
3.1 -> 4.0
|
Release Notes
clap-rs/clap (clap)
v4.5.27
Documentation
- Iterate on tutorials and reference based on feedback
v4.5.26
Fixes
-
(error) Reduce binary size with the
suggestions
feature
v4.5.25
Fixes
- (help) Reduce binary size
v4.5.24
Fixes
-
(parser) Correctly handle defaults with
ignore_errors(true)
and when a suggestion is provided for an unknown argument
v4.5.23
Fixes
-
(parser) When check
allow_negative_numbers
, allowE
again
v4.5.22
Fixes
- (assert) Catch bugs with arguments requiring themself
v4.5.21
Fixes
-
(parser) Ensure defaults are filled in on error with
ignore_errors(true)
v4.5.20
Features
-
(unstable) Add
CommandExt
v4.5.19
Internal
- Update dependencies
v4.5.18
Features
-
(builder) Expose
Arg::get_display_order
andCommand::get_display_order
v4.5.17
Fixes
- (help) Style required argument groups
- (derive) Improve error messages when unsupported fields are used
v4.5.16
Fixes
-
(derive) Improve error messages when
derive
feature is missing
v4.5.15
Compatiblity
-
(unstable-ext)
Arg::remove
changed return types
Fixes
-
(unstable-ext) Make
Arg::remove
return the removed item
v4.5.14
Features
-
(unstable-ext) Added
Arg::add
for attaching arbitrary state, like completion hints, toArg
withoutArg
knowing about it
v4.5.13
Fixes
-
(derive) Improve error message when
#[flatten]
ing an optional#[group(skip)]
- (help) Properly wrap long subcommand descriptions in help
v4.5.12
v4.5.11
v4.5.10
v4.5.9
Fixes
- (error) When defining a custom help flag, be sure to suggest it like we do the built-in one
v4.5.8
Fixes
- Reduce extra flushes
v4.5.7
Fixes
- Clean up error message when too few arguments for
num_args
v4.5.6
v4.5.5
Fixes
- Allow
exclusive
to overriderequired_unless_present
,required_unless_present_any
,required_unless_present_all
v4.5.4
Fixes
-
(derive) Allow non-literal
#[arg(id)]
attributes again
v4.5.3
Internal
-
(derive) Update
heck
v4.5.2
Documentation
- Iterate on tutorials and reference based on feedback
v4.5.1
Internal
- Update dependencies
v4.5.0
Compatibility
- Update MSRV to 1.74
v4.4.18
Fixes
-
(error) When lacking
usage
feature, ensure the list of required arguments is unique
v4.4.17
Fixes
- Fix
panic!
when mixingargs_conflicts_with_subcommands
withArgGroup
(which is implicit withderive
) introduced in 4.4.15
v4.4.16
Fixes
- Ensure invalid escape sequences in user-defined strings are correctly stripped when terminal doesn't support color
v4.4.15
Fixes
- Improve error for
args_conflicts_with_subcommands
- Ensure we error for
args_conflicts_with_subcommands
when using subcommand short and long flags
v4.4.14
Documentation
- Fix
find
cookbook entry to allow repeats of flags/options
Features
- Allow
num_args(0)
on options which allows making them emulate being a flag for position-tracking flags
v4.4.13
Documentation
- Fix link to structopt migration guide
v4.4.12
Performance
- Only ask
TypedValueParser
for possible values if needed
v4.4.11
Features
- Add
Command::mut_group
v4.4.10
Documentation
- Link out to changelog
- Cross link derive's attribute reference to derive tutorial
v4.4.9
Fixes
-
(help) Show correct
Command::about
under flattened headings -
(help) Respect
hide
when flattening subcommands
v4.4.8
Features
- Add
Command::flatten_help
to allowgit stash -h
like help for subcommands
v4.4.7
Performance
- Reduced code size
v4.4.6
Internal
- Upgrade
anstream
v4.4.5
Fixes
-
(parser) When inferring subcommand
name
orlong_flag
, allow ambiguous-looking matches that unambiguously map back to the same command -
(parser) When inferring subcommand
long_flag
, don't panic - (assert) Clarify what action is causing a positional that doesn't set values which is especially useful for derive users
v4.4.4
Internal
- Update
terminal_size
to 0.3
v4.4.3
Documentation
- (derive) Clarify use of attributes within the tutorial
- Split sections in the builder and derive tutorials into separate modules
v4.4.2
Performance
- Improve build times by removing
once_cell
dependency
v4.4.1
Fixes
-
(error) When lacking
usage
feature, ensure the list of required arguments is unique
v4.4.0
compatibility
- update msrv to 1.70.0
v4.3.24
Fixes
- Ensure column padding is preserved in
--help
with custom templates
v4.3.23
Fixes
- Fixed
UnknownArgumentValueParser
to not error on flag's absence
v4.3.22
Features
- Add
UnknownArgumentValueParser
for injecting errors for improving the experience with errors
v4.3.21
Features
- Expose
TryMapValueParser
so the type can be named
v4.3.20
Features
-
Command::mut_args
for modifying all arguments en masse
v4.3.19
Fixes
-
(parse) Respect
value_terminator
even in the presence of later multiple-value positional arguments
v4.3.18
Fixes
-
(parse) Suggest
--
in fewer places where it won't work
v4.3.17
Fixes
-
(help) Address a regression in wrapping
PossibleValue
descriptions in--help
v4.3.16
Fixes
- Don't assert when stateful value parsers fail on defaults (e.g. checking if a path exists)
v4.3.15
Features
-
(unstable-styles) Re-export
anstyle
Documentation
- (unstable-styles) Provide more examples
v4.3.14
Features
-
ArgAction::HelpShort
andArgAction::HelpLong
for explicitly specifying which style of help to display
Fixes
- Skip
[OPTIONS]
in usage if a help or versionArgAction
is used
v4.3.13
v4.3.12
Fixes
- (derive) Don't error on enum variant field attributes
v4.3.11
Features
-
(derive) Support fields wrapped in
num::Wrapping
,Box
, orArc
-
(derive) Support
Box<str>
,Box<OsStr>
, andBox<Path>
v4.3.10
Performance
- Drop a dependency, reducing binary size by 1.3 KiB
v4.3.9
Fixes
-
Command::ignore_errors
no longer masks help/version
v4.3.8
Fixes
- Error on ambiguity with
infer_long_arg
, rather than arbitrarily picking one, matching the documentation and subcommand's behavior
v4.3.7
Documentation
- Further clarify magic behavior in derive tutorial
- Further clarify derive API's relationship to builder within the tutorial
v4.3.6
Documentation
- Suggest
clio
v4.3.5
-
ColorChoice::possible_values
is added to simplify things for builder users
Fixes
-
ColorChoice::to_possible_value
no longer includes descriptions, encouraging shorter help where possible
v4.3.4
Features
- Add
Error::exit_code
v4.3.3
Features
-
Command::defer
for delayed initialization of subcommands to reduce startup times of large applications like deno
v4.3.2
Fixes
- Ensure column padding is preserved in
--help
with custom templates
v4.3.1
Fixes
-
(parse) Respect
value_terminator
even in the presence of later multiple-value positional arguments
v4.3.0
Fixes
- (assert) Allow multiple, value-terminated, positional arguments
-
(assert) Clear up language on
last
assertion - (parser) Correctly assign values to arguments when using multiple, value-termianted, positional arguments
-
(parser) Ensure
value_terminator
has higher precedence thanallow_hyphen_values
-
(help) Only use next-line-help on subcommand list when explicitly specified, not just with
--help
- (help) Correctly align possible values list
- (help) Don't waste code, vertical space in moving possible value descriptions to next line
v4.2.7
Fixes
- Correctly track remaining length for iterators provided by
ArgMatches
v4.2.6
Features
impl Eq<std::any::TypeId> for clap_builder::util::AnyValueId
v4.2.5
Fixes
- Improve panic when a group requires a non-existent ID
v4.2.4
Documentation
- Corrected docs for
Command::style
v4.2.3
Features
-
Command::styles
for theming help/errors (behindunstable-styles
)
v4.2.2
Internal
- Update dependencies
v4.2.1
Fixes
- Don't highlight uninteresting parts of the error message
v4.2.0
Compatibility
- Removed the languishing
unstable-replace
feature (open to discussion at #2836) - Removed the stablized
unstable-grouped
feature
Features
- Allow any
StyledStr
to accept text styled with ANSI escape codes - Respect
CLICOLOR
,CLICOLOR_FORCE
Fixes
- Lighten the tone for "unexpected argument" errors (open to discussion at #4638)
v4.1.14
Features
-
(derive)
#[group]
raw attribute support
Performance
-
(derive)
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 binaries
v4.1.13
Performance
- Reduce repeated alloc calls when building a
Command
- Reduce duplicate dependencies for faster builds
v4.1.12
Internal
-
(derive) Update to
syn
v2
Performance
-
(derive) Faster build times by dropping
proc-macro-error
dependency
v4.1.11
Internal
- Update
bitflags
v4.1.10
Fixes
- (help) On Windows, avoid underlined text artifacts
v4.1.9
Fixes
-
(assert) Improve the assert when using the wrong action with
get_count
/get_flag
v4.1.8
Fixes
-
(derive) Don't
deny
lints on the users behalf
v4.1.7
Fixes
- (derive) Hide some nightly clippy warnings
v4.1.6
Fixes
-
(help) Don't show long help for
--help
just because hidden possible values include a description
v4.1.5
Fixes
-
(help) Don't show long help for
--help
just because a hidden arg has a possible value with a description
v4.1.4
Fixes
-
(help) Respect
disable_colored_help
when usingarg_required_else_help
Performance
- Speed up compiling
arg!
macro
v4.1.3
Fixes
- (error) Improve suggested flag/value/subcommand when two share a long preifx
-
(error) When suggesting one of several subcommands, use the plural
subcommands
, rather thansubcommand
v4.1.2
Fixes
- In documentation, refer to
get_flag
, rather thanget_one::<bool>
v4.1.1
Features
-
(derive)
#[group]
raw attribute support
Performance
-
(derive)
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 binaries
v4.1.0
Compatibility
MSRV changed to 1.64.0
For apps with custom --help
and --version
flags:
- Descriptions for
--help
and--version
changed
When apps have errors imitating clap's error style:
- Error message style was changed, including
- Moving away from "did you mean" to tips
- Leading letter is lower case
- "For more" added some punctuation
Features
-
ArgMatches::get_occurrences
support for argument values to be grouped by their occurrence
Fixes
-
(derive) Allow
upgrade_from
when arguments / subcommands are explicitly marked as required -
(help) Try be more clearer and succinct with
--help
and--version
(also helps with overflow) - (error) Try to be more clearer and succinct with error messages
- (error) Officially adopt an error style guide
v4.0.32
Fixes
-
(parser) When overriding
required(true)
, consider args that conflict with its group
v4.0.31
Performance
- Speed up parsing when a lot of different flags are present (100 unique flags)
v4.0.30
Fixes
-
(error) Improve error for
args_conflicts_with_subcommand
v4.0.29
v4.0.28
Fixes
- Fix wasm support which was broken in 4.0.27
v4.0.27
Features
- Have
Arg::value_parser
acceptVec<impl Into<PossibleValue>>
- Implement
Display
andFromStr
forColorChoice
Fixes
- Remove soundness issue by switching from
atty
tois-terminal
v4.0.26
Fixes
-
(error) Fix typos in
ContextKind::as_str
v4.0.25
Features
- (error) Report available subcommands when required subcommand is missing
v4.0.24
Fixes
- Avoid panic when printing an argument that isn't built
v4.0.23
Fixes
- Don't panic on reporting invalid-long errors when followed by invalid UTF8
-
(help) Clarified argument to
help
subcommand
v4.0.22
Fixes
- (help) Don't overflow into next-line-help early due to stale (pre-v4) padding calculations
v4.0.21
Features
-
(derive)
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
Fixes
- (derive) Allow defaulted value parser for '()' fields
v4.0.19
Features
-
ColorChoice
now implementsValueEnum
v4.0.18
Fixes
-
(derive) Allow
#[command(skip)]
to also work with enum variants with a value
v4.0.17
Fixes
- Allow using
Arg::last(true)
withArg::value_hint(ValueHint::CommandWithArguments)
v4.0.16
Fixes
-
Arg::exclusive(true)
should not be exclusive with the argument's ownArgGroup
v4.0.15
Fixes
-
(error) Don't suggest
--
when it doesn't help - (error) Be more consistent in quoting, punctuation, and indentation in errors
v4.0.14
Fixes
- Only put
ArgGroup
inArgMatches
when explicitly specified, fixing derives handling of option-flattened fields (#4375)
v4.0.13
Features
-
(derive) Allow
()
for fields to mean "don't read" (#4371)
v4.0.12
Features
- Added
TypedValueParser::try_map
for when adapting an existingTypedValueParser
can fail -
(error) Create errors like clap with
Error::new
,Error::with_cmd
, andError::insert
v4.0.11
Fixes
- (help) Fix wrapping calculations with ANSI escape codes
v4.0.10
Features
v4.0.9
Fixes
-
(derive) Process doc comments for
#[command(subcommand)]
like in clap v3
v4.0.8
Fixes
-
(derive) Remove a low-value assert preventing defaulting
Help
andVersion
actions
v4.0.7
Features
- (derive) Populate implicit ArgGroup (#3165)
Fixes
-
(derive) Support
#[group(skip)]
onParser
derive - (derive) Tell users about implicit arg groups when running into group name conflicts
- (error) Don't report unrelated groups in conflict or requires errors
v4.0.6
Features
v4.0.5
v4.0.4
Fixes
- (error) Specialize the self-conflict error to look like clap v3
v4.0.3
Fixes
-
(parser) When overriding
required(true)
, consider args that conflict with its group
v4.0.2
v4.0.1
Features
-
ColorChoice
now implementsValueEnum
v4.0.0
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 both
single values and ranges of values. num_args
controls how many raw arguments
on 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 is
meeting that goal.
In doing this evaluation, we wanted to keep in mind:
- Whether other CLIs had ideas that make sense to apply
- Providing an experience that fits within the rest of applications and works across all shells
Before:
git
A fictional versioning CLI
USAGE:
git <SUBCOMMAND>
OPTIONS:
-h, --help Print help information
SUBCOMMANDS:
add adds things
clone Clones repos
help Print this message or the help of the given subcommand(s)
push pushes things
stash
After:
A fictional versioning CLI
Usage: git <COMMAND>
Commands:
clone Clones repos
push pushes things
add adds things
stash
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help information
- name/version header was removed because we couldn't justify the space it occupied when
- Usage already includes the name
-
--version
is available for showing the same thing (if the program has a version set)
- Usage was dropped to one line to save space
- Focus is put on the subcommands
- Headings are now Title case
- The more general term "command" is used rather than being explicit about being "subcommands"
- The output is more dense with the expectation that it won't affect legibility but will allow more content
- We've moved to a more neutral palette for highlighting elements (not highlighted above)
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 make
dealing with owned data difficult, like #[arg(default_value_t)]
generating a
String from the default value.
Additionally, to avoid ArgMatches
from borrowing (and for some features we
decided to forgo), clap took the &str
argument IDs and hashed them. This
prevented 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, or
Box<str>
for dynamic behavior with small binary size.
As an extension of that work, you can now call ArgMatches::ids
to iterate
over 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:
- Replacing the implicit behavior for args when parsing them with
ArgAction
- Replacing various one-off forms of value validation with the
ValueParser
API- Allowing derives to automatically do the right thing for
PathBuf
(allowing invalid UTF-8)
- Allowing derives to automatically do the right thing for
- Replacing
AppSettings
andArgSettings
enums with getters/setters - Clarifying terms and making them more consistent
Migrating
Steps:
- Upgrade to v3 if you haven't already
- Add CLI tests (including example below),
-h
and--help
output at a minimum (recommendation: trycmd for snapshot testing) -
If using Builder API: Explicitly set the
arg.action(ArgAction::...)
on each argument (StoreValue
for options andIncOccurrences
for flags) - Run
cargo check --features clap/deprecated
and resolve all deprecation warnings - Upgrade to v4
- Update feature flags
-
If
default-features = false
, runcargo add clap -F help,usage,error-context
- Run
cargo add clap -F wrap_help
unless you want to hard code line wraps
- Resolve compiler errors
- Resolve behavior changes (see "subtle changes" under BREAKING CHANGES)
- At your leisure: resolve new deprecation notices
Example test (derive):
#[derive(clap::Parser)]
struct Cli {
...
}
#[test]
fn verify_cli() {
use clap::CommandFactory;
Cli::command().debug_assert()
}
Example test (builder):
fn cli() -> clap::Command {
...
}
#[test]
fn verify_cli() {
cli().debug_assert();
}
Note: the idiomatic / recommended way of specifying different types of args in the Builder API has changed:
Before
.arg(Arg::new("flag").long("flag")) # --flag
.arg(Arg::new("option").long("option").takes_value(true)) # --option <option>
After:
.arg(Arg::new("flag").long("flag").action(ArgAction::SetTrue)) # --flag
.arg(Arg::new("option").long("option")) # --option <option>
In particular, num_args
(the replacement for takes_value
) will default appropriately
from the ArgAction
and generally only needs to be set explicitly for the
other 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
now conflict by default to be likeArgAction::StoreValue
andArgAction::IncOccurrences
, requiringcmd.args_override_self(true)
to override instead (#4261) - By default, an
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) - Removed lifetimes from
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) - Added default feature flags,
help
,usage
anderror-context
, requiring adding them back in ifdefault-features = false
(#4236) -
(parser) Always fill in
""
argument for external subcommands to make it easier to distinguish them from built-in commands (#3263) -
(parser) Short flags now have higher precedence than hyphen values with
Arg::allow_hyphen_values
, to be consistent withCommand::allow_hyphen_values
(#4187) -
(parser)
Arg::value_terminator
must be its own argument on the CLI rather than being in a delimited list (#4025) -
(help) Line wrapping of help is now behind the existing
wrap_help
feature flag, either enable it or hard code your wraps (#4258) -
(help) Make
DeriveDisplayOrder
the default and removed the setting. To sort help, setnext_display_order(None)
(#2808) -
(help) Subcommand display order respects
Command::next_display_order
instead ofDeriveDisplayOrder
and using its own initial display order value (#2808) -
(help) Subcommands are now listed before arguments. To get the old behavior, see
Command::help_template
(#4132) -
(help) Help headings are now title cased, making any user-provided help headings inconsistent. To get the old behavior, see
Command::help_template
,Arg::help_heading
, andCommand::subcommand_help_heading
(#4132) -
(help) "Command" is used as the section heading for subcommands and
COMMAND
for the value name. To get the old behavior, seeCommand::subcommand_help_heading
andArg::subcommand_value_name
(#4132, #4155) - (help) Whitespace in help output is now trimmed to ensure consistency regardless of how well a template matches the users needs. (#4132, #4156)
-
(help) name/version/author are removed by default from help output. To get the old behavior, see
Command::help_template
. (#4132, #4160) - (help) Indentation for second-line usage changed. (#4132, #4188)
-
(env) Parse
--help
and--version
like anyArgAction::SetTrue
flag (#3776) -
(derive) Leave
Arg::id
asverbatim
casing, requiring updating of string references to other args like inconflicts_with
orrequires
(#3282) -
(derive) Doc comments for
ValueEnum
variants will now show up in--help
(#3312) -
(derive) When deriving
Args
, andArgGroup
is created using the type's name, reserving it for future use (#2621, #4209) -
(derive)
next_help_heading
can now leak out of a#[clap(flatten)]
, like all other command settings (#4222)
Easier to catch changes:
- Looking up a group in
ArgMatches
now returns the argId
s, rather than the values to reduce overhead and offer more flexibility. (#4072) - Changed
Arg::number_of_values
(average-across-occurrences) toArg::num_args
(per-occurrence) (raw CLI args, not parsed values) (#2688, #4023) - Replace
Arg::min_values
(across all occurrences) withArg::num_args(N..)
(per occurrence) to reduce confusion over different value count APIs (#4023) - Replace
Arg::max_values
(across all occurrences) withArg::num_args(1..=M)
(per occurrence) to reduce confusion over different value count APIs (#4023) - Replace
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) - Replace
Arg::takes_value(true)
withArg::num_args(1)
andArg::takes_value(false)
withArg::num_args(0)
to reduce confusion over different value count APIs - Remove
Arg::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 the built-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) - Changed
Arg::requires_ifs
andArg::default_value*_ifs*
to taking anArgPredicate
, removing ambiguity withNone
when accepting owned and borrowed types (#4084) - Removed
PartialEq
andEq
fromCommand
so we could change external subcommands to use aValueParser
(#3990) - Various
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
module -
ErrorKind::EmptyValue
replaced withErrorKind::InvalidValue
to remove an unnecessary special case (#3676, #3968) -
ErrorKind::UnrecognizedSubcommand
replaced withErrorKind::InvalidSubcommand
to remove an unnecessary special case (#3676) - Changed the default type of
allow_external_subcommands
fromString
toOsString
as that is less likely to cause bugs in user applications (#3990) -
(help)
Command::render_usage
now returns aStyledStr
(#4248) -
(derive) Changed the default for arguments from
parse
tovalue_parser
, removingparse
support (#3827, #3981)-
#[clap(value_parser)]
and#[clap(action)]
are now redundant
-
-
(derive)
subcommand_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) -
(derive) Remove
arg_enum
attribute in favor ofvalue_enum
to match the new name (we didn't have support in v3 to mark it deprecated) (#4127) - (parser) Assert when the CLI looksup an unknown args when external subcommand support is enabled to help catch bugs (#3703)
-
(assert) Sometimes
Arg::default_missing_value
didn't requirenum_args(0..=N)
, now it does (#4023) -
(assert) Leading dashes in
Arg::long
are no longer allowed (#3691) -
(assert) Disallow more
value_names
thannum_args
(#2695) -
(assert) Always enforce that version is specified when the
ArgAction::Version
is used -
(assert) Add missing
#[track_caller]
s to make it easier to debug asserts -
(assert) Ensure
overrides_with
IDs are valid -
(assert) Ensure no self-
overrides_with
now that Actions replace it - (assert) Ensure subcommand names are not duplicated
-
(assert) Assert on
mut_arg
receiving an invalid arg ID ormut_subcommand
receiving an invalid command name
Compatibility
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 thing -
Arg::requires_all
in favor ofArg::requires_ifs
now that it takes anArgPredicate
to avoid having multiple ways of doing the same thing -
Arg::number_of_values
in favor ofArg::num_args
to clarify semantic differences -
default_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) -
(help) Deprecated
Command::write_help
andCommand::write_long_help
in favor ofCommand::render_help
andCommand::render_long_help
(#4248) -
(derive)
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) -
(derive)
#[clap(value_parser)]
and#[clap(action)]
defaulted attributes (its the default) (#3976)
Behavior Changes
-
(help) With
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) - Allow non-bool
value_parser
s forArgAction::SetTrue
/ArgAction::SetFalse
(#4092) - Add
From<&OsStr>
,From<OsString>
,From<&str>
, andFrom<String>
tovalue_parser!
(#4257) - Allow resetting most builder methods
- Can now pass runtime generated data to
Command
,Arg
,ArgGroup
,PossibleValue
, etc without managing lifetimes with thestring
feature flag (#2150, #4223) - New default
error-context
,help
andusage
feature flags that can be turned off for smaller binaries (#4236) - Added
StyledStr::ansi()
toDisplay
with ANSI escape codes (#4248) -
(error)
Error::apply
for changing the formatter for dropping binary size (#4111) -
(error)
Error::render
for formatting the error into aStyledStr
-
(help) Show
PossibleValue::help
in long help (--help
) (#3312) -
(help) New
{tab}
variable forCommand::help_template
(#4161) -
(help)
Command::render_help
andCommand::render_long_help
for formatting the error into aStyledStr
(#3873, #4248) -
(help)
Command::render_usage
now returns aStyledStr
(#4248)
Fixes
- Verify
required
is not used with conditional required settings (#3660) - Replaced
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) - Allow
OsStr
s forArg::{required_if_eq,required_if_eq_any,required_if_eq_all}
(#4084) -
(help) With
wrap_help
feature, if the terminal size cannot be determined,LINES
andCOLUMNS
variables are used (#4186) -
(help) Use
Command::display_name
in the help title rather thanCommand::bin_name
-
(help) Show when a flag is
ArgAction::Count
by adding an...
(#4003) - (help) Use a more neutral palette for coloring (#4132, #4117)
- (help) Don't rely on ALL CAPS for help headers (#4132, #4123)
- (help) List subcommands first, focusing the emphasis on them (#4132, #4125)
-
(help) Do not include global args in
cmd help help
(#4131) -
(help) Use
[positional]
in list when relevant (#4144) -
(help) Show all
[positional]
in usage (#4151) - (help) Polish up subcommands by referring to them as commands (#4132, #4155)
- (help) Trim extra whitespace to avoid artifacts from different uses of templates (#4132, #4156)
-
(help) Hint to the user the difference between
-h
/--help
when applicable (#4132, #4159) - (help) Shorten help by eliding name/version/author (#4132, #4160)
-
(help) When short help is long enough to activate
next_line_help
, don't add blank lines (#4132, #4190) - (help) Make help output more dense (reducing horizontal whitespace) (#4132, #4192)
- (help) Separate subcommand flags with "," like option flags (#4232, #4235)
- (help) Quote the suggested help flag (#4220)
-
(version) Use
Command::display_name
rather thanCommand::bin_name
(#3966) -
(parser) Always fill in
""
argument for external subcommands (#3263) -
(parser) Short flags now have higher precedence than hyphen values with
Arg::allow_hyphen_values
, likeCommand::allow_hyphen_values
(#4187) -
(parser) Prefer
InvalidSubcommand
overUnknownArgument
in more cases (#4219) - (derive) Detect escaped external subcommands that look like built-in subcommands (#3703)
-
(derive) Leave
Arg::id
asverbatim
casing (#3282) -
(derive) Default to
#[clap(value_parser, action)]
instead of#[clap(parse)]
(#3827)
Configuration
-
If you want to rebase/retry this MR, check this box
This MR has been generated by Renovate Bot.
Merge request reports
- Side-by-side
- Inline
Some changes are not shown
For a faster browsing experience, some files are collapsed by default.
Files
2Generated files are collapsed by default. To change this behavior, edit the .gitattributes
file. Learn more.