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.

src/bin/cargo/commands/update.rs

@@ -38,7 +38,7 @@ pub fn cli() -> Command {
         .arg(
             flag(
                 "breaking",
-                "Upgrade [SPEC] to latest breaking versions, unless pinned (unstable)",
+                "Update [SPEC] to latest SemVer-breaking version (unstable)",
             )
             .short('b'),
         )

src/doc/man/cargo-update.md

@@ -51,6 +51,23 @@ A compatible `pre-release` version can also be specified even when the version
 requirement in `Cargo.toml` doesn't contain any pre-release identifier (nightly only).
 {{/option}}
 
+{{#option "`--breaking` _directory_" }}
+Update _spec_ to latest SemVer-breaking version.
+
+Version requirements will be modified to allow this update.
+
+This only applies to dependencies when
+- The package is a dependency of a workspace member
+- The dependency is not renamed
+- A SemVer-incompatible version is available
+- The "SemVer operator" is used (`^` which is the default)
+
+This option is unstable and available only on the
+[nightly channel](https://doc.rust-lang.org/book/appendix-07-nightly-rust.html)
+and requires the `-Z unstable-options` flag to enable.
+See <https://github.com/rust-lang/cargo/issues/12425> for more information.
+{{/option}}
+
 {{#option "`-w`" "`--workspace`" }}
 Attempt to update only packages defined in the workspace. Other packages
 are updated only if they don't already exist in the lockfile. This

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

@@ -43,6 +43,27 @@ OPTIONS
            version requirement in Cargo.toml doesn’t contain any pre-release
            identifier (nightly only).
 
+       --breaking directory
+           Update spec to latest SemVer-breaking version.
+
+           Version requirements will be modified to allow this update.
+
+           This only applies to dependencies when
+
+           o  The package is a dependency of a workspace member
+
+           o  The dependency is not renamed
+
+           o  A SemVer-incompatible version is available
+
+           o  The “SemVer operator” is used (^ which is the default)
+
+           This option is unstable and available only on the nightly channel
+           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
+           requires the -Z unstable-options flag to enable. See
+           <https://github.com/rust-lang/cargo/issues/12425> for more
+           information.
+
        -w, --workspace
            Attempt to update only packages defined in the workspace. Other
            packages are updated only if they don’t already exist in the

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

@@ -47,6 +47,22 @@ from the maintainers of the package.</p>
 requirement in <code>Cargo.toml</code> doesn’t contain any pre-release identifier (nightly only).</dd>
 
 
+<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>
+<dd class="option-desc">Update <em>spec</em> to latest SemVer-breaking version.</p>
+<p>Version requirements will be modified to allow this update.</p>
+<p>This only applies to dependencies when</p>
+<ul>
+<li>The package is a dependency of a workspace member</li>
+<li>The dependency is not renamed</li>
+<li>A SemVer-incompatible version is available</li>
+<li>The “SemVer operator” is used (<code>^</code> which is the default)</li>
+</ul>
+<p>This option is unstable and available only on the
+<a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly channel</a>
+and requires the <code>-Z unstable-options</code> flag to enable.
+See <a href="https://github.com/rust-lang/cargo/issues/12425">https://github.com/rust-lang/cargo/issues/12425</a> for more information.</dd>
+
+
 <dt class="option-term" id="option-cargo-update--w"><a class="option-anchor" href="#option-cargo-update--w"></a><code>-w</code></dt>
 <dt class="option-term" id="option-cargo-update---workspace"><a class="option-anchor" href="#option-cargo-update---workspace"></a><code>--workspace</code></dt>
 <dd class="option-desc">Attempt to update only packages defined in the workspace. Other packages

src/doc/src/reference/unstable.md

@@ -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
 
 * Tracking Issue: [#12425](https://github.com/rust-lang/cargo/issues/12425)
 
-This feature allows upgrading dependencies to breaking versions with
-`update --breaking`.
+Allow upgrading dependencies version requirements in `Cargo.toml` across SemVer
+incompatible versions using with the `--breaking` flag.
 
-This is essentially migrating `cargo upgrade` from `cargo-edit` into Cargo itself, 
-and involves making changes to the `Cargo.toml` manifests, not just the lock file.
+This only applies to dependencies when
+- The package is a dependency of a workspace member
+- The dependency is not renamed
+- A SemVer-incompatible version is available
+- The "SemVer operator" is used (`^` which is the default)
 
-When doing a breaking update, Cargo will keep all non-breaking dependencies
-unchanged. It will also not change any dependencies that use a different version
-operator than the default caret. Also, it will not upgrade any renamed package
-dependencies. Example:
+Users may further restrict which packages get upgraded by specifying them on
+the command line.
 
-```sh
-cargo +nightly update --breaking -Z unstable-options
+Example:
+```console
+$ cargo +nightly -Zunstable-options update --breaking
+$ cargo +nightly -Zunstable-options update --breaking clap
 ```
 
+*This is meant to fill a similar role as [cargo-upgrade](https://github.com/killercup/cargo-edit/)*
+
 ## build-std
 * Tracking Repository: <https://github.com/rust-lang/wg-cargo-std-aware>
 

src/etc/man/cargo-update.1

@@ -48,6 +48,36 @@ A compatible \fBpre\-release\fR version can also be specified even when the vers
 requirement in \fBCargo.toml\fR doesn\[cq]t contain any pre\-release identifier (nightly only).
 .RE
 .sp
+\fB\-\-breaking\fR \fIdirectory\fR
+.RS 4
+Update \fIspec\fR to latest SemVer\-breaking version.
+.sp
+Version requirements will be modified to allow this update.
+.sp
+This only applies to dependencies when
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'The package is a dependency of a workspace member
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'The dependency is not renamed
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'A SemVer\-incompatible version is available
+.RE
+.sp
+.RS 4
+\h'-04'\(bu\h'+02'The \[lq]SemVer operator\[rq] is used (\fB^\fR which is the default)
+.RE
+.sp
+This option is unstable and available only on the
+\fInightly channel\fR <https://doc.rust\-lang.org/book/appendix\-07\-nightly\-rust.html>
+and requires the \fB\-Z unstable\-options\fR flag to enable.
+See <https://github.com/rust\-lang/cargo/issues/12425> for more information.
+.RE
+.sp
 \fB\-w\fR, 
 \fB\-\-workspace\fR
 .RS 4