From 96b446237db31e35aaa0470ce37231bd63bc9e19 Mon Sep 17 00:00:00 2001
From: di3go04 <di3go04@users.noreply.github.com>
Date: Tue, 30 Jun 2026 06:20:24 -0500
Subject: [PATCH 1/6] fix(cli): clarify -Z help output and note rustc flags

Updates the -Z help output per the design proposed in #17145: clarifies these are cargo flags, reformats the channel warning to rustc diagnostic style, and adds a note pointing to rustc -Zhelp for rustc flags.
---
 src/bin/cargo/cli.rs                         | 13 +++++++------
 tests/testsuite/cargo/z_help/stdout.term.svg |  8 ++++++--
 2 files changed, 13 insertions(+), 8 deletions(-)

diff --git a/src/bin/cargo/cli.rs b/src/bin/cargo/cli.rs
index 83eba6895a7..df26ac18785 100644
--- a/src/bin/cargo/cli.rs
+++ b/src/bin/cargo/cli.rs
@@ -125,7 +125,7 @@ fn print_zhelp(gctx: &GlobalContext) {
     drop_println!(
         gctx,
         "\
-{header}Available unstable (nightly-only) flags:{header:#}
+{header}Available unstable (nightly-only) cargo flags:{header:#}
 
 {z_flags}
 
@@ -134,17 +134,18 @@ Run with `{literal}cargo -Z{literal:#} {placeholder}[FLAG] [COMMAND]{placeholder
     if !gctx.nightly_features_allowed {
         drop_println!(
             gctx,
-            "\nUnstable flags are only available on the nightly channel \
-                 of Cargo, but this is the `{}` channel.\n\
-                 {}",
+            "\n{header}warn:{header:#} unstable flags are unavailable on the current (`{}`) channel,\n \
+             {header}| help:{header:#} run on the nightly channel to use them\n \
+             {header}| help:{header:#} see {channels} for more information about Rust release channels.",
             features::channel(),
-            features::SEE_CHANNELS
+            channels = features::SEE_CHANNELS,
         );
     }
     drop_println!(
         gctx,
         "\nSee https://doc.rust-lang.org/nightly/cargo/reference/unstable.html \
-             for more information about these flags."
+             for more information about these flags.\n\n\
+             note: to see rustc unstable features, run `rustc -Zhelp`"
     );
 }
 
diff --git a/tests/testsuite/cargo/z_help/stdout.term.svg b/tests/testsuite/cargo/z_help/stdout.term.svg
index c3feb8b2e72..75dba04db57 100644
--- a/tests/testsuite/cargo/z_help/stdout.term.svg
+++ b/tests/testsuite/cargo/z_help/stdout.term.svg
@@ -1,4 +1,4 @@
-<svg width="1255px" height="1010px" xmlns="http://www.w3.org/2000/svg">
+<svg width="1255px" height="1050px" xmlns="http://www.w3.org/2000/svg">
   <style>
     .fg { fill: #AAAAAA }
     .bg { fill: #000000 }
@@ -16,7 +16,7 @@
   <rect width="100%" height="100%" y="0" rx="4.5" class="bg" />
 
   <text xml:space="preserve" class="container fg">
-    <tspan x="10px" y="28px"><tspan>Available unstable (nightly-only) flags:</tspan>
+    <tspan x="10px" y="28px"><tspan>Available unstable (nightly-only) cargo flags:</tspan>
 </tspan>
     <tspan x="10px" y="46px">
 </tspan>
@@ -125,6 +125,10 @@
     <tspan x="10px" y="982px"><tspan>See https://doc.rust-lang.org/nightly/cargo/reference/unstable.html for more information about these flags.</tspan>
 </tspan>
     <tspan x="10px" y="1000px">
+</tspan>
+    <tspan x="10px" y="1018px"><tspan>note: to see rustc unstable features, run `rustc -Zhelp`</tspan>
+</tspan>
+    <tspan x="10px" y="1036px">
 </tspan>
   </text>
 

From c22b76abe8297bbb012046c6bb211599e5b9dafc Mon Sep 17 00:00:00 2001
From: di3go04 <di3go04@users.noreply.github.com>
Date: Wed, 8 Jul 2026 06:24:25 +0000
Subject: [PATCH 2/6] refactor(z_help): use annotate-snippets for
 warn/help/note

Per @epage's feedback, use annotate-snippets (Level::WARNING with
Level::HELP elements via print_report, and shell().note() for the
rustc note) instead of manually imitating the warn:/help:/note:
diagnostic style with drop_println!.

Changes:
- Warning + help messages now use Level::WARNING.secondary_title()
  with Level::HELP.message() elements via print_report (stderr)
- The rustc -Zhelp note now uses shell().note() which internally
  uses annotate-snippets Level::NOTE (stderr)
- The 'See https://...' line stays on stdout via drop_println!
- Updated stdout.term.svg to remove the note (now on stderr)
- Added stderr.term.svg with the expected note rendering
- Updated the test to check stderr against the new SVG
---
 src/bin/cargo/cli.rs                         | 28 +++++++++++++-------
 tests/testsuite/cargo/z_help/mod.rs          |  3 +--
 tests/testsuite/cargo/z_help/stderr.term.svg | 27 +++++++++++++++++++
 tests/testsuite/cargo/z_help/stdout.term.svg |  6 +----
 4 files changed, 47 insertions(+), 17 deletions(-)
 create mode 100644 tests/testsuite/cargo/z_help/stderr.term.svg

diff --git a/src/bin/cargo/cli.rs b/src/bin/cargo/cli.rs
index df26ac18785..c5b567398f6 100644
--- a/src/bin/cargo/cli.rs
+++ b/src/bin/cargo/cli.rs
@@ -132,21 +132,29 @@ fn print_zhelp(gctx: &GlobalContext) {
 Run with `{literal}cargo -Z{literal:#} {placeholder}[FLAG] [COMMAND]{placeholder:#}`",
     );
     if !gctx.nightly_features_allowed {
-        drop_println!(
-            gctx,
-            "\n{header}warn:{header:#} unstable flags are unavailable on the current (`{}`) channel,\n \
-             {header}| help:{header:#} run on the nightly channel to use them\n \
-             {header}| help:{header:#} see {channels} for more information about Rust release channels.",
-            features::channel(),
-            channels = features::SEE_CHANNELS,
-        );
+        let report = [Level::WARNING
+            .secondary_title(format!(
+                "unstable flags are unavailable on the current (`{}`) channel",
+                features::channel()
+            ))
+            .element(Level::HELP.message(
+                "run on the nightly channel to use them",
+            ))
+            .element(
+                Level::HELP.message(format!(
+                    "see {} for more information about Rust release channels",
+                    features::SEE_CHANNELS
+                )),
+            )];
+        gctx.shell().print_report(&report, false)?;
     }
     drop_println!(
         gctx,
         "\nSee https://doc.rust-lang.org/nightly/cargo/reference/unstable.html \
-             for more information about these flags.\n\n\
-             note: to see rustc unstable features, run `rustc -Zhelp`"
+             for more information about these flags."
     );
+    gctx.shell()
+        .note("to see rustc unstable features, run `rustc -Zhelp`")?;
 }
 
 fn print_list(gctx: &GlobalContext, is_verbose: bool) {
diff --git a/tests/testsuite/cargo/z_help/mod.rs b/tests/testsuite/cargo/z_help/mod.rs
index 9104d418b52..65ee33e84a9 100644
--- a/tests/testsuite/cargo/z_help/mod.rs
+++ b/tests/testsuite/cargo/z_help/mod.rs
@@ -1,6 +1,5 @@
 use crate::prelude::*;
 use cargo_test_support::file;
-use cargo_test_support::str;
 
 #[cargo_test]
 fn case() {
@@ -10,5 +9,5 @@ fn case() {
         .assert()
         .success()
         .stdout_eq(file!["stdout.term.svg"])
-        .stderr_eq(str![""]);
+        .stderr_eq(file!["stderr.term.svg"]);
 }
diff --git a/tests/testsuite/cargo/z_help/stderr.term.svg b/tests/testsuite/cargo/z_help/stderr.term.svg
new file mode 100644
index 00000000000..71aded0d540
--- /dev/null
+++ b/tests/testsuite/cargo/z_help/stderr.term.svg
@@ -0,0 +1,27 @@
+<svg width="1255px" height="64px" xmlns="http://www.w3.org/2000/svg">
+  <style>
+    .fg { fill: #AAAAAA }
+    .bg { fill: #000000 }
+    .fg-bright-green { fill: #55FF55 }
+    .container {
+      padding: 0 10px;
+      line-height: 18px;
+    }
+    .bold { font-weight: bold; }
+    tspan {
+      font: 14px SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace;
+      white-space: pre;
+      line-height: 18px;
+    }
+  </style>
+
+  <rect width="100%" height="100%" y="0" rx="4.5" class="bg" />
+
+  <text xml:space="preserve" class="container fg">
+    <tspan x="10px" y="28px"><tspan class="fg-bright-green bold">note</tspan><tspan>: to see rustc unstable features, run `rustc -Zhelp`</tspan>
+</tspan>
+    <tspan x="10px" y="46px">
+</tspan>
+  </text>
+
+</svg>
diff --git a/tests/testsuite/cargo/z_help/stdout.term.svg b/tests/testsuite/cargo/z_help/stdout.term.svg
index 75dba04db57..b37a8323ed8 100644
--- a/tests/testsuite/cargo/z_help/stdout.term.svg
+++ b/tests/testsuite/cargo/z_help/stdout.term.svg
@@ -1,4 +1,4 @@
-<svg width="1255px" height="1050px" xmlns="http://www.w3.org/2000/svg">
+<svg width="1255px" height="1010px" xmlns="http://www.w3.org/2000/svg">
   <style>
     .fg { fill: #AAAAAA }
     .bg { fill: #000000 }
@@ -125,10 +125,6 @@
     <tspan x="10px" y="982px"><tspan>See https://doc.rust-lang.org/nightly/cargo/reference/unstable.html for more information about these flags.</tspan>
 </tspan>
     <tspan x="10px" y="1000px">
-</tspan>
-    <tspan x="10px" y="1018px"><tspan>note: to see rustc unstable features, run `rustc -Zhelp`</tspan>
-</tspan>
-    <tspan x="10px" y="1036px">
 </tspan>
   </text>
 

From f045712696335a54dfabff441782bfb8cd1638ea Mon Sep 17 00:00:00 2001
From: di3go04 <di3go04@users.noreply.github.com>
Date: Wed, 8 Jul 2026 06:27:14 +0000
Subject: [PATCH 3/6] style(z_help): match rustfmt formatting conventions

Align the print_report call with the existing style used elsewhere
in cli.rs (e.g. the alias shadowing warnings): secondary_title and
element calls chained on the same line, without trailing commas
inside element().
---
 src/bin/cargo/cli.rs | 31 ++++++++++++++++---------------
 1 file changed, 16 insertions(+), 15 deletions(-)

diff --git a/src/bin/cargo/cli.rs b/src/bin/cargo/cli.rs
index c5b567398f6..7ade5442e0f 100644
--- a/src/bin/cargo/cli.rs
+++ b/src/bin/cargo/cli.rs
@@ -132,21 +132,22 @@ fn print_zhelp(gctx: &GlobalContext) {
 Run with `{literal}cargo -Z{literal:#} {placeholder}[FLAG] [COMMAND]{placeholder:#}`",
     );
     if !gctx.nightly_features_allowed {
-        let report = [Level::WARNING
-            .secondary_title(format!(
-                "unstable flags are unavailable on the current (`{}`) channel",
-                features::channel()
-            ))
-            .element(Level::HELP.message(
-                "run on the nightly channel to use them",
-            ))
-            .element(
-                Level::HELP.message(format!(
-                    "see {} for more information about Rust release channels",
-                    features::SEE_CHANNELS
-                )),
-            )];
-        gctx.shell().print_report(&report, false)?;
+        gctx.shell().print_report(
+            &[
+                Level::WARNING.secondary_title(format!(
+                    "unstable flags are unavailable on the current (`{}`) channel",
+                    features::channel()
+                )).element(
+                    Level::HELP.message("run on the nightly channel to use them")
+                ).element(
+                    Level::HELP.message(format!(
+                        "see {} for more information about Rust release channels",
+                        features::SEE_CHANNELS
+                    ))
+                ),
+            ],
+            false,
+        )?;
     }
     drop_println!(
         gctx,

From a42cb84e48b52e0c94469603e84742f81c693326 Mon Sep 17 00:00:00 2001
From: di3go04 <di3go04@users.noreply.github.com>
Date: Wed, 8 Jul 2026 06:31:38 +0000
Subject: [PATCH 4/6] style: apply rustfmt to print_zhelp

---
 src/bin/cargo/cli.rs | 19 ++++++++-----------
 1 file changed, 8 insertions(+), 11 deletions(-)

diff --git a/src/bin/cargo/cli.rs b/src/bin/cargo/cli.rs
index 7ade5442e0f..17cb9ac4c54 100644
--- a/src/bin/cargo/cli.rs
+++ b/src/bin/cargo/cli.rs
@@ -133,19 +133,16 @@ Run with `{literal}cargo -Z{literal:#} {placeholder}[FLAG] [COMMAND]{placeholder
     );
     if !gctx.nightly_features_allowed {
         gctx.shell().print_report(
-            &[
-                Level::WARNING.secondary_title(format!(
+            &[Level::WARNING
+                .secondary_title(format!(
                     "unstable flags are unavailable on the current (`{}`) channel",
                     features::channel()
-                )).element(
-                    Level::HELP.message("run on the nightly channel to use them")
-                ).element(
-                    Level::HELP.message(format!(
-                        "see {} for more information about Rust release channels",
-                        features::SEE_CHANNELS
-                    ))
-                ),
-            ],
+                ))
+                .element(Level::HELP.message("run on the nightly channel to use them"))
+                .element(Level::HELP.message(format!(
+                    "see {} for more information about Rust release channels",
+                    features::SEE_CHANNELS
+                )))],
             false,
         )?;
     }

From 7a6742f4141200953d095ef5916f86df7d9021c5 Mon Sep 17 00:00:00 2001
From: di3go04 <di3go04@users.noreply.github.com>
Date: Wed, 8 Jul 2026 06:50:26 +0000
Subject: [PATCH 5/6] fix(z_help): use str! for stderr expectation, fix
 compilation error

- Use str! with [NOTE] placeholder for stderr instead of SVG file
  (simpler and matches the snapbox pattern used elsewhere)
- Fix compilation: print_zhelp returns () so use 'let _ =' for
  print_report/note calls instead of ? operator
---
 src/bin/cargo/cli.rs                         |  9 ++++---
 tests/testsuite/cargo/z_help/mod.rs          |  6 ++++-
 tests/testsuite/cargo/z_help/stderr.term.svg | 27 --------------------
 3 files changed, 10 insertions(+), 32 deletions(-)
 delete mode 100644 tests/testsuite/cargo/z_help/stderr.term.svg

diff --git a/src/bin/cargo/cli.rs b/src/bin/cargo/cli.rs
index 17cb9ac4c54..d677a0e7829 100644
--- a/src/bin/cargo/cli.rs
+++ b/src/bin/cargo/cli.rs
@@ -132,7 +132,7 @@ fn print_zhelp(gctx: &GlobalContext) {
 Run with `{literal}cargo -Z{literal:#} {placeholder}[FLAG] [COMMAND]{placeholder:#}`",
     );
     if !gctx.nightly_features_allowed {
-        gctx.shell().print_report(
+        let _ = gctx.shell().print_report(
             &[Level::WARNING
                 .secondary_title(format!(
                     "unstable flags are unavailable on the current (`{}`) channel",
@@ -144,15 +144,16 @@ Run with `{literal}cargo -Z{literal:#} {placeholder}[FLAG] [COMMAND]{placeholder
                     features::SEE_CHANNELS
                 )))],
             false,
-        )?;
+        );
     }
     drop_println!(
         gctx,
         "\nSee https://doc.rust-lang.org/nightly/cargo/reference/unstable.html \
              for more information about these flags."
     );
-    gctx.shell()
-        .note("to see rustc unstable features, run `rustc -Zhelp`")?;
+    let _ = gctx
+        .shell()
+        .note("to see rustc unstable features, run `rustc -Zhelp`");
 }
 
 fn print_list(gctx: &GlobalContext, is_verbose: bool) {
diff --git a/tests/testsuite/cargo/z_help/mod.rs b/tests/testsuite/cargo/z_help/mod.rs
index 65ee33e84a9..230bad4a27b 100644
--- a/tests/testsuite/cargo/z_help/mod.rs
+++ b/tests/testsuite/cargo/z_help/mod.rs
@@ -1,5 +1,6 @@
 use crate::prelude::*;
 use cargo_test_support::file;
+use cargo_test_support::str;
 
 #[cargo_test]
 fn case() {
@@ -9,5 +10,8 @@ fn case() {
         .assert()
         .success()
         .stdout_eq(file!["stdout.term.svg"])
-        .stderr_eq(file!["stderr.term.svg"]);
+        .stderr_eq(str![[r#"
+[NOTE] to see rustc unstable features, run `rustc -Zhelp`
+
+"#]]);
 }
diff --git a/tests/testsuite/cargo/z_help/stderr.term.svg b/tests/testsuite/cargo/z_help/stderr.term.svg
deleted file mode 100644
index 71aded0d540..00000000000
--- a/tests/testsuite/cargo/z_help/stderr.term.svg
+++ /dev/null
@@ -1,27 +0,0 @@
-<svg width="1255px" height="64px" xmlns="http://www.w3.org/2000/svg">
-  <style>
-    .fg { fill: #AAAAAA }
-    .bg { fill: #000000 }
-    .fg-bright-green { fill: #55FF55 }
-    .container {
-      padding: 0 10px;
-      line-height: 18px;
-    }
-    .bold { font-weight: bold; }
-    tspan {
-      font: 14px SFMono-Regular, Consolas, Liberation Mono, Menlo, monospace;
-      white-space: pre;
-      line-height: 18px;
-    }
-  </style>
-
-  <rect width="100%" height="100%" y="0" rx="4.5" class="bg" />
-
-  <text xml:space="preserve" class="container fg">
-    <tspan x="10px" y="28px"><tspan class="fg-bright-green bold">note</tspan><tspan>: to see rustc unstable features, run `rustc -Zhelp`</tspan>
-</tspan>
-    <tspan x="10px" y="46px">
-</tspan>
-  </text>
-
-</svg>

From aa20e1a8c0271a6ef18da04e5354ef9f5d1c11ce Mon Sep 17 00:00:00 2001
From: di3go04 <di3go04@users.noreply.github.com>
Date: Wed, 8 Jul 2026 07:52:08 +0000
Subject: [PATCH 6/6] fix(z_help): use annotate-snippets for warn/help, keep
 note on stdout

Per @epage's feedback, use annotate-snippets (Level::WARNING with
Level::HELP elements via print_report) for the warn:/help: messages
instead of manually imitating the diagnostic style.

The note about rustc -Zhelp stays as plain text on stdout via
drop_println! since it's an informational pointer, not a diagnostic.
This also restores the original stdout.term.svg and test expectations.
---
 src/bin/cargo/cli.rs                         | 6 ++----
 tests/testsuite/cargo/z_help/mod.rs          | 5 +----
 tests/testsuite/cargo/z_help/stdout.term.svg | 6 +++++-
 3 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/src/bin/cargo/cli.rs b/src/bin/cargo/cli.rs
index d677a0e7829..5f8733e6959 100644
--- a/src/bin/cargo/cli.rs
+++ b/src/bin/cargo/cli.rs
@@ -149,11 +149,9 @@ Run with `{literal}cargo -Z{literal:#} {placeholder}[FLAG] [COMMAND]{placeholder
     drop_println!(
         gctx,
         "\nSee https://doc.rust-lang.org/nightly/cargo/reference/unstable.html \
-             for more information about these flags."
+             for more information about these flags.\n\n\
+             note: to see rustc unstable features, run `rustc -Zhelp`"
     );
-    let _ = gctx
-        .shell()
-        .note("to see rustc unstable features, run `rustc -Zhelp`");
 }
 
 fn print_list(gctx: &GlobalContext, is_verbose: bool) {
diff --git a/tests/testsuite/cargo/z_help/mod.rs b/tests/testsuite/cargo/z_help/mod.rs
index 230bad4a27b..9104d418b52 100644
--- a/tests/testsuite/cargo/z_help/mod.rs
+++ b/tests/testsuite/cargo/z_help/mod.rs
@@ -10,8 +10,5 @@ fn case() {
         .assert()
         .success()
         .stdout_eq(file!["stdout.term.svg"])
-        .stderr_eq(str![[r#"
-[NOTE] to see rustc unstable features, run `rustc -Zhelp`
-
-"#]]);
+        .stderr_eq(str![""]);
 }
diff --git a/tests/testsuite/cargo/z_help/stdout.term.svg b/tests/testsuite/cargo/z_help/stdout.term.svg
index b37a8323ed8..75dba04db57 100644
--- a/tests/testsuite/cargo/z_help/stdout.term.svg
+++ b/tests/testsuite/cargo/z_help/stdout.term.svg
@@ -1,4 +1,4 @@
-<svg width="1255px" height="1010px" xmlns="http://www.w3.org/2000/svg">
+<svg width="1255px" height="1050px" xmlns="http://www.w3.org/2000/svg">
   <style>
     .fg { fill: #AAAAAA }
     .bg { fill: #000000 }
@@ -125,6 +125,10 @@
     <tspan x="10px" y="982px"><tspan>See https://doc.rust-lang.org/nightly/cargo/reference/unstable.html for more information about these flags.</tspan>
 </tspan>
     <tspan x="10px" y="1000px">
+</tspan>
+    <tspan x="10px" y="1018px"><tspan>note: to see rustc unstable features, run `rustc -Zhelp`</tspan>
+</tspan>
+    <tspan x="10px" y="1036px">
 </tspan>
   </text>