Skip to content

Commit 1e804fc

Browse files
epageepage
committed
docs: Iterate on --breaking docs
This is a follow up to rust-lang#13979 to try to clarify things in prep for users testing this.
1 parent b134eff commit 1e804fc

File tree

7 files changed

+101
-12
lines changed

7 files changed

+101
-12
lines changed

Diff for: ‎src/bin/cargo/commands/update.rs

+1-1
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ pub fn cli() -> Command {
3838
.arg(
3939
flag(
4040
"breaking",
41-
"Upgrade [SPEC] to latest breaking versions, unless pinned (unstable)",
41+
"Update [SPEC] to latest semver-breaking version (unstable)",
4242
)
4343
.short('b'),
4444
)

Diff for: ‎src/doc/man/cargo-update.md

+17
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,23 @@ A compatible `pre-release` version can also be specified even when the version
5151
requirement in `Cargo.toml` doesn't contain any pre-release identifier (nightly only).
5252
{{/option}}
5353

54+
{{#option "`--breaking` _directory_" }}
55+
Update _spec_ to latest semver-breaking version.
56+
57+
Version requirements will be modified to allow this update.
58+
59+
This only applies to dependencies when
60+
- The package is a dependency of a workspace member
61+
- The dependency is not renamed
62+
- A semver-incompatible version is available
63+
- The "semver operator" is used (`^` which is the default)
64+
65+
This option is unstable and available only on the
66+
[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html)
67+
and requires the `-Z unstable-options` flag to enable.
68+
See <https://github.com/rust-lang/cargo/issues/12425> for more information.
69+
{{/option}}
70+
5471
{{#option "`-w`" "`--workspace`" }}
5572
Attempt to update only packages defined in the workspace. Other packages
5673
are updated only if they don't already exist in the lockfile. This

Diff for: ‎src/doc/man/generated_txt/cargo-update.txt

+21
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,27 @@ OPTIONS
4343
version requirement in Cargo.toml doesn’t contain any pre-release
4444
identifier (nightly only).
4545

46+
--breaking directory
47+
Update spec to latest semver-breaking version.
48+
49+
Version requirements will be modified to allow this update.
50+
51+
This only applies to dependencies when
52+
53+
o The package is a dependency of a workspace member
54+
55+
o The dependency is not renamed
56+
57+
o A semver-incompatible version is available
58+
59+
o The “semver operator” is used (^ which is the default)
60+
61+
This option is unstable and available only on the nightly channel
62+
<https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
63+
requires the -Z unstable-options flag to enable. See
64+
<https://github.com/rust-lang/cargo/issues/12425> for more
65+
information.
66+
4667
-w, --workspace
4768
Attempt to update only packages defined in the workspace. Other
4869
packages are updated only if they don’t already exist in the

Diff for: ‎src/doc/src/commands/cargo-update.md

+16
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,22 @@ from the maintainers of the package.</p>
4747
requirement in <code>Cargo.toml</code> doesn’t contain any pre-release identifier (nightly only).</dd>
4848

4949

50+
<dt class="option-term" id="option-cargo-update---breaking"><a class="option-anchor" href="#option-cargo-update---breaking"></a><code>--breaking</code> <em>directory</em></dt>
51+
<dd class="option-desc">Update <em>spec</em> to latest semver-breaking version.</p>
52+
<p>Version requirements will be modified to allow this update.</p>
53+
<p>This only applies to dependencies when</p>
54+
<ul>
55+
<li>The package is a dependency of a workspace member</li>
56+
<li>The dependency is not renamed</li>
57+
<li>A semver-incompatible version is available</li>
58+
<li>The “semver operator” is used (<code>^</code> which is the default)</li>
59+
</ul>
60+
<p>This option is unstable and available only on the
61+
<a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly channel</a>
62+
and requires the <code>-Z unstable-options</code> flag to enable.
63+
See <a href="https://github.com/rust-lang/cargo/issues/12425">https://github.com/rust-lang/cargo/issues/12425</a> for more information.</dd>
64+
65+
5066
<dt class="option-term" id="option-cargo-update--w"><a class="option-anchor" href="#option-cargo-update--w"></a><code>-w</code></dt>
5167
<dt class="option-term" id="option-cargo-update---workspace"><a class="option-anchor" href="#option-cargo-update---workspace"></a><code>--workspace</code></dt>
5268
<dd class="option-desc">Attempt to update only packages defined in the workspace. Other packages

Diff for: ‎src/doc/src/reference/unstable.md

+15-10
Original file line numberDiff line numberDiff line change
@@ -383,21 +383,26 @@ It would not be possible to upgrade to `0.2.0-pre.0` from `0.1.1` in the same wa
383383

384384
* Tracking Issue: [#12425](https://github.com/rust-lang/cargo/issues/12425)
385385

386-
This feature allows upgrading dependencies to breaking versions with
387-
`update --breaking`.
386+
Allow upgrading dependencies version requirements in `Cargo.toml` across semver
387+
incompatible versions using with the `--breaking` flag.
388388

389-
This is essentially migrating `cargo upgrade` from `cargo-edit` into Cargo itself,
390-
and involves making changes to the `Cargo.toml` manifests, not just the lock file.
389+
This only applies to dependencies when
390+
- The package is a dependency of a workspace member
391+
- The dependency is not renamed
392+
- A semver-incompatible version is available
393+
- The "semver operator" is used (`^` which is the default)
391394

392-
When doing a breaking update, Cargo will keep all non-breaking dependencies
393-
unchanged. It will also not change any dependencies that use a different version
394-
operator than the default caret. Also, it will not upgrade any renamed package
395-
dependencies. Example:
395+
Users may further restrict which packages get upgraded by specifying them on
396+
the command line.
396397

397-
```sh
398-
cargo +nightly update --breaking -Z unstable-options
398+
Example:
399+
```console
400+
$ cargo +nightly -Zunstable-options update --breaking
401+
$ cargo +nightly -Zunstable-options update --breaking clap
399402
```
400403

404+
*This is meant to fill a similar role as [cargo-upgrade](https://github.com/killercup/cargo-edit/)*
405+
401406
## build-std
402407
* Tracking Repository: <https://github.com/rust-lang/wg-cargo-std-aware>
403408

Diff for: ‎src/etc/man/cargo-update.1

+30
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,36 @@ A compatible \fBpre\-release\fR version can also be specified even when the vers
4848
requirement in \fBCargo.toml\fR doesn\[cq]t contain any pre\-release identifier (nightly only).
4949
.RE
5050
.sp
51+
\fB\-\-breaking\fR \fIdirectory\fR
52+
.RS 4
53+
Update \fIspec\fR to latest semver\-breaking version.
54+
.sp
55+
Version requirements will be modified to allow this update.
56+
.sp
57+
This only applies to dependencies when
58+
.sp
59+
.RS 4
60+
\h'-04'\(bu\h'+02'The package is a dependency of a workspace member
61+
.RE
62+
.sp
63+
.RS 4
64+
\h'-04'\(bu\h'+02'The dependency is not renamed
65+
.RE
66+
.sp
67+
.RS 4
68+
\h'-04'\(bu\h'+02'A semver\-incompatible version is available
69+
.RE
70+
.sp
71+
.RS 4
72+
\h'-04'\(bu\h'+02'The \[lq]semver operator\[rq] is used (\fB^\fR which is the default)
73+
.RE
74+
.sp
75+
This option is unstable and available only on the
76+
\fInightly channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html>
77+
and requires the \fB\-Z unstable\-options\fR flag to enable.
78+
See <https://github.com/rust\-lang/cargo/issues/12425> for more information.
79+
.RE
80+
.sp
5181
\fB\-w\fR,
5282
\fB\-\-workspace\fR
5383
.RS 4

Diff for: ‎tests/testsuite/cargo_update/help/stdout.term.svg

+1-1
Loading

0 commit comments

Comments
 (0)