Sourced from clap's changelog.

[3.2.1] - 2022-06-13

[3.2.0] - 2022-06-13

Features

• Parsed, typed arguments via Arg::value_parser / ArgMatches::{get_one,get_many} (#2683, #3732)
  • Several built-in TypedValueParsers available with an API open for expansion
  • value_parser!(T) macro for selecting a parser for a given type (#3732) and open to expansion via the ValueParserFactory trait (#3755)
  • [&str] is implicitly a value parser for possible values
  • All ArgMatches getters do not assume required arguments (#2505)
  • Add ArgMatches::remove_* variants to transfer ownership
  • Add ArgMatches::try_* variants to avoid panics for developer errors (#3621)
  • Add a get_raw to access the underlying OsStrs
  • PathBuf value parsers imply ValueHint::AnyPath for completions (#3732)
• Explicit control over parsing via Arg::action (#3774)
  • ArgAction::StoreValue: existing takes_value(true) behavior
  • ArgAction::IncOccurrences: existing takes_value(false) behavior
  • ArgAction::Help: existing --help behavior
  • ArgAction::Version: existing --version behavior
  • ArgAction::Set: Overwrite existing values (like Arg::multiple_occurrences mixed with Command::args_override_self) (#3777)
  • ArgAction::Append: like Arg::multiple_occurrences (#3777)
  • ArgAction::SetTrue: Treat --flag as --flag=true (#3775)
    • Implies Arg::default_value("false") (#3786)
    • Parses Arg::env via Arg::value_parser
  • ArgAction::SetFalse: Treat --flag as --flag=false (#3775)
    • Implies Arg::default_value("true") (#3786)
    • Parses Arg::env via Arg::value_parser
  • ArgAction::Count: Treat --flag --flag --flag as --flag=1 --flag=2 --flag=3 (#3775)
    • Implies Arg::default_value("0") (#3786)
    • Parses Arg::env via Arg::value_parser
• (derive) Opt-in to new Arg::value_parser / Arg::action with either #[clap(value_parser)] (#3589, #3742) / #[clap(action)] attributes (#3794)
  • Default ValueParser is determined by value_parser! (#3199, #3496)
  • Default ArgAction is determine by a hard-coded lookup on the type (#3794)
• Command::multicall is now stable for busybox-like programs and REPLs (#2861, #3684)
• ArgMatches::{try_,}contains_id for checking if there are values for an argument that mirrors the new get_{one,many} API

Fixes

parser

• Set ArgMatches::value_source and ArgMatches::occurrences_of for external subcommands (#3732)
• Use value delimiter for Arg::default_missing_values (#3761, #3765)
• SplitArg::default_value / Arg::env on value delimiters independent of whether -- was used (#3765)
• Allow applying defaults to flags (#3294, 3775)
• Defaults no longer satisfy required and its variants (#3793)

Compatibility

MSRV is now 1.56.0 (#3732)

... (truncated)

• 650a29c chore: Release
• 73ea5bc chore: Release
• 4e56acf chore: Release
• 45d8bb1 chore: Release
• bd56054 docs(lex): Update changelog
• d25b805 Merge pull request #3821 from epage/test
• 1d053e9 docs: Update changelog
• d72b313 test: Match rest of style
• c8b45f7 Merge pull request #3820 from epage/panic
• 3eacf5b fix(builder): Don't double-has arg id in default_value_ifs_os (#3815)
• Additional commits viewable in compare view

You can trigger Dependabot actions by commenting on this PR:

• @dependabot rebase will rebase this PR
• @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
• @dependabot merge will merge this PR after your CI passes on it
• @dependabot squash and merge will squash and merge this PR after your CI passes on it
• @dependabot cancel merge will cancel a previously requested merge and block automerging
• @dependabot reopen will reopen this PR if it is closed
• @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
• @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)

Sourced from clap's releases.

v3.1.0

[3.1.0] - 2022-02-16

Compatibility

Changes in behavior of note that are not guaranteed to be compatible across releases:

• (help) help subcommand shows long help like --help, rather than short help (-h), deprecated clap::AppSettings::UseLongFormatForHelpSubcommand (#3440)
• (help) Pacman-style subcommands are now ordered the same as usage errors (#3470)
• (help) Pacman-style subcommands use standard alternate syntax in usage (#3470)

Deprecations

• clap::Command is now preferred over clap::App (#3089 in #3472)
  • clap::command! is now preferred over clap::app_from_crate (#3089 in #3474)
  • clap::CommandFactory::command is now preferred over clap::IntoApp::into_app (#3089 in #3473)
• (help) help subcommand shows long help like --help, rather than short help (-h), deprecated clap::AppSettings::UseLongFormatForHelpSubcommand (#3440)
• (error) Deprecate clap::AppSettings::WaitOnError, leaving it to the user to implement
• (validation) clap::Command::subcommand_required(true).arg_required_else_help(true) is now preferred over clap::AppSettings::SubcommandRequiredElseHelp (#3280)
• (builder) clap::AppSettings are nearly all deprecated and replaced with builder methods and getters (#2717)
• (builder) clap::ArgSettings is deprecated and replaced with builder methods and getters (#2717)
• (builder) clap::Arg::id and clap::ArgGroup::id are now preferred over clap::Arg::name and clap::ArgGroup::name (#3335)
• (help) clap::Command::next_help_heading is now preferred over clap::Command::help_heading (#1807, #1553)
• (error) clap::error::ErrorKind is now preferred over clap::ErrorKind (#3395)
• (error) clap::Error::kind() is now preferred over clap::Error::kind
• (error) clap::Error::context() is now preferred over clap::Error::info (#2628)

Note: All items deprecated in 3.0.0 are now hidden in the documentation. (#3458)

Features

• (matches) Add clap::ArgMatches::value_source to determine what insert the value (#1345)
• (help) Override derived display order with clap::Command::next_display_order (#1807)
• (error) Show possible values when an argument doesn't have a value (#3320)
• (error) New clap::Error::context API to open the door for fully-custom error messages (#2628)
  • (error) clap::error::ErrorKind now implements Display

Fixes

• (builder) Some functions were renamed for consistency and fixing spelling issues
• (builder) Allow clap::Command::color to override previous calls (#3449)
• (parse) Propagate globals with multiple subcommands (#3428)
• (validation) Give ArgRequiredElseHelp precedence over SubcommandRequired (#3456)
• (validation) Default values no longer count as "present" for conflicts, requires, clap::Command::arg_required_else_help, etc (#3076, #1264)
• (assert) Report invalid defaults (#3202)
• (help) Clarify how to handle -h conflicts (#3403)
• (help) Make it easier to debug the addition of help flags (#3425)
• (help) Pacman-style subcommands are now separated with spaces (#3470)
• (help) Pacman-style subcommands are now ordered the same as usage errors (#3470)
• (help) Pacman-style subcommands use standard alternate syntax in usage (#3470)

... (truncated)

Sourced from clap's changelog.

[3.1.0] - 2022-02-16

Compatibility

Changes in behavior of note that are not guaranteed to be compatible across releases:

• (help) help subcommand shows long help like --help, rather than short help (-h), deprecated clap::AppSettings::UseLongFormatForHelpSubcommand (#3440)
• (help) Pacman-style subcommands are now ordered the same as usage errors (#3470)
• (help) Pacman-style subcommands use standard alternate syntax in usage (#3470)

Deprecations

• clap::Command is now preferred over clap::App (#3089 in #3472)
  • clap::command! is now preferred over clap::app_from_crate (#3089 in #3474)
  • clap::CommandFactory::command is now preferred over clap::IntoApp::into_app (#3089 in #3473)
• (help) help subcommand shows long help like --help, rather than short help (-h), deprecated clap::AppSettings::UseLongFormatForHelpSubcommand (#3440)
• (error) Deprecate clap::AppSettings::WaitOnError, leaving it to the user to implement
• (validation) clap::Command::subcommand_required(true).arg_required_else_help(true) is now preferred over clap::AppSettings::SubcommandRequiredElseHelp (#3280)
• (builder) clap::AppSettings are nearly all deprecated and replaced with builder methods and getters (#2717)
• (builder) clap::ArgSettings is deprecated and replaced with builder methods and getters (#2717)
• (builder) clap::Arg::id and clap::ArgGroup::id are now preferred over clap::Arg::name and clap::ArgGroup::name (#3335)
• (help) clap::Command::next_help_heading is now preferred over clap::Command::help_heading (#1807, #1553)
• (error) clap::error::ErrorKind is now preferred over clap::ErrorKind (#3395)
• (error) clap::Error::kind() is now preferred over clap::Error::kind
• (error) clap::Error::context() is now preferred over clap::Error::info (#2628)

Note: All items deprecated in 3.0.0 are now hidden in the documentation. (#3458)

Features

• (matches) Add clap::ArgMatches::value_source to determine what insert the value (#1345)
• (help) Override derived display order with clap::Command::next_display_order (#1807)
• (error) Show possible values when an argument doesn't have a value (#3320)
• (error) New clap::Error::context API to open the door for fully-custom error messages (#2628)
  • (error) clap::error::ErrorKind now implements Display

Fixes

• (builder) Some functions were renamed for consistency and fixing spelling issues
• (builder) Allow clap::Command::color to override previous calls (#3449)
• (parse) Propagate globals with multiple subcommands (#3428)
• (validation) Give ArgRequiredElseHelp precedence over SubcommandRequired (#3456)
• (validation) Default values no longer count as "present" for conflicts, requires, clap::Command::arg_required_else_help, etc (#3076, #1264)
• (assert) Report invalid defaults (#3202)
• (help) Clarify how to handle -h conflicts (#3403)
• (help) Make it easier to debug the addition of help flags (#3425)
• (help) Pacman-style subcommands are now separated with spaces (#3470)
• (help) Pacman-style subcommands are now ordered the same as usage errors (#3470)
• (help) Pacman-style subcommands use standard alternate syntax in usage (#3470)
• (error) Be consistent in showing of required attributes between errors / usage (#3390)

... (truncated)

• e6729f9 chore: Release
• aad9fdc Merge pull request #3477 from epage/compat
• 62c2ca4 chore: Remove compatibility crates
• 73847b3 chore: Upgrade boilerplate
• 9bc0af8 Merge pull request #3475 from epage/fixes
• 3dd3993 docs(builder): Add ToC to Command, Arg
• 94e2727 docs(builder): Clarify command-wide
• 92d1002 docs(changelog): Add missing deprecation
• e2136f9 docs(contrib): Align release windows
• 15c7abb docs(parser): Fix ArgMatches::value_source documentation
• Additional commits viewable in compare view

You can trigger Dependabot actions by commenting on this PR:

• @dependabot rebase will rebase this PR
• @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
• @dependabot merge will merge this PR after your CI passes on it
• @dependabot squash and merge will squash and merge this PR after your CI passes on it
• @dependabot cancel merge will cancel a previously requested merge and block automerging
• @dependabot reopen will reopen this PR if it is closed
• @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
• @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)

Sourced from clap's releases.

v3.0.1

[3.0.1] - 2022-01-03

Fixes

• Don't panic when getting number of values (#3241)
• Don't warn when using default_value_t derive attribute with a Subcommand (#3245)

Documentation

• Added name attribute to ArgEnum variant derive reference

Sourced from clap's changelog.

[3.0.1] - 2022-01-03

Fixes

• Don't panic when getting number of values (#3241)
• Don't warn when using default_value_t derive attribute with a Subcommand (#3245)

Documentation

• Added name attribute to ArgEnum variant derive reference

[3.0.0] - 2021-12-31

Note: clap v3 has been in development for several years and has changed hands multiple times. Unfortunately, our changelog might be incomplete, whether in changes or their motivation.

Highlights

A special thanks to the maintainers, contributors, beta users, and sponsors who have helped along this journey, especially kbknapp.

StructOpt Integration

StructOpt provides a serde-like declarative approach to defining your parser. The main benefits we've seen so far from integrating are:

• Tighter feedback between the design of clap and the derives
• More universal traits. Crates exist for common CLI patterns (example) and we've re-designed the StructOpt traits so crates built on clap3 can be reused not just with other derives but also people using the builder API. People can even hand implement these so people using the builder API won't have the pay the cost for derives.

Custom Help Headings

Previously, clap automatically grouped arguments in the help as either ARGS, FLAGS, OPTIONS, and SUBCOMMANDS.

You can now override the default group with Arg::help_heading and App::subcommand_help_heading. To apply a heading to a series of arguments, you can set App::help_heading.

Deprecations

While a lot of deprecations have been added to clean up the API (overloaded meaning of Arg::multiple) or make things more consistent, some particular highlights are:

• clap_app! has been deprecated in favor of the builder API with arg! (clap-rs/clap#2835)
• Arg::from_usage has been deprecated in favor of arg! (clap-rs/clap#3087)
  • Porting example

... (truncated)

• d392b88 chore: Release
• 1a19d48 docs: Update changelog
• 3782d8e Merge pull request #3247 from epage/len
• 5c829ff Merge pull request #3246 from epage/warn
• e580683 fix: Don't panic when getting number of values
• 6b9ae54 fix(derive): Don't enit warnings
• b0cb205 docs(derive): Include name magic attribute
• 06f24b1 Merge pull request #3243 from intgr/fix-clap_complete-documentation-imports
• f10c5d1 docs(complete): Fix imports in documentation
• 879219a Merge pull request #3240 from epage/heck
• Additional commits viewable in compare view

You can trigger Dependabot actions by commenting on this PR:

• @dependabot rebase will rebase this PR
• @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
• @dependabot merge will merge this PR after your CI passes on it
• @dependabot squash and merge will squash and merge this PR after your CI passes on it
• @dependabot cancel merge will cancel a previously requested merge and block automerging
• @dependabot reopen will reopen this PR if it is closed
• @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
• @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)

Sourced from clap's changelog.

[4.0.0] - 2022-09-28

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

... (truncated)

• 3a74d82 chore: Release
• 9cd1939 Merge pull request #4269 from epage/usage
• cb1cd67 fix(error): Include failed arg in usage in --flag=bad-value error
• 12d76d6 fix(error): Include 'Usage:' title in --flag=bad-value error
• 3a8d2a5 test(parser): Verify existing --flag=bad-value case
• c7dd03e Merge pull request #4267 from jpgrayson/override-usage-help-4
• f925ca8 docs: Clarify how to use examples
• 7dd216b docs: Update multiline usage override rules
• a0c8c7d docs: Clean up StyledStr entries
• 01672f8 chore: Release
• Additional commits viewable in compare view

You can trigger Dependabot actions by commenting on this PR:

• @dependabot rebase will rebase this PR
• @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
• @dependabot merge will merge this PR after your CI passes on it
• @dependabot squash and merge will squash and merge this PR after your CI passes on it
• @dependabot cancel merge will cancel a previously requested merge and block automerging
• @dependabot reopen will reopen this PR if it is closed
• @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
• @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
• @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)