Do not use pager for root uv help and improve after help hint (#4936)

Adds a nice hint at the bottom of `uv help` output indicating how to get
more details about a specific command, roughly matching Cargo's
interface.

We use the short help and skip the pager for the root `uv help` since
it's intended to be a landing page for the help interface more than an
in-depth display. This also matches Cargo, though I like that they have
the global options above the commands and I've not changed that here.

crates/uv/src/commands/help.rs

@@ -4,6 +4,7 @@ use anstream::{stream::IsTerminal, ColorChoice};
 use anyhow::{anyhow, Result};
 use clap::CommandFactory;
 use itertools::{Either, Itertools};
+use owo_colors::OwoColorize;
 use which::which;
 
 use super::ExitStatus;
@@ -35,8 +36,28 @@ pub(crate) fn help(query: &[String], printer: Printer) -> Result<ExitStatus> {
         )
     })?;
 
+    let name = command.get_name();
+    let is_root = name == uv.get_name();
     let mut command = command.clone();
-    let help = command.render_long_help();
+
+    let help = if is_root {
+        command
+            .after_help(format!(
+                "Use `{}` for more information on a specific command.",
+                "uv help <command>".bold()
+            ))
+            .render_help()
+    } else {
+        if command.has_subcommands() {
+            command.after_long_help(format!(
+                "Use `{}` for more information on a specific command.",
+                format!("uv help {name} <command>").bold()
+            ))
+        } else {
+            command
+        }
+        .render_long_help()
+    };
 
     let help_ansi = match anstream::Stdout::choice(&std::io::stdout()) {
         ColorChoice::Always | ColorChoice::AlwaysAnsi => Either::Left(help.ansi()),
@@ -46,11 +67,11 @@ pub(crate) fn help(query: &[String], printer: Printer) -> Result<ExitStatus> {
     };
 
     let is_terminal = std::io::stdout().is_terminal();
-    if is_terminal && which("less").is_ok() {
+    if !is_root && is_terminal && which("less").is_ok() {
         // When using less, we use the command name as the file name and can support colors
         let prompt = format!("help: uv {}", query.join(" "));
         spawn_pager("less", &["-R", "-P", &prompt], &help_ansi)?;
-    } else if is_terminal && which("more").is_ok() {
+    } else if !is_root && is_terminal && which("more").is_ok() {
         // When using more, we skip the ANSI color codes
         spawn_pager("more", &[], &help)?;
     } else {

crates/uv/tests/help.rs

@@ -27,86 +27,34 @@ fn help() {
     Options:
       -q, --quiet
               Do not print any output
-
       -v, --verbose...
-              Use verbose output.
+              Use verbose output
-              
-              You can configure fine-grained logging using the `RUST_LOG` environment variable.
-              (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)
-
           --color <COLOR_CHOICE>
-              Control colors in output
+              Control colors in output [default: auto] [possible values: auto, always, never]
-              
-              [default: auto]
-
-              Possible values:
-              - auto:   Enables colored output only when the output is going to a terminal or TTY with
-                support
-              - always: Enables colored output regardless of the detected environment
-              - never:  Disables colored output
-
           --native-tls
-              Whether to load TLS certificates from the platform's native certificate store.
+              Whether to load TLS certificates from the platform's native certificate store [env:
-              
+              UV_NATIVE_TLS=]
-              By default, `uv` loads certificates from the bundled `webpki-roots` crate. The
-              `webpki-roots` are a reliable set of trust roots from Mozilla, and including them in `uv`
-              improves portability and performance (especially on macOS).
-              
-              However, in some cases, you may want to use the platform's native certificate store,
-              especially if you're relying on a corporate trust root (e.g., for a mandatory proxy)
-              that's included in your system's certificate store.
-              
-              [env: UV_NATIVE_TLS=]
-
           --offline
               Disable network access, relying only on locally cached data and locally available files
-
           --python-preference <PYTHON_PREFERENCE>
-              Whether to prefer using Python from uv or on the system
+              Whether to prefer using Python from uv or on the system [possible values: only-managed,
-
+              installed, managed, system, only-system]
-              Possible values:
-              - only-managed: Only use managed Python installations; never use system Python
-                installations
-              - installed:    Prefer installed Python installations, only download managed Python
-                installations if no system Python installation is found
-              - managed:      Prefer managed Python installations over system Python installations, even
-                if fetching is required
-              - system:       Prefer system Python installations over managed Python installations
-              - only-system:  Only use system Python installations; never use managed Python
-                installations
-
           --python-fetch <PYTHON_FETCH>
-              Whether to automatically download Python when required
+              Whether to automatically download Python when required [possible values: automatic,
-
+              manual]
-              Possible values:
-              - automatic: Automatically fetch managed Python installations when needed
-              - manual:    Do not automatically fetch managed Python installations; require explicit
-                installation
-
       -n, --no-cache
-              Avoid reading from or writing to the cache
+              Avoid reading from or writing to the cache [env: UV_NO_CACHE=]
-              
-              [env: UV_NO_CACHE=]
-
           --cache-dir [CACHE_DIR]
-              Path to the cache directory.
+              Path to the cache directory [env: UV_CACHE_DIR=]
-              
-              Defaults to `$HOME/Library/Caches/uv` on macOS, `$XDG_CACHE_HOME/uv` or `$HOME/.cache/uv`
-              on Linux, and `{FOLDERID_LocalAppData}/uv/cache` on Windows.
-              
-              [env: UV_CACHE_DIR=]
-
           --config-file <CONFIG_FILE>
-              The path to a `uv.toml` file to use for configuration
+              The path to a `uv.toml` file to use for configuration [env: UV_CONFIG_FILE=]
-              
-              [env: UV_CONFIG_FILE=]
-
       -h, --help
               Print help
-
       -V, --version
               Print version
 
+    Use `uv help <command>` for more information on a specific command.
+
 
     ----- stderr -----
     "###);
@@ -324,6 +272,8 @@ fn help_subcommand() {
       -V, --version
               Print version
 
+    Use `uv help python <command>` for more information on a specific command.
+
 
     ----- stderr -----
     "###);
@@ -622,86 +572,34 @@ fn help_with_global_option() {
     Options:
       -q, --quiet
               Do not print any output
-
       -v, --verbose...
-              Use verbose output.
+              Use verbose output
-              
-              You can configure fine-grained logging using the `RUST_LOG` environment variable.
-              (<https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives>)
-
           --color <COLOR_CHOICE>
-              Control colors in output
+              Control colors in output [default: auto] [possible values: auto, always, never]
-              
-              [default: auto]
-
-              Possible values:
-              - auto:   Enables colored output only when the output is going to a terminal or TTY with
-                support
-              - always: Enables colored output regardless of the detected environment
-              - never:  Disables colored output
-
           --native-tls
-              Whether to load TLS certificates from the platform's native certificate store.
+              Whether to load TLS certificates from the platform's native certificate store [env:
-              
+              UV_NATIVE_TLS=]
-              By default, `uv` loads certificates from the bundled `webpki-roots` crate. The
-              `webpki-roots` are a reliable set of trust roots from Mozilla, and including them in `uv`
-              improves portability and performance (especially on macOS).
-              
-              However, in some cases, you may want to use the platform's native certificate store,
-              especially if you're relying on a corporate trust root (e.g., for a mandatory proxy)
-              that's included in your system's certificate store.
-              
-              [env: UV_NATIVE_TLS=]
-
           --offline
               Disable network access, relying only on locally cached data and locally available files
-
           --python-preference <PYTHON_PREFERENCE>
-              Whether to prefer using Python from uv or on the system
+              Whether to prefer using Python from uv or on the system [possible values: only-managed,
-
+              installed, managed, system, only-system]
-              Possible values:
-              - only-managed: Only use managed Python installations; never use system Python
-                installations
-              - installed:    Prefer installed Python installations, only download managed Python
-                installations if no system Python installation is found
-              - managed:      Prefer managed Python installations over system Python installations, even
-                if fetching is required
-              - system:       Prefer system Python installations over managed Python installations
-              - only-system:  Only use system Python installations; never use managed Python
-                installations
-
           --python-fetch <PYTHON_FETCH>
-              Whether to automatically download Python when required
+              Whether to automatically download Python when required [possible values: automatic,
-
+              manual]
-              Possible values:
-              - automatic: Automatically fetch managed Python installations when needed
-              - manual:    Do not automatically fetch managed Python installations; require explicit
-                installation
-
       -n, --no-cache
-              Avoid reading from or writing to the cache
+              Avoid reading from or writing to the cache [env: UV_NO_CACHE=]
-              
-              [env: UV_NO_CACHE=]
-
           --cache-dir [CACHE_DIR]
-              Path to the cache directory.
+              Path to the cache directory [env: UV_CACHE_DIR=]
-              
-              Defaults to `$HOME/Library/Caches/uv` on macOS, `$XDG_CACHE_HOME/uv` or `$HOME/.cache/uv`
-              on Linux, and `{FOLDERID_LocalAppData}/uv/cache` on Windows.
-              
-              [env: UV_CACHE_DIR=]
-
           --config-file <CONFIG_FILE>
-              The path to a `uv.toml` file to use for configuration
+              The path to a `uv.toml` file to use for configuration [env: UV_CONFIG_FILE=]
-              
-              [env: UV_CONFIG_FILE=]
-
       -h, --help
               Print help
-
       -V, --version
               Print version
 
+    Use `uv help <command>` for more information on a specific command.
+
 
     ----- stderr -----
     "###);