clap breaking changes
cargo93 curated breaking changes across major versions of clap. Use this as a migration checklist before bumping dependencies.
- 4.6.1 \u2192 5.0.0behavior
*(help)* Change default `Command::max_term_width` to 100
- 4.6.1 \u2192 5.0.0behavior
*(help)* Change default `Command::term_width` to "source format"
- 4.6.1 \u2192 5.0.0breaking
*(derive)* `Vec<Vec<T>>` types are now assuming to capture occurrences
- 4.6.1 \u2192 5.0.0breaking
*(derive)* `ValueEnum` variants now use the full doc comment, not summary, for `PossibleValue::help`
- 4.6.1 \u2192 5.0.0breaking
Made `ArgPredicate` `non_exhaustive`
- 3.2.18 \u2192 4.0.0api
*(help)* Subcommands are now listed before arguments. To get the old behavior, see `Command::help_template` (#4132)
- 3.2.18 \u2192 4.0.0api
*(parser)* Always fill in `""` argument for external subcommands to make it easier to distinguish them from built-in commands (#3263)
- 3.2.18 \u2192 4.0.0api
`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)
- 3.2.18 \u2192 4.0.0api
*(parser)* `Arg::value_terminator` must be its own argument on the CLI rather than being in a delimited list (#4025)
- 3.2.18 \u2192 4.0.0behavior
Added default feature flags, `help`, `usage` and `error-context`, requiring adding them back in if `default-features = false` (#4236)
- 3.2.18 \u2192 4.0.0behavior
By default, an `Arg`s default action is `ArgAction::Set`, rather than `ArgAction::IncOccurrence` to reduce confusing magic through consistency (#2687, #4032, see also #3977)
- 3.2.18 \u2192 4.0.0behavior
*(help)* "Command" is used as the section heading for subcommands and `COMMAND` for the value name. To get the old behavior, see `Command::subcommand_help_heading` and `Arg::subcommand_value_name` (#4132, #4155)
- 3.2.18 \u2192 4.0.0behavior
*(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`, and `Command::subcommand_help_heading` (#4132)
- 3.2.18 \u2192 4.0.0behavior
`arg!(--flag <value>)` is now optional, instead of required. Add `.required(true)` at the end to restore the original behavior (#4206)
- 3.2.18 \u2192 4.0.0breaking
*(derive)* Leave `Arg::id` as `verbatim` casing, requiring updating of string references to other args like in `conflicts_with` or `requires` (#3282)
- 3.2.18 \u2192 4.0.0breaking
`arg!` now sets one of (#3795):
- 3.2.18 \u2192 4.0.0breaking
`ArgAction::SetTrue`, requiring `ArgMatches::get_flag` instead of `ArgMatches::is_present`
- 3.2.18 \u2192 4.0.0breaking
`ArgAction::Count`, requiring `ArgMatches::get_count` instead of `ArgMatches::occurrences_of`
- 3.2.18 \u2192 4.0.0breaking
`ArgAction::Set`, requiring `ArgMatches::get_one` instead of `ArgMatches::value_of`
- 3.2.18 \u2192 4.0.0breaking
`ArgAction::Append`, requiring `ArgMatches::get_many` instead of `ArgMatches::values_of`
- 3.2.18 \u2192 4.0.0breaking
`ArgAction::Set`, `ArgAction::SetTrue`, and `Arg::Action::SetFalse` now
- 3.2.18 \u2192 4.0.0breaking
*(parser)* Short flags now have higher precedence than hyphen values with `Arg::allow_hyphen_values`, to be consistent with `Command::allow_hyphen_values` (#4187)
- 3.2.18 \u2192 4.0.0breaking
*(help)* Line wrapping of help is now behind the existing `wrap_help` feature flag, either enable it or hard code your wraps (#4258)
- 3.2.18 \u2192 4.0.0breaking
*(help)* Subcommand display order respects `Command::next_display_order` instead of `DeriveDisplayOrder` and using its own initial display order value (#2808)
- 3.2.18 \u2192 4.0.0breaking
*(help)* Whitespace in help output is now trimmed to ensure consistency regardless of how well a template matches the users needs. (#4132, #4156)
- 3.2.18 \u2192 4.0.0breaking
*(help)* Indentation for second-line usage changed. (#4132, #4188)
- 3.2.18 \u2192 4.0.0breaking
*(env)* Parse `--help` and `--version` like any `ArgAction::SetTrue` flag (#3776)
- 3.2.18 \u2192 4.0.0removed
*(help)* name/version/author are removed by default from help output. To get the old behavior, see `Command::help_template`. (#4132, #4160)
- 3.2.18 \u2192 4.0.0removed
Removed lifetimes from `Command`, `Arg`, `ArgGroup`, and `PossibleValue`, assuming `'static`. `string` feature flag will enable support for `String`s (#1041, #2150, #4223)
- 3.2.18 \u2192 4.0.0removed
*(help)* Make `DeriveDisplayOrder` the default and removed the setting. To sort help, set `next_display_order(None)` (#2808)
- 2.34.0 \u2192 3.0.0api
`ArgMatches` panics on unknown arguments
- 2.34.0 \u2192 3.0.0api
No longer accept an arbitrary number of `-` for long arguments (`-----long`)
- 2.34.0 \u2192 3.0.0behavior
`AppSettings::UnifiedHelpMessage` is now default behaviour
- 2.34.0 \u2192 3.0.0behavior
`AppSettings::EnableColoredHelp` is now the default behavior but can be
- 2.34.0 \u2192 3.0.0behavior
When using `no-default-features`, you now have to specify the `std` feature (reserved for future work)
- 2.34.0 \u2192 3.0.0behavior
`AppSettings::StrictUtf8` is now default behaviour and asserts if
- 2.34.0 \u2192 3.0.0breaking
Changed `...`s meaning in usage parser. Before, it always meant `multiple` which is still true for `--option [val]...`. Now `[name]... --option [val]` results in `ArgSettings::MultipleOccurrences`.
- 2.34.0 \u2192 3.0.0breaking
`{flags}` and `{unified}` will assert if present in `App::help_template`
- 2.34.0 \u2192 3.0.0breaking
See [clap-rs/clap#2807](https://github.com/clap-rs/clap/issues/2807)
- 2.34.0 \u2192 3.0.0breaking
`App::override_usage` no longer implies a leading `\t`, allowing multi lined usages
- 2.34.0 \u2192 3.0.0breaking
`Arg::require_equals` no longer implies `ArgSettings::ForbidEmptyValues` ([#2233](https://github.com/clap-rs/clap/issues/2233))
- 2.34.0 \u2192 3.0.0breaking
`Arg::require_delimiter` no longer implies `ArgSettings::TakesValue` and `ArgSettings::UseValueDelimiter` ([#2233](https://github.com/clap-rs/clap/issues/2233))
- 2.34.0 \u2192 3.0.0breaking
`Arg::env`, `Arg::env_os`, `Arg::last`, `Arg::require_equals`, `Arg::allow_hyphen_values`,
- 2.34.0 \u2192 3.0.0breaking
`ArgMatches::is_present` no longer checks subcommand names
- 2.34.0 \u2192 3.0.0breaking
Some env variable values are now considered false for flags, not just "not-present" ([clap-rs/clap#2539](https://github.com/clap-rs/clap/issues/2539))
- 2.34.0 \u2192 3.0.0breaking
Usage exit code changed from `1` to `2` ([clap-rs/clap#1327](https://github.com/clap-rs/clap/issues/1327))
- 2.34.0 \u2192 3.0.0breaking
Reject `--foo=bar` when `takes_value(false)` ([clap-rs/clap#1543](https://github.com/clap-rs/clap/issues/1543))
- 2.34.0 \u2192 3.0.0breaking
Gated env support behind `env` feature flag
- 2.34.0 \u2192 3.0.0breaking
Impacts `Arg::env`, `Arg::env_os`, `Arg::hide_env_values`, `ArgSettings::HideEnvValues`
- 2.34.0 \u2192 3.0.0breaking
See [clap-rs/clap#2694](https://github.com/clap-rs/clap/pull/2694)
- 2.34.0 \u2192 3.0.0breaking
Gated crate information behind `cargo` feature flag
- 2.34.0 \u2192 3.0.0breaking
Impacts `crate_name!`, `crate_version!`, `crate_authors!`, `crate_description!`, `app_from_crate!`
- 2.34.0 \u2192 3.0.0breaking
[clap-rs/clap#751](https://github.com/clap-rs/clap/issues/751)
- 2.34.0 \u2192 3.0.0breaking
`Arg::short` and `Arg::value_delimiter` now take a `char` instead of a `&str`
- 2.34.0 \u2192 3.0.0removed
`AppSettings::AllowInvalidUtf8` has been removed
- 2.26.2 \u2192 2.27.0api
when an argument requires a value and that value happens to match a subcommand name, its parsed as a value ([0c223f54](https://github.com/clap-rs/clap/commit/0c223f54ed46da406bc8b43a5806e0b227863b31), closes [#1031](https://github.com/clap-rs/clap/issues/1031), breaks [#](https://github.com/clap-rs/clap/issues/), [#](https://github.com/clap-rs/clap/issues/))
- 2.19.1 \u2192 2.19.2breaking
**README.md:** adds guidance on when to use ~ in version pinning, and clarifies breaking change policy ([591eaefc](https://github.com/clap-rs/clap/commit/591eaefc7319142ba921130e502bb0729feed907), closes [#765](https://github.com/clap-rs/clap/issues/765))
- 2.19.1 \u2192 2.19.2breaking
**ZSH Completions:** escapes square brackets in ZSH completions ([7e17d5a3](https://github.com/clap-rs/clap/commit/7e17d5a36b2cc2cc77e7b15796b14d639ed3cbf7), closes [#771](https://github.com/clap-rs/clap/issues/771))
- 2.19.1 \u2192 2.19.2breaking
**Examples:** adds subcommand examples ([0e0f3354](https://github.com/clap-rs/clap/commit/0e0f33547a6901425afc1d9fbe19f7ae3832d9a4), closes [#766](https://github.com/clap-rs/clap/issues/766))
- 2.9.3 \u2192 2.10.0breaking
**parser:** preserve external subcommand name ([875df243](https://github.com/clap-rs/clap/commit/875df24316c266920a073c13bbefbf546bc1f635))
- 1.5.5 \u2192 2.0.0breaking
**Fewer lifetimes! Yay!**
- 1.5.5 \u2192 2.0.0breaking
`App<'a, 'b, 'c, 'd, 'e, 'f>` => `App<'a, 'b>`
- 1.5.5 \u2192 2.0.0breaking
`Arg<'a, 'b, 'c, 'd, 'e, 'f>` => `Arg<'a, 'b>`
- 1.5.5 \u2192 2.0.0breaking
`ArgMatches<'a, 'b>` => `ArgMatches<'a>`
- 1.5.5 \u2192 2.0.0breaking
`App::arg_required_else_help`
- 1.5.5 \u2192 2.0.0breaking
`App::versionless_subcommands`
- 1.5.5 \u2192 2.0.0breaking
`App::subcommand_required_else_help`
- 1.5.5 \u2192 2.0.0breaking
`SubCommand::new`
- 1.5.5 \u2192 2.0.0breaking
`App::wait_on_error`
- 1.5.5 \u2192 2.0.0breaking
`App::unified_help_messages`
- 1.5.5 \u2192 2.0.0breaking
`App::subcommand_required`
- 1.5.5 \u2192 2.0.0breaking
`App::global_version(bool)`
- 1.5.5 \u2192 2.0.0breaking
`App::arg_group` => `App::group`
- 1.5.5 \u2192 2.0.0breaking
`App::arg_groups` => `App::groups`
- 1.5.5 \u2192 2.0.0breaking
`ArgGroup::add` => `ArgGroup::arg`
- 1.5.5 \u2192 2.0.0breaking
`ArgGroup::add_all` => `ArgGroup::args`
- 1.5.5 \u2192 2.0.0breaking
`ClapError` => `Error`
- 1.5.5 \u2192 2.0.0breaking
struct field `ClapError::error_type` => `Error::kind`
- 1.5.5 \u2192 2.0.0breaking
`ClapResult` => `Result`
- 1.5.5 \u2192 2.0.0breaking
`App::error_on_no_subcommand`
- 1.5.5 \u2192 2.0.0breaking
`ClapErrorType` => `ErrorKind`
- 1.5.5 \u2192 2.0.0breaking
`App::subcommands_negate_reqs`
- 1.5.5 \u2192 2.0.0removed
**Removed Deprecated Functions and Methods**
- 1.5.5 \u2192 2.0.0renamed
**Simply Renamed**
- 0.6.9 \u2192 0.7.0breaking
add support for minimum and maximum number of values ([53f6b8c9](https://github.com/clap-rs/clap/commit/53f6b8c9d8dc408b4fa9f833fc3a63683873c42f))
- 0.6.9 \u2192 0.7.0breaking
implement shorthand for options with multiple values ([6669f0a9](https://github.com/clap-rs/clap/commit/6669f0a9687d4f668523145d7bd5c007d1eb59a8))
- 0.6.9 \u2192 0.7.0breaking
**arg** allow other types besides Vec for multiple value settings (**BREAKING CHANGE** [0cc2f698](https://github.com/clap-rs/clap/commit/0cc2f69839b9b1db5d06330771b494783049a88e), closes [#87](https://github.com/clap-rs/clap/issues/87))
- 0.6.9 \u2192 0.7.0breaking
**usage** implement smart usage strings on errors ([d77048ef](https://github.com/clap-rs/clap/commit/d77048efb1e595ffe831f1a2bea2f2700db53b9f), closes [#88](https://github.com/clap-rs/clap/issues/88))
- 0.6.9 \u2192 0.7.0breaking
**MultipleValues**
- 0.6.9 \u2192 0.7.0breaking
adds support limited number and named values ([ae09f05e](https://github.com/clap-rs/clap/commit/ae09f05e92251c1b39a83d372736fcc7b504e432))
- 0.6.9 \u2192 0.7.0removed
**from_usage** removes bug where usage strings have no help text ([ad4e5451](https://github.com/clap-rs/clap/commit/ad4e54510739aeabf75f0da3278fb0952db531b3), closes [#83](https://github.com/clap-rs/clap/issues/83))
- 0.10.5 \u2192 0.11.0behavior
**Help and Version** default short for version is now `-V` but can be overridden (only breaks manual documentation) (**BREAKING CHANGE** [eb1d9320](https://github.com/clap-rs/clap/commit/eb1d9320c509c1e4e57d7c7959da82bcfe06ada0))
- 0.10.5 \u2192 0.11.0behavior
updates docs to new version flag defaults ([ebf442eb](https://github.com/clap-rs/clap/commit/ebf442ebebbcd2ec6bfe2c06566c9d362bccb112))
Get this data programmatically \u2014 free, no authentication.
curl https://depscope.dev/api/breaking/cargo/clap