test(help): snapshot cargo help tests

src/bin/cargo/commands/help.rs

@@ -79,18 +79,23 @@ fn try_help(gctx: &GlobalContext, subcommand: &str) -> CargoResult<bool> {
         None => return Ok(false),
     };
 
-    if resolve_executable(Path::new("man")).is_ok() {
-        let man = match extract_man(subcommand, "1") {
-            Some(man) => man,
-            None => return Ok(false),
+    // ALLOWED: For testing cargo itself only.
+    #[allow(clippy::disallowed_methods)]
+    let force_help_text = std::env::var("__CARGO_TEST_FORCE_HELP_TXT").is_ok();
+
+    if resolve_executable(Path::new("man")).is_ok() && !force_help_text {
+        let Some(man) = extract_man(subcommand, "1") else {
+            return Ok(false);
         };
         write_and_spawn(subcommand, &man, "man")?;
     } else {
         let txt = match extract_man(subcommand, "txt") {
             Some(txt) => txt,
             None => return Ok(false),
         };
-        if resolve_executable(Path::new("less")).is_ok() {
+        if force_help_text {
+            drop(std::io::stdout().write_all(&txt));
+        } else if resolve_executable(Path::new("less")).is_ok() {
             write_and_spawn(subcommand, &txt, "less")?;
         } else if resolve_executable(Path::new("more")).is_ok() {
             write_and_spawn(subcommand, &txt, "more")?;

src/doc/man/cargo-help.md

@@ -12,6 +12,26 @@ cargo-help --- Get help for a Cargo command
 
 Prints a help message for the given command.
 
+## OPTIONS
+
+### Display Options
+
+{{#options}}
+{{> options-display }}
+{{/options}}
+
+### Manifest Options
+
+{{#options}}
+{{> options-locked }}
+{{/options}}
+
+{{> section-options-common }}
+
+{{> section-environment }}
+
+{{> section-exit-status }}
+
 ## EXAMPLES
 
 1. Get help for a command:

src/doc/man/cargo-remove.md

@@ -88,9 +88,9 @@ Package to remove from.
 
        cargo remove --dev trybuild
 
-3. Remove `nom` from the `x86_64-pc-windows-gnu` dependencies table
+3. Remove `nom` from the `wasm32-unknown-unknown` dependencies table
 
-       cargo remove --target x86_64-pc-windows-gnu nom
+       cargo remove --target wasm32-unknown-unknown nom
 
 ## SEE ALSO
 {{man "cargo" 1}}, {{man "cargo-add" 1}}

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

@@ -9,6 +9,112 @@ SYNOPSIS
 DESCRIPTION
        Prints a help message for the given command.
 
+OPTIONS
+   Display Options
+       -v, --verbose
+           Use verbose output. May be specified twice for “very verbose”
+           output which includes extra output such as dependency warnings and
+           build script output. May also be specified with the term.verbose
+           config value
+           <https://doc.rust-lang.org/cargo/reference/config.html>.
+
+       -q, --quiet
+           Do not print cargo log messages. May also be specified with the
+           term.quiet config value
+           <https://doc.rust-lang.org/cargo/reference/config.html>.
+
+       --color when
+           Control when colored output is used. Valid values:
+
+           o  auto (default): Automatically detect if color support is
+              available on the terminal.
+
+           o  always: Always display colors.
+
+           o  never: Never display colors.
+
+           May also be specified with the term.color config value
+           <https://doc.rust-lang.org/cargo/reference/config.html>.
+
+   Manifest Options
+       --locked
+           Asserts that the exact same dependencies and versions are used as
+           when the existing Cargo.lock file was originally generated. Cargo
+           will exit with an error when either of the following scenarios
+           arises:
+
+           o  The lock file is missing.
+
+           o  Cargo attempted to change the lock file due to a different
+              dependency resolution.
+
+           It may be used in environments where deterministic builds are
+           desired, such as in CI pipelines.
+
+       --offline
+           Prevents Cargo from accessing the network for any reason. Without
+           this flag, Cargo will stop with an error if it needs to access the
+           network and the network is not available. With this flag, Cargo will
+           attempt to proceed without the network if possible.
+
+           Beware that this may result in different dependency resolution than
+           online mode. Cargo will restrict itself to crates that are
+           downloaded locally, even if there might be a newer version as
+           indicated in the local copy of the index. See the cargo-fetch(1)
+           command to download dependencies before going offline.
+
+           May also be specified with the net.offline config value
+           <https://doc.rust-lang.org/cargo/reference/config.html>.
+
+       --frozen
+           Equivalent to specifying both --locked and --offline.
+
+   Common Options
+       +toolchain
+           If Cargo has been installed with rustup, and the first argument to
+           cargo begins with +, it will be interpreted as a rustup toolchain
+           name (such as +stable or +nightly). See the rustup documentation
+           <https://rust-lang.github.io/rustup/overrides.html> for more
+           information about how toolchain overrides work.
+
+       --config KEY=VALUE or PATH
+           Overrides a Cargo configuration value. The argument should be in
+           TOML syntax of KEY=VALUE, or provided as a path to an extra
+           configuration file. This flag may be specified multiple times. See
+           the command-line overrides section
+           <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides>
+           for more information.
+
+       -C PATH
+           Changes the current working directory before executing any specified
+           operations. This affects things like where cargo looks by default
+           for the project manifest (Cargo.toml), as well as the directories
+           searched for discovering .cargo/config.toml, for example. This
+           option must appear before the command name, for example cargo -C
+           path/to/my-project build.
+
+           This option is only available 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 #10098
+           <https://github.com/rust-lang/cargo/issues/10098>).
+
+       -h, --help
+           Prints help information.
+
+       -Z flag
+           Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
+           details.
+
+ENVIRONMENT
+       See the reference
+       <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
+       for details on environment variables that Cargo reads.
+
+EXIT STATUS
+       o  0: Cargo succeeded.
+
+       o  101: Cargo failed to complete.
+
 EXAMPLES
        1. Get help for a command:
 

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

@@ -152,9 +152,9 @@ EXAMPLES
 
               cargo remove --dev trybuild
 
-       3. Remove nom from the x86_64-pc-windows-gnu dependencies table
+       3. Remove nom from the wasm32-unknown-unknown dependencies table
 
-              cargo remove --target x86_64-pc-windows-gnu nom
+              cargo remove --target wasm32-unknown-unknown nom
 
 SEE ALSO
        cargo(1), cargo-add(1)

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

@@ -12,6 +12,133 @@ cargo-help --- Get help for a Cargo command
 
 Prints a help message for the given command.
 
+## OPTIONS
+
+### Display Options
+
+<dl>
+<dt class="option-term" id="option-cargo-help--v"><a class="option-anchor" href="#option-cargo-help--v"><code>-v</code></a></dt>
+<dt class="option-term" id="option-cargo-help---verbose"><a class="option-anchor" href="#option-cargo-help---verbose"><code>--verbose</code></a></dt>
+<dd class="option-desc"><p>Use verbose output. May be specified twice for “very verbose” output which
+includes extra output such as dependency warnings and build script output.
+May also be specified with the <code>term.verbose</code>
+<a href="../reference/config.html">config value</a>.</p>
+</dd>
+
+
+<dt class="option-term" id="option-cargo-help--q"><a class="option-anchor" href="#option-cargo-help--q"><code>-q</code></a></dt>
+<dt class="option-term" id="option-cargo-help---quiet"><a class="option-anchor" href="#option-cargo-help---quiet"><code>--quiet</code></a></dt>
+<dd class="option-desc"><p>Do not print cargo log messages.
+May also be specified with the <code>term.quiet</code>
+<a href="../reference/config.html">config value</a>.</p>
+</dd>
+
+
+<dt class="option-term" id="option-cargo-help---color"><a class="option-anchor" href="#option-cargo-help---color"><code>--color</code> <em>when</em></a></dt>
+<dd class="option-desc"><p>Control when colored output is used. Valid values:</p>
+<ul>
+<li><code>auto</code> (default): Automatically detect if color support is available on the
+terminal.</li>
+<li><code>always</code>: Always display colors.</li>
+<li><code>never</code>: Never display colors.</li>
+</ul>
+<p>May also be specified with the <code>term.color</code>
+<a href="../reference/config.html">config value</a>.</p>
+</dd>
+
+</dl>
+
+### Manifest Options
+
+<dl>
+<dt class="option-term" id="option-cargo-help---locked"><a class="option-anchor" href="#option-cargo-help---locked"><code>--locked</code></a></dt>
+<dd class="option-desc"><p>Asserts that the exact same dependencies and versions are used as when the
+existing <code>Cargo.lock</code> file was originally generated. Cargo will exit with an
+error when either of the following scenarios arises:</p>
+<ul>
+<li>The lock file is missing.</li>
+<li>Cargo attempted to change the lock file due to a different dependency resolution.</li>
+</ul>
+<p>It may be used in environments where deterministic builds are desired,
+such as in CI pipelines.</p>
+</dd>
+
+
+<dt class="option-term" id="option-cargo-help---offline"><a class="option-anchor" href="#option-cargo-help---offline"><code>--offline</code></a></dt>
+<dd class="option-desc"><p>Prevents Cargo from accessing the network for any reason. Without this
+flag, Cargo will stop with an error if it needs to access the network and
+the network is not available. With this flag, Cargo will attempt to
+proceed without the network if possible.</p>
+<p>Beware that this may result in different dependency resolution than online
+mode. Cargo will restrict itself to crates that are downloaded locally, even
+if there might be a newer version as indicated in the local copy of the index.
+See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going
+offline.</p>
+<p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</p>
+</dd>
+
+
+<dt class="option-term" id="option-cargo-help---frozen"><a class="option-anchor" href="#option-cargo-help---frozen"><code>--frozen</code></a></dt>
+<dd class="option-desc"><p>Equivalent to specifying both <code>--locked</code> and <code>--offline</code>.</p>
+</dd>
+
+</dl>
+
+### Common Options
+
+<dl>
+
+<dt class="option-term" id="option-cargo-help-+toolchain"><a class="option-anchor" href="#option-cargo-help-+toolchain"><code>+</code><em>toolchain</em></a></dt>
+<dd class="option-desc"><p>If Cargo has been installed with rustup, and the first argument to <code>cargo</code>
+begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such
+as <code>+stable</code> or <code>+nightly</code>).
+See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a>
+for more information about how toolchain overrides work.</p>
+</dd>
+
+
+<dt class="option-term" id="option-cargo-help---config"><a class="option-anchor" href="#option-cargo-help---config"><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></a></dt>
+<dd class="option-desc"><p>Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>,
+or provided as a path to an extra configuration file. This flag may be specified multiple times.
+See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</p>
+</dd>
+
+
+<dt class="option-term" id="option-cargo-help--C"><a class="option-anchor" href="#option-cargo-help--C"><code>-C</code> <em>PATH</em></a></dt>
+<dd class="option-desc"><p>Changes the current working directory before executing any specified operations. This affects
+things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as
+the directories searched for discovering <code>.cargo/config.toml</code>, for example. This option must
+appear before the command name, for example <code>cargo -C path/to/my-project build</code>.</p>
+<p>This option is only available 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/10098">#10098</a>).</p>
+</dd>
+
+
+<dt class="option-term" id="option-cargo-help--h"><a class="option-anchor" href="#option-cargo-help--h"><code>-h</code></a></dt>
+<dt class="option-term" id="option-cargo-help---help"><a class="option-anchor" href="#option-cargo-help---help"><code>--help</code></a></dt>
+<dd class="option-desc"><p>Prints help information.</p>
+</dd>
+
+
+<dt class="option-term" id="option-cargo-help--Z"><a class="option-anchor" href="#option-cargo-help--Z"><code>-Z</code> <em>flag</em></a></dt>
+<dd class="option-desc"><p>Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</p>
+</dd>
+
+
+</dl>
+
+## ENVIRONMENT
+
+See [the reference](../reference/environment-variables.html) for
+details on environment variables that Cargo reads.
+
+## EXIT STATUS
+
+* `0`: Cargo succeeded.
+* `101`: Cargo failed to complete.
+
 ## EXAMPLES
 
 1. Get help for a command:

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

@@ -200,9 +200,9 @@ details on environment variables that Cargo reads.
 
        cargo remove --dev trybuild
 
-3. Remove `nom` from the `x86_64-pc-windows-gnu` dependencies table
+3. Remove `nom` from the `wasm32-unknown-unknown` dependencies table
 
-       cargo remove --target x86_64-pc-windows-gnu nom
+       cargo remove --target wasm32-unknown-unknown nom
 
 ## SEE ALSO
 [cargo(1)](cargo.html), [cargo-add(1)](cargo-add.html)