From 0091adfa5b098e037bd22fa0a141183ac866b03d Mon Sep 17 00:00:00 2001
From: Zanie Blue <contact@zanie.dev>
Date: Fri, 16 Aug 2024 18:16:42 -0500
Subject: [PATCH] Document `uv add` and `uv remove` behavior with markers
 (#6163)

---
 crates/uv-cli/src/lib.rs | 31 ++++++++++++++++++-------------
 docs/reference/cli.md    |  4 ++++
 2 files changed, 22 insertions(+), 13 deletions(-)

diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs
index 7856a14c7..c83ed54f4 100644
--- a/crates/uv-cli/src/lib.rs
+++ b/crates/uv-cli/src/lib.rs
@@ -548,22 +548,24 @@ pub enum ProjectCommand {
     ///
     /// Dependencies are added to the project's `pyproject.toml` file.
     ///
-    /// If no constraint or URL is provided for a dependency, a lower bound is
-    /// added equal to the latest compatible version of the package, e.g.,
-    /// `>=1.2.3`, unless `--frozen` is provided, in which case no resolution is
-    /// performed.
+    /// If a given dependency exists already, it will be updated to the new version specifier unless
+    /// it includes markers that differ from the existing specifier in which case another entry for
+    /// the depenedency will be added.
     ///
-    /// The lockfile and project environment will be updated to reflect the
-    /// added dependencies. To skip updating the lockfile, use `--frozen`. To
-    /// skip updating the environment, use `--no-sync`.
+    /// If no constraint or URL is provided for a dependency, a lower bound is added equal to the
+    /// latest compatible version of the package, e.g., `>=1.2.3`, unless `--frozen` is provided, in
+    /// which case no resolution is performed.
     ///
-    /// If any of the requested dependencies cannot be found, uv will exit with
-    /// an error, unless the `--frozen` flag is provided, in which case uv will
-    /// add the dependencies verbatim without checking that they exist or are
-    /// compatible with the project.
+    /// The lockfile and project environment will be updated to reflect the added dependencies. To
+    /// skip updating the lockfile, use `--frozen`. To skip updating the environment, use
+    /// `--no-sync`.
     ///
-    /// uv will search for a project in the current directory or any parent
-    /// directory. If a project cannot be found, uv will exit with an error.
+    /// If any of the requested dependencies cannot be found, uv will exit with an error, unless the
+    /// `--frozen` flag is provided, in which case uv will add the dependencies verbatim without
+    /// checking that they exist or are compatible with the project.
+    ///
+    /// uv will search for a project in the current directory or any parent directory. If a project
+    /// cannot be found, uv will exit with an error.
     #[command(
         after_help = "Use `uv help add` for more details.",
         after_long_help = ""
@@ -573,6 +575,9 @@ pub enum ProjectCommand {
     ///
     /// Dependencies are removed from the project's `pyproject.toml` file.
     ///
+    /// If multiple entries exist for a given dependency, i.e., each with different markers, all of
+    /// the entries will be removed.
+    ///
     /// The lockfile and project environment will be updated to reflect the
     /// removed dependencies. To skip updating the lockfile, use `--frozen`. To
     /// skip updating the environment, use `--no-sync`.
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 75133695b..a45465bfb 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -455,6 +455,8 @@ Add dependencies to the project (experimental).
 
 Dependencies are added to the project's `pyproject.toml` file.
 
+If a given dependency exists already, it will be updated to the new version specifier unless it includes markers that differ from the existing specifier in which case another entry for the depenedency will be added.
+
 If no constraint or URL is provided for a dependency, a lower bound is added equal to the latest compatible version of the package, e.g., `>=1.2.3`, unless `--frozen` is provided, in which case no resolution is performed.
 
 The lockfile and project environment will be updated to reflect the added dependencies. To skip updating the lockfile, use `--frozen`. To skip updating the environment, use `--no-sync`.
@@ -739,6 +741,8 @@ Remove dependencies from the project (experimental).
 
 Dependencies are removed from the project's `pyproject.toml` file.
 
+If multiple entries exist for a given dependency, i.e., each with different markers, all of the entries will be removed.
+
 The lockfile and project environment will be updated to reflect the removed dependencies. To skip updating the lockfile, use `--frozen`. To skip updating the environment, use `--no-sync`.
 
 If any of the requested dependencies are not present in the project, uv will exit with an error.