Ensure symlink warning is shown (#15126)

Fixes #15115, see also clap-rs/clap#6092

<img width="1079" height="1030" alt="image"
src="https://github.com/user-attachments/assets/05b003a6-9ca0-4f2b-8a74-078aa155ce6d"
/>

Author: konstin

crates/uv-cli/src/lib.rs

@@ -2769,6 +2769,11 @@ pub struct VenvArgs {
     ///
     /// Defaults to `clone` (also known as Copy-on-Write) on macOS, and `hardlink` on Linux and
     /// Windows.
+    ///
+    /// WARNING: The use of symlink link mode is discouraged, as they create tight coupling between
+    /// the cache and the target environment. For example, clearing the cache (`uv cache clear`)
+    /// will break all installed packages by way of removing the underlying source files. Use
+    /// symlinks with caution.
     #[arg(long, value_enum, env = EnvVars::UV_LINK_MODE)]
     pub link_mode: Option<uv_install_wheel::LinkMode>,
 
@@ -4808,6 +4813,11 @@ pub struct ToolUpgradeArgs {
     ///
     /// Defaults to `clone` (also known as Copy-on-Write) on macOS, and `hardlink` on Linux and
     /// Windows.
+    ///
+    /// WARNING: The use of symlink link mode is discouraged, as they create tight coupling between
+    /// the cache and the target environment. For example, clearing the cache (`uv cache clear`)
+    /// will break all installed packages by way of removing the underlying source files. Use
+    /// symlinks with caution.
     #[arg(
         long,
         value_enum,
@@ -5612,6 +5622,11 @@ pub struct InstallerArgs {
     ///
     /// Defaults to `clone` (also known as Copy-on-Write) on macOS, and `hardlink` on Linux and
     /// Windows.
+    ///
+    /// WARNING: The use of symlink link mode is discouraged, as they create tight coupling between
+    /// the cache and the target environment. For example, clearing the cache (`uv cache clear`)
+    /// will break all installed packages by way of removing the underlying source files. Use
+    /// symlinks with caution.
     #[arg(
         long,
         value_enum,
@@ -5824,6 +5839,11 @@ pub struct ResolverArgs {
     ///
     /// Defaults to `clone` (also known as Copy-on-Write) on macOS, and `hardlink` on Linux and
     /// Windows.
+    ///
+    /// WARNING: The use of symlink link mode is discouraged, as they create tight coupling between
+    /// the cache and the target environment. For example, clearing the cache (`uv cache clear`)
+    /// will break all installed packages by way of removing the underlying source files. Use
+    /// symlinks with caution.
     #[arg(
         long,
         value_enum,
@@ -6028,6 +6048,11 @@ pub struct ResolverInstallerArgs {
     ///
     /// Defaults to `clone` (also known as Copy-on-Write) on macOS, and `hardlink` on Linux and
     /// Windows.
+    ///
+    /// WARNING: The use of symlink link mode is discouraged, as they create tight coupling between
+    /// the cache and the target environment. For example, clearing the cache (`uv cache clear`)
+    /// will break all installed packages by way of removing the underlying source files. Use
+    /// symlinks with caution.
     #[arg(
         long,
         value_enum,

crates/uv-install-wheel/src/linker.rs

@@ -27,11 +27,6 @@ pub enum LinkMode {
     /// Hard link packages from the wheel into the `site-packages` directory.
     Hardlink,
     /// Symbolically link packages from the wheel into the `site-packages` directory.
-    ///
-    /// WARNING: The use of symlinks is discouraged, as they create tight coupling between the
-    /// cache and the target environment. For example, clearing the cache (`uv cache clear`) will
-    /// break all installed packages by way of removing the underlying source files. Use symlinks
-    /// with caution.
     Symlink,
 }
 

crates/uv-settings/src/settings.rs

@@ -639,7 +639,7 @@ pub struct ResolverInstallerOptions {
         default = "[]",
         value_type = "dict",
         example = r#"
-        [extra-build-dependencies] 
+        [extra-build-dependencies]
         pytest = ["setuptools"]
     "#
     )]
@@ -685,6 +685,11 @@ pub struct ResolverInstallerOptions {
     ///
     /// Defaults to `clone` (also known as Copy-on-Write) on macOS, and `hardlink` on Linux and
     /// Windows.
+    ///
+    /// WARNING: The use of symlink link mode is discouraged, as they create tight coupling between
+    /// the cache and the target environment. For example, clearing the cache (`uv cache clear`)
+    /// will break all installed packages by way of removing the underlying source files. Use
+    /// symlinks with caution.
     #[option(
         default = "\"clone\" (macOS) or \"hardlink\" (Linux, Windows)",
         value_type = "str",
@@ -1568,6 +1573,11 @@ pub struct PipOptions {
     ///
     /// Defaults to `clone` (also known as Copy-on-Write) on macOS, and `hardlink` on Linux and
     /// Windows.
+    ///
+    /// WARNING: The use of symlink link mode is discouraged, as they create tight coupling between
+    /// the cache and the target environment. For example, clearing the cache (`uv cache clear`)
+    /// will break all installed packages by way of removing the underlying source files. Use
+    /// symlinks with caution.
     #[option(
         default = "\"clone\" (macOS) or \"hardlink\" (Linux, Windows)",
         value_type = "str",