Display short help menu when --help is used (#4772)

I feel like I'm always drowning in the help output from `uv` because we
have so many options.

I basically agree with the commentary in
https://github.com/clap-rs/clap/issues/4687 that having different
behaviors for `-h` and `--help` is surprising. I think `--help` is more
obvious for users and I want to optimize for that experience.

This roughly matches the help menus in Cargo and pip.

The `uv help` command can be used for long help. In #4906 and #4909 we
improve that command.

Extends #4904 which adds test cases for the existing behavior.

crates/uv-cli/src/lib.rs

@@ -52,6 +52,7 @@ fn extra_name_with_clap_error(arg: &str) -> Result<ExtraName> {
 #[command(name = "uv", author, version = uv_version::version(), long_version = crate::version::version())]
 #[command(about = "An extremely fast Python package manager.")]
 #[command(propagate_version = true)]
+#[command(disable_help_flag = true)]
 #[allow(clippy::struct_excessive_bools)]
 pub struct Cli {
     #[command(subcommand)]
@@ -66,6 +67,10 @@ pub struct Cli {
     /// The path to a `uv.toml` file to use for configuration.
     #[arg(global = true, long, env = "UV_CONFIG_FILE")]
     pub config_file: Option<PathBuf>,
+
+    /// Print help.
+    #[arg(global = true, short, long, action = clap::ArgAction::HelpShort)]
+    help: Option<bool>,
 }
 
 #[derive(Parser, Debug, Clone)]

crates/uv/tests/help.rs

@@ -102,7 +102,7 @@ fn help() {
               [env: UV_CONFIG_FILE=]
 
       -h, --help
-              Print help (see a summary with '-h')
+              Print help
 
       -V, --version
               Print version
@@ -134,83 +134,29 @@ fn help_flag() {
     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 (see a summary with '-h')
+              Print help
-
       -V, --version
               Print version
 
@@ -263,7 +209,7 @@ fn help_short_flag() {
           --config-file <CONFIG_FILE>
               The path to a `uv.toml` file to use for configuration [env: UV_CONFIG_FILE=]
       -h, --help
-              Print help (see more with '--help')
+              Print help
       -V, --version
               Print version
 
@@ -369,7 +315,7 @@ fn help_subcommand() {
               [env: UV_CONFIG_FILE=]
 
       -h, --help
-              Print help (see a summary with '-h')
+              Print help
 
       -V, --version
               Print version
@@ -479,7 +425,7 @@ fn help_subsubcommand() {
               [env: UV_CONFIG_FILE=]
 
       -h, --help
-              Print help (see a summary with '-h')
+              Print help
 
       -V, --version
               Print version
@@ -511,83 +457,29 @@ fn help_flag_subcommand() {
     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 (see a summary with '-h')
+              Print help
-
       -V, --version
               Print version
 
@@ -608,96 +500,36 @@ fn help_flag_subsubcommand() {
     Usage: uv python install [OPTIONS] [TARGETS]...
 
     Arguments:
-      [TARGETS]...
+      [TARGETS]...  The Python version(s) to install
-              The Python version(s) to install.
-              
-              If not provided, the requested Python version(s) will be read from the `.python-versions`
-              or `.python-version` files. If neither file is present, uv will check if it has installed
-              any Python versions. If not, it will install the latest stable version of Python.
 
     Options:
       -f, --force
               Force the installation of the requested Python, even if it is already installed
-
       -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 (see a summary with '-h')
+              Print help
-
       -V, --version
               Print version