document the -Zallow-yanked-deps unstable CLI flag

Author: pietroalbini

src/bin/cargo/cli.rs

@@ -28,13 +28,14 @@ pub fn main(config: &mut Config) -> CliResult {
             "
 Available unstable (nightly-only) flags:
 
-    -Z avoid-dev-deps   -- Avoid installing dev-dependencies if possible
-    -Z minimal-versions -- Install minimal dependency versions instead of maximum
-    -Z no-index-update  -- Do not update the registry, avoids a network request for benchmarking
-    -Z offline          -- Offline mode that does not perform network requests
-    -Z unstable-options -- Allow the usage of unstable options such as --registry
-    -Z config-profile   -- Read profiles from .cargo/config files
-    -Z compile-progress -- Display a progress bar while compiling
+    -Z avoid-dev-deps    -- Avoid installing dev-dependencies if possible
+    -Z minimal-versions  -- Install minimal dependency versions instead of maximum
+    -Z no-index-update   -- Do not update the registry, avoids a network request for benchmarking
+    -Z offline           -- Offline mode that does not perform network requests
+    -Z unstable-options  -- Allow the usage of unstable options such as --registry
+    -Z config-profile    -- Read profiles from .cargo/config files
+    -Z compile-progress  -- Display a progress bar while compiling
+    -Z allow-yanked-deps -- Allow depending on yanked crates
 
 Run with 'cargo -Z [FLAG] [SUBCOMMAND]'"
         );

src/doc/src/reference/unstable.md

@@ -198,6 +198,18 @@ directory.  Example:
 cargo +nightly build --out-dir=out -Z unstable-options
 ```
 
+## allow-yanked-deps
+* Original Issue: [#4425](https://github.com/rust-lang/cargo/issues/4225)
+
+This feature allows your project to depend on yanked crates.
+
+The flag can be useful if you need to build an old project that relies on a
+yanked dependency, and you can't update it. The flag should not be used on new
+or maintained projects: remember that yanked crates are not meant to be used.
+
+```
+cargo +nightly build -Z allow-yanked-deps
+```
 
 ### Edition
 * Tracking Issue: [rust-lang/rust#44581](https://github.com/rust-lang/rust/issues/44581)

tests/testsuite/cargo_command.rs

@@ -315,6 +315,6 @@ fn explain() {
 fn z_flags_help() {
     cargo_process("-Z help")
         .with_stdout_contains(
-            "    -Z unstable-options -- Allow the usage of unstable options such as --registry",
+            "    -Z unstable-options  -- Allow the usage of unstable options such as --registry",
         ).run();
 }