Skip to content

Commit 94770a5

Browse files
borsbors
committed
Auto merge of #12545 - epage:positional, r=weihanglo
fix(update): Make `-p` more convenient by being positional Generally, cargo avoids positional arguments. Mostly for the commands that might forward arguments to another command, like `cargo test`. It also allows some flexibility in turning flags into options. For `cargo add` and `cargo remove`, we decided to accept positionals because the motivations didn't seem to apply as much (similar to `cargo install`). This applies the pattern to `cargo update` as well which is in the same category of commands as `cargo add` and `cargo remove`. As for `--help` formatting, I'm mixed on whether `[SPEC]...` should be at the top like other positionals or should be relegated to "Package selection". I went with the latter mostly to make it easier to visualize the less common choice. Switching to a positional for `cargo update` (while keeping `-p` for backwards compatibility) was referenced in #12425.
2 parents 5522091 + dc37222 commit 94770a5

28 files changed

+158
-99
lines changed

‎src/bin/cargo/commands/update.rs

+33-3
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,26 @@
11
use crate::command_prelude::*;
22

3+
use anyhow::anyhow;
34
use cargo::ops::{self, UpdateOptions};
45
use cargo::util::print_available_packages;
56

67
pub fn cli() -> Command {
78
subcommand("update")
89
.about("Update dependencies as recorded in the local lock file")
10+
.args([clap::Arg::new("package2")
11+
.action(clap::ArgAction::Append)
12+
.num_args(1..)
13+
.value_name("SPEC")
14+
.help_heading(heading::PACKAGE_SELECTION)
15+
.group("package-group")
16+
.help("Package to update")])
17+
.arg(
18+
optional_multi_opt("package", "SPEC", "Package to update")
19+
.short('p')
20+
.hide(true)
21+
.help_heading(heading::PACKAGE_SELECTION)
22+
.group("package-group"),
23+
)
924
.arg_dry_run("Don't actually write the lockfile")
1025
.arg(
1126
flag(
@@ -20,15 +35,14 @@ pub fn cli() -> Command {
2035
"Update a single dependency to exactly PRECISE when used with -p",
2136
)
2237
.value_name("PRECISE")
23-
.requires("package"),
38+
.requires("package-group"),
2439
)
2540
.arg_quiet()
2641
.arg(
2742
flag("workspace", "Only update the workspace packages")
2843
.short('w')
2944
.help_heading(heading::PACKAGE_SELECTION),
3045
)
31-
.arg_package_spec_simple("Package to update")
3246
.arg_manifest_path()
3347
.after_help("Run `cargo help update` for more detailed information.\n")
3448
}
@@ -40,10 +54,26 @@ pub fn exec(config: &mut Config, args: &ArgMatches) -> CliResult {
4054
print_available_packages(&ws)?;
4155
}
4256

57+
let to_update = if args.contains_id("package") {
58+
"package"
59+
} else {
60+
"package2"
61+
};
62+
let to_update = values(args, to_update);
63+
for crate_name in to_update.iter() {
64+
if let Some(toolchain) = crate_name.strip_prefix("+") {
65+
return Err(anyhow!(
66+
"invalid character `+` in package name: `+{toolchain}`
67+
Use `cargo +{toolchain} update` if you meant to use the `{toolchain}` toolchain."
68+
)
69+
.into());
70+
}
71+
}
72+
4373
let update_opts = UpdateOptions {
4474
aggressive: args.flag("aggressive"),
4575
precise: args.get_one::<String>("precise").map(String::as_str),
46-
to_update: values(args, "package"),
76+
to_update,
4777
dry_run: args.dry_run(),
4878
workspace: args.flag("workspace"),
4979
config,

‎src/cargo/ops/cargo_compile/mod.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -508,7 +508,7 @@ pub fn create_bcx<'a, 'cfg>(
508508
} else if !unit.is_local() {
509509
format!(
510510
"Either upgrade to rustc {} or newer, or use\n\
511-
cargo update -p {}@{} --precise ver\n\
511+
cargo update {}@{} --precise ver\n\
512512
where `ver` is the latest version of `{}` supporting rustc {}",
513513
version,
514514
unit.pkg.name(),

‎src/cargo/ops/resolve.rs

+2-2
Original file line numberDiff line numberDiff line change
@@ -612,7 +612,7 @@ fn register_previous_locks(
612612

613613
// Ok so we've been passed in a `keep` function which basically says "if I
614614
// return `true` then this package wasn't listed for an update on the command
615-
// line". That is, if we run `cargo update -p foo` then `keep(bar)` will return
615+
// line". That is, if we run `cargo update foo` then `keep(bar)` will return
616616
// `true`, whereas `keep(foo)` will return `false` (roughly speaking).
617617
//
618618
// This isn't actually quite what we want, however. Instead we want to
@@ -622,7 +622,7 @@ fn register_previous_locks(
622622
// * There's a crate `log`.
623623
// * There's a crate `serde` which depends on `log`.
624624
//
625-
// Let's say we then run `cargo update -p serde`. This may *also* want to
625+
// Let's say we then run `cargo update serde`. This may *also* want to
626626
// update the `log` dependency as our newer version of `serde` may have a
627627
// new minimum version required for `log`. Now this isn't always guaranteed
628628
// to work. What'll happen here is we *won't* lock the `log` dependency nor

‎src/cargo/sources/registry/mod.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -251,7 +251,7 @@ pub struct RegistrySource<'cfg> {
251251
/// yanked.
252252
///
253253
/// This is populated from the entries in `Cargo.lock` to ensure that
254-
/// `cargo update -p somepkg` won't unlock yanked entries in `Cargo.lock`.
254+
/// `cargo update somepkg` won't unlock yanked entries in `Cargo.lock`.
255255
/// Otherwise, the resolver would think that those entries no longer
256256
/// exist, and it would trigger updates to unrelated packages.
257257
yanked_whitelist: HashSet<PackageId>,

‎src/doc/man/cargo-update.md

+8-8
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ cargo-update --- Update dependencies as recorded in the local lock file
66

77
## SYNOPSIS
88

9-
`cargo update` [_options_]
9+
`cargo update` [_options_] _spec_
1010

1111
## DESCRIPTION
1212

@@ -20,26 +20,26 @@ latest available versions.
2020

2121
{{#options}}
2222

23-
{{#option "`-p` _spec_..." "`--package` _spec_..." }}
23+
{{#option "_spec_..." }}
2424
Update only the specified packages. This flag may be specified
2525
multiple times. See {{man "cargo-pkgid" 1}} for the SPEC format.
2626

27-
If packages are specified with the `-p` flag, then a conservative update of
27+
If packages are specified with _spec_, then a conservative update of
2828
the lockfile will be performed. This means that only the dependency specified
2929
by SPEC will be updated. Its transitive dependencies will be updated only if
3030
SPEC cannot be updated without updating dependencies. All other dependencies
3131
will remain locked at their currently recorded versions.
3232

33-
If `-p` is not specified, all dependencies are updated.
33+
If _spec_ is not specified, all dependencies are updated.
3434
{{/option}}
3535

3636
{{#option "`--aggressive`" }}
37-
When used with `-p`, dependencies of _spec_ are forced to update as well.
37+
When used with _spec_, dependencies of _spec_ are forced to update as well.
3838
Cannot be used with `--precise`.
3939
{{/option}}
4040

4141
{{#option "`--precise` _precise_" }}
42-
When used with `-p`, allows you to specify a specific version number to set
42+
When used with _spec_, allows you to specify a specific version number to set
4343
the package to. If the package comes from a git repository, this can be a git
4444
revision (such as a SHA hash or tag).
4545
{{/option}}
@@ -87,11 +87,11 @@ Displays what would be updated, but doesn't actually write the lockfile.
8787

8888
2. Update only specific dependencies:
8989

90-
cargo update -p foo -p bar
90+
cargo update foo bar
9191

9292
3. Set a specific dependency to a specific version:
9393

94-
cargo update -p foo --precise 1.2.3
94+
cargo update foo --precise 1.2.3
9595

9696
## SEE ALSO
9797
{{man "cargo" 1}}, {{man "cargo-generate-lockfile" 1}}

‎src/doc/man/generated_txt/cargo-update.txt

+13-13
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ NAME
44
cargo-update — Update dependencies as recorded in the local lock file
55

66
SYNOPSIS
7-
cargo update [options]
7+
cargo update [options] spec
88

99
DESCRIPTION
1010
This command will update dependencies in the Cargo.lock file to the
@@ -13,25 +13,25 @@ DESCRIPTION
1313

1414
OPTIONS
1515
Update Options
16-
-p spec…, --package spec…
16+
spec…
1717
Update only the specified packages. This flag may be specified
1818
multiple times. See cargo-pkgid(1) for the SPEC format.
1919

20-
If packages are specified with the -p flag, then a conservative
21-
update of the lockfile will be performed. This means that only the
22-
dependency specified by SPEC will be updated. Its transitive
23-
dependencies will be updated only if SPEC cannot be updated without
24-
updating dependencies. All other dependencies will remain locked at
25-
their currently recorded versions.
20+
If packages are specified with spec, then a conservative update of
21+
the lockfile will be performed. This means that only the dependency
22+
specified by SPEC will be updated. Its transitive dependencies will
23+
be updated only if SPEC cannot be updated without updating
24+
dependencies. All other dependencies will remain locked at their
25+
currently recorded versions.
2626

27-
If -p is not specified, all dependencies are updated.
27+
If spec is not specified, all dependencies are updated.
2828

2929
--aggressive
30-
When used with -p, dependencies of spec are forced to update as
30+
When used with spec, dependencies of spec are forced to update as
3131
well. Cannot be used with --precise.
3232

3333
--precise precise
34-
When used with -p, allows you to specify a specific version number
34+
When used with spec, allows you to specify a specific version number
3535
to set the package to. If the package comes from a git repository,
3636
this can be a git revision (such as a SHA hash or tag).
3737

@@ -155,11 +155,11 @@ EXAMPLES
155155

156156
2. Update only specific dependencies:
157157

158-
cargo update -p foo -p bar
158+
cargo update foo bar
159159

160160
3. Set a specific dependency to a specific version:
161161

162-
cargo update -p foo --precise 1.2.3
162+
cargo update foo --precise 1.2.3
163163

164164
SEE ALSO
165165
cargo(1), cargo-generate-lockfile(1)

‎src/doc/src/commands/cargo-update.md

+8-9
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ cargo-update --- Update dependencies as recorded in the local lock file
66

77
## SYNOPSIS
88

9-
`cargo update` [_options_]
9+
`cargo update` [_options_] _spec_
1010

1111
## DESCRIPTION
1212

@@ -20,25 +20,24 @@ latest available versions.
2020

2121
<dl>
2222

23-
<dt class="option-term" id="option-cargo-update--p"><a class="option-anchor" href="#option-cargo-update--p"></a><code>-p</code> <em>spec</em>…</dt>
24-
<dt class="option-term" id="option-cargo-update---package"><a class="option-anchor" href="#option-cargo-update---package"></a><code>--package</code> <em>spec</em>…</dt>
23+
<dt class="option-term" id="option-cargo-update-spec…"><a class="option-anchor" href="#option-cargo-update-spec…"></a><em>spec</em>…</dt>
2524
<dd class="option-desc">Update only the specified packages. This flag may be specified
2625
multiple times. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the SPEC format.</p>
27-
<p>If packages are specified with the <code>-p</code> flag, then a conservative update of
26+
<p>If packages are specified with <em>spec</em>, then a conservative update of
2827
the lockfile will be performed. This means that only the dependency specified
2928
by SPEC will be updated. Its transitive dependencies will be updated only if
3029
SPEC cannot be updated without updating dependencies. All other dependencies
3130
will remain locked at their currently recorded versions.</p>
32-
<p>If <code>-p</code> is not specified, all dependencies are updated.</dd>
31+
<p>If <em>spec</em> is not specified, all dependencies are updated.</dd>
3332

3433

3534
<dt class="option-term" id="option-cargo-update---aggressive"><a class="option-anchor" href="#option-cargo-update---aggressive"></a><code>--aggressive</code></dt>
36-
<dd class="option-desc">When used with <code>-p</code>, dependencies of <em>spec</em> are forced to update as well.
35+
<dd class="option-desc">When used with <em>spec</em>, dependencies of <em>spec</em> are forced to update as well.
3736
Cannot be used with <code>--precise</code>.</dd>
3837

3938

4039
<dt class="option-term" id="option-cargo-update---precise"><a class="option-anchor" href="#option-cargo-update---precise"></a><code>--precise</code> <em>precise</em></dt>
41-
<dd class="option-desc">When used with <code>-p</code>, allows you to specify a specific version number to set
40+
<dd class="option-desc">When used with <em>spec</em>, allows you to specify a specific version number to set
4241
the package to. If the package comes from a git repository, this can be a git
4342
revision (such as a SHA hash or tag).</dd>
4443

@@ -187,11 +186,11 @@ details on environment variables that Cargo reads.
187186

188187
2. Update only specific dependencies:
189188

190-
cargo update -p foo -p bar
189+
cargo update foo bar
191190

192191
3. Set a specific dependency to a specific version:
193192

194-
cargo update -p foo --precise 1.2.3
193+
cargo update foo --precise 1.2.3
195194

196195
## SEE ALSO
197196
[cargo(1)](cargo.html), [cargo-generate-lockfile(1)](cargo-generate-lockfile.html)

‎src/doc/src/guide/cargo-toml-vs-cargo-lock.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -91,8 +91,8 @@ When we’re ready to opt in to a new version of the library, Cargo can
9191
re-calculate the dependencies and update things for us:
9292

9393
```console
94-
$ cargo update # updates all dependencies
95-
$ cargo update -p regex # updates just “regex”
94+
$ cargo update # updates all dependencies
95+
$ cargo update regex # updates just “regex”
9696
```
9797

9898
This will write out a new `Cargo.lock` with the new version information. Note

‎src/doc/src/reference/overriding-dependencies.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ $ cargo build
9797

9898
And that's it! You're now building with the local version of `uuid` (note the
9999
path in parentheses in the build output). If you don't see the local path version getting
100-
built then you may need to run `cargo update -p uuid --precise $version` where
100+
built then you may need to run `cargo update uuid --precise $version` where
101101
`$version` is the version of the locally checked out copy of `uuid`.
102102

103103
Once you've fixed the bug you originally found the next thing you'll want to do

‎src/doc/src/reference/resolver.md

+2-2
Original file line numberDiff line numberDiff line change
@@ -464,10 +464,10 @@ situations may require specifying unusual requirements.
464464
If you fail to do this, it may not be immediately obvious because Cargo can
465465
opportunistically choose the newest version when you run a blanket `cargo
466466
update`. However, if another user depends on your library, and runs `cargo
467-
update -p your-library`, it will *not* automatically update "bar" if it is
467+
update your-library`, it will *not* automatically update "bar" if it is
468468
locked in their `Cargo.lock`. It will only update "bar" in that situation if
469469
the dependency declaration is also updated. Failure to do so can cause
470-
confusing build errors for the user using `cargo update -p`.
470+
confusing build errors for the user using `cargo update your-library`.
471471
* If two packages are tightly coupled, then an `=` dependency requirement may
472472
help ensure that they stay in sync. For example, a library with a companion
473473
proc-macro library will sometimes make assumptions between the two libraries

‎src/doc/src/reference/specifying-dependencies.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ The string `"0.1.12"` is a version requirement. Although it looks like a
2323
specific *version* of the `time` crate, it actually specifies a *range* of
2424
versions and allows [SemVer] compatible updates. An update is allowed if the new
2525
version number does not modify the left-most non-zero number in the major, minor,
26-
patch grouping. In this case, if we ran `cargo update -p time`, cargo should
26+
patch grouping. In this case, if we ran `cargo update time`, cargo should
2727
update us to version `0.1.13` if it is the latest `0.1.z` release, but would not
2828
update us to `0.2.0`. If instead we had specified the version string as `1.0`,
2929
cargo should update to `1.1` if it is the latest `1.y` release, but not `2.0`.

‎src/etc/_cargo

+2-1
Original file line numberDiff line numberDiff line change
@@ -344,7 +344,8 @@ _cargo() {
344344
'--aggressive=[force dependency update]' \
345345
"--dry-run[don't actually write the lockfile]" \
346346
'(-p --package)'{-p+,--package=}'[specify package to update]:package:_cargo_package_names' \
347-
'--precise=[update single dependency to precise release]:release'
347+
'--precise=[update single dependency to precise release]:release' \
348+
'*:package:_cargo_package_names'
348349
;;
349350

350351
verify-project)

‎src/etc/man/cargo-update.1

+8-9
Original file line numberDiff line numberDiff line change
@@ -6,38 +6,37 @@
66
.SH "NAME"
77
cargo\-update \[em] Update dependencies as recorded in the local lock file
88
.SH "SYNOPSIS"
9-
\fBcargo update\fR [\fIoptions\fR]
9+
\fBcargo update\fR [\fIoptions\fR] \fIspec\fR
1010
.SH "DESCRIPTION"
1111
This command will update dependencies in the \fBCargo.lock\fR file to the latest
1212
version. If the \fBCargo.lock\fR file does not exist, it will be created with the
1313
latest available versions.
1414
.SH "OPTIONS"
1515
.SS "Update Options"
1616
.sp
17-
\fB\-p\fR \fIspec\fR\[u2026],
18-
\fB\-\-package\fR \fIspec\fR\[u2026]
17+
\fIspec\fR\[u2026]
1918
.RS 4
2019
Update only the specified packages. This flag may be specified
2120
multiple times. See \fBcargo\-pkgid\fR(1) for the SPEC format.
2221
.sp
23-
If packages are specified with the \fB\-p\fR flag, then a conservative update of
22+
If packages are specified with \fIspec\fR, then a conservative update of
2423
the lockfile will be performed. This means that only the dependency specified
2524
by SPEC will be updated. Its transitive dependencies will be updated only if
2625
SPEC cannot be updated without updating dependencies. All other dependencies
2726
will remain locked at their currently recorded versions.
2827
.sp
29-
If \fB\-p\fR is not specified, all dependencies are updated.
28+
If \fIspec\fR is not specified, all dependencies are updated.
3029
.RE
3130
.sp
3231
\fB\-\-aggressive\fR
3332
.RS 4
34-
When used with \fB\-p\fR, dependencies of \fIspec\fR are forced to update as well.
33+
When used with \fIspec\fR, dependencies of \fIspec\fR are forced to update as well.
3534
Cannot be used with \fB\-\-precise\fR\&.
3635
.RE
3736
.sp
3837
\fB\-\-precise\fR \fIprecise\fR
3938
.RS 4
40-
When used with \fB\-p\fR, allows you to specify a specific version number to set
39+
When used with \fIspec\fR, allows you to specify a specific version number to set
4140
the package to. If the package comes from a git repository, this can be a git
4241
revision (such as a SHA hash or tag).
4342
.RE
@@ -200,7 +199,7 @@ cargo update
200199
.sp
201200
.RS 4
202201
.nf
203-
cargo update \-p foo \-p bar
202+
cargo update foo bar
204203
.fi
205204
.RE
206205
.RE
@@ -210,7 +209,7 @@ cargo update \-p foo \-p bar
210209
.sp
211210
.RS 4
212211
.nf
213-
cargo update \-p foo \-\-precise 1.2.3
212+
cargo update foo \-\-precise 1.2.3
214213
.fi
215214
.RE
216215
.RE

0 commit comments

Comments
 (0)