Upgrading clap 3 to 4
Breaking3.2.25 → 4.6.7Breaking26Platform3Deprecated6New71Changed66Fixed156Other46
BreakingUpgrade verdict
26 breaking changes and 3 platform requirement changes.
In plain terms
- name/version header was removed because we couldn't justify the space it occupied when.
- ArgAction::Set, ArgAction::SetTrue, and Arg::Action::SetFalse now conflict by default to be like ArgAction::StoreValue and ArgAction::IncOccurrences, requiring cmd.args_override_self(true) to…
- By default, an Args default action is ArgAction::Set, rather than ArgAction::IncOccurrence to reduce confusing magic through consistency (,, see also ).
- 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.
Must act Top 5 of 35 that need code or config changes
clap publishes an official migration guide for version 4. It covers more than the release notes do.
Migrating to clap 4 ↗Rust requirement changed in 4.6.0: 1.56.1 → 1.85.
What you must change
Breaking26
name/version header was removed because we couldn't justify the space it occupied when.
--versionArgAction::Set, ArgAction::SetTrue, and Arg::Action::SetFalse now conflict by default to be like ArgAction::StoreValue and ArgAction::IncOccurrences, requiring cmd.args_override_self(true) to…
ArgAction::SetArgAction::SetTrueArg::Action::SetFalseArgAction::StoreValueArgAction::IncOccurrencescmd.args_override_self(true)By default, an Args default action is ArgAction::Set, rather than ArgAction::IncOccurrence to reduce confusing magic through consistency (,, see also ).
ArgArgAction::SetArgAction::IncOccurrencemut_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.
mut_argCommand::disable_help_flagCommand::disable_version_flagRemoved lifetimes from Command, Arg, ArgGroup, and PossibleValue, assuming 'static. string feature flag will enable support for Strings.
CommandArgArgGroupPossibleValue'staticstringAdded default feature flags, help, usage and error-context, requiring adding them back in if default-features = false.
helpusageerror-context(help) Make DeriveDisplayOrder the default and removed the setting.
DeriveDisplayOrdernext_display_order(None)(help) name/version/author are removed by default from help output.
Command::help_templateResolve behavior changes (see "subtle changes" under BREAKING CHANGES).
arg! now sets one of.
arg!ArgAction::SetTrueArgMatches::get_flagArgMatches::is_presentArgAction::CountArgMatches::get_countarg!(--flag ) is now optional, instead of required.
.required(true)(parser) Always fill in "" argument for external subcommands to make it easier to distinguish them from built-in commands.
(parser) Short flags now have higher precedence than hyphen values with Arg::allow_hyphen_values, to be consistent with Command::allow_hyphen_values.
Arg::allow_hyphen_valuesCommand::allow_hyphen_values(parser) Arg::value_terminator must be its own argument on the CLI rather than being in a delimited list.
Arg::value_terminator(help) Line wrapping of help is now behind the existing wrap_help feature flag, either enable it or hard code your wraps.
wrap_help(help) Subcommand display order respects Command::next_display_order instead of DeriveDisplayOrder and using its own initial display order value.
Command::next_display_orderDeriveDisplayOrder(help) Subcommands are now listed before arguments.
Command::help_template(help) Help headings are now title cased, making any user-provided help headings inconsistent.
Command::help_templateArg::help_headingCommand::subcommand_help_heading(help) "Command" is used as the section heading for subcommands and COMMAND for the value name.
COMMANDCommand::subcommand_help_headingArg::subcommand_value_name(help) Whitespace in help output is now trimmed to ensure consistency regardless of how well a template matches the users needs.
(help) Indentation for second-line usage changed.
(env) Parse --help and --version like any ArgAction::SetTrue flag.
--help--versionArgAction::SetTrue(derive) Leave Arg::id as verbatim casing, requiring updating of string references to other args like in conflicts_with or requires.
Arg::idverbatimconflicts_withrequires(derive) Doc comments for ValueEnum variants will now show up in --help.
ValueEnum--help(derive) When deriving Args, and ArgGroup is created using the type's name, reserving it for future use.
ArgsArgGroup(derive) next_help_heading can now leak out of a #[clap(flatten)], like all other command settings.
next_help_heading#[clap(flatten)]Platform3
Updates the minimum supported Rust version (MSRV) to 1.85.
Update MSRV to 1.74.
Update msrv to 1.70.0.
Deprecations to plan for
Deprecated6
Replacing the implicit behavior for args when parsing them with ArgAction.
ArgActionReplacing various one-off forms of value validation with the ValueParser API.
ValueParserPathBufReplacing AppSettings and ArgSettings enums with getters/setters.
AppSettingsArgSettingsClarifying terms and making them more consistent.
Run cargo check --features clap/deprecated and resolve all deprecation warnings.
At your leisure: resolve new deprecation notices.