From a8af23b027bdff1e341d6c6dd1812962eaa3cd56 Mon Sep 17 00:00:00 2001
From: Charlie Marsh <charlie.r.marsh@gmail.com>
Date: Wed, 4 Sep 2024 19:28:44 -0400
Subject: [PATCH] Tweak display; add docs

---
 crates/uv-cli/src/lib.rs            |  3 +++
 crates/uv/src/commands/tool/list.rs | 23 +++++++++++++----------
 crates/uv/src/settings.rs           |  3 ++-
 crates/uv/tests/tool_list.rs        |  2 +-
 docs/reference/cli.md               |  4 +++-
 5 files changed, 22 insertions(+), 13 deletions(-)

diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs
index 7ca8f244d11b3..316f31dc39eff 100644
--- a/crates/uv-cli/src/lib.rs
+++ b/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,
 }
diff --git a/crates/uv/src/commands/tool/list.rs b/crates/uv/src/commands/tool/list.rs
index 0bea982559e6c..8cc279ef0f86d 100644
--- a/crates/uv/src/commands/tool/list.rs
+++ b/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!(
diff --git a/crates/uv/src/settings.rs b/crates/uv/src/settings.rs
index 22331e79359d3..50c2470ad23d4 100644
--- a/crates/uv/src/settings.rs
+++ b/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 {
diff --git a/crates/uv/tests/tool_list.rs b/crates/uv/tests/tool_list.rs
index 6133b8d0a7e6f..476a5490a3567 100644
--- a/crates/uv/tests/tool_list.rs
+++ b/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
 
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index efcf411e9f165..21861d59fc837 100644
--- a/docs/reference/cli.md
+++ b/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>