Tweak display; add docs

crates/uv-cli/src/lib.rs

@@ -3164,12 +3164,15 @@ pub struct ToolListArgs {
     /// Whether to display the path to each tool environment and installed executable.
     #[arg(long)]
     pub show_paths: bool,
+
+    /// Whether to display the version specifier(s) used to install each tool.
     #[arg(long)]
     pub show_version_specifiers: bool,
 
     // Hide unused global Python options.
     #[arg(long, hide = true)]
     pub python_preference: Option<PythonPreference>,
+
     #[arg(long, hide = true)]
     pub no_python_downloads: bool,
 }

crates/uv/src/commands/tool/list.rs

@@ -1,6 +1,7 @@
 use std::fmt::Write;
 
 use anyhow::Result;
+use itertools::Itertools;
 use owo_colors::OwoColorize;
 
 use uv_cache::Cache;
@@ -55,16 +56,18 @@ pub(crate) async fn list(
             }
         };
 
-        let mut version_specifier = String::new();
-        if show_version_specifiers {
-            if let Some(source) = tool.requirements().iter().find_map(|req| {
-                (req.name == name)
-                    .then_some(req.source.to_string())
-                    .filter(|s| !s.is_empty())
-            }) {
-                version_specifier.push_str(&format!(r#" (specifier: "{source}")"#));
-            }
-        }
+        let version_specifier = if show_version_specifiers {
+            let specifiers = tool
+                .requirements()
+                .iter()
+                .filter(|req| req.name == name)
+                .map(|req| req.source.to_string())
+                .filter(|s| !s.is_empty())
+                .join(", ");
+            format!(" [required: {}]", specifiers)
+        } else {
+            String::new()
+        };
 
         if show_paths {
             writeln!(

crates/uv/src/settings.rs

@@ -467,7 +467,8 @@ impl ToolListSettings {
         let ToolListArgs {
             show_paths,
             show_version_specifiers,
-            ..
+            python_preference: _,
+            no_python_downloads: _,
         } = args;
 
         Self {

crates/uv/tests/tool_list.rs

@@ -274,7 +274,7 @@ fn tool_list_show_version_specifiers() {
     success: true
     exit_code: 0
     ----- stdout -----
-    black v24.2.0 (specifier: "<24.3.0")
+    black v24.2.0 [required: <24.3.0]
     - black
     - blackd
 

docs/reference/cli.md

@@ -3141,7 +3141,9 @@ uv tool list [OPTIONS]
 
 </dd><dt><code>--show-paths</code></dt><dd><p>Whether to display the path to each tool environment and installed executable</p>
 
-</dd><dt><code>--show-version-specifiers</code></dt><dt><code>--verbose</code>, <code>-v</code></dt><dd><p>Use verbose output.</p>
+</dd><dt><code>--show-version-specifiers</code></dt><dd><p>Whether to display the version specifier(s) used to install each tool</p>
+
+</dd><dt><code>--verbose</code>, <code>-v</code></dt><dd><p>Use verbose output.</p>
 
 <p>You can configure fine-grained logging using the <code>RUST_LOG</code> environment variable. (&lt;https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives&gt;)</p>