feat: support --lfs in uv add

samypr100 · samypr100 · commit b34deecfc119 · 2025-10-13T15:01:28.000-04:00
diff --git a/crates/uv-cli/src/lib.rs b/crates/uv-cli/src/lib.rs
@@ -3882,6 +3882,10 @@ pub struct AddArgs {
     #[arg(long, group = "git-ref", action = clap::ArgAction::Set)]
     pub branch: Option<String>,
 
+    /// Whether to use Git LFS when adding a dependency from Git.
+    #[arg(long, env = EnvVars::UV_GIT_LFS, value_parser = clap::builder::BoolishValueParser::new())]
+    pub lfs: bool,
+
     /// Extras to enable for the dependency.
     ///
     /// May be provided more than once.
diff --git a/crates/uv-workspace/src/pyproject.rs b/crates/uv-workspace/src/pyproject.rs
@@ -1549,6 +1549,10 @@ pub enum SourceError {
         "`{0}` did not resolve to a Git repository, but a Git reference (`--branch {1}`) was provided."
     )]
     UnusedBranch(String, String),
+    #[error(
+        "`{0}` did not resolve to a Git repository, but a Git extension (`--lfs`) was provided."
+    )]
+    UnusedLfs(String),
     #[error(
         "`{0}` did not resolve to a local directory, but the `--editable` flag was provided. Editable installs are only supported for local directories."
     )]
@@ -1578,12 +1582,13 @@ impl Source {
         rev: Option<String>,
         tag: Option<String>,
         branch: Option<String>,
+        lfs: Option<bool>,
         root: &Path,
         existing_sources: Option<&BTreeMap<PackageName, Sources>>,
     ) -> Result<Option<Self>, SourceError> {
         // If the user specified a Git reference for a non-Git source, try existing Git sources before erroring.
         if !matches!(source, RequirementSource::Git { .. })
-            && (branch.is_some() || tag.is_some() || rev.is_some())
+            && (branch.is_some() || tag.is_some() || rev.is_some() || lfs.is_some())
         {
             if let Some(sources) = existing_sources {
                 if let Some(package_sources) = sources.get(name) {
@@ -1603,7 +1608,7 @@ impl Source {
                                 rev,
                                 tag,
                                 branch,
-                                lfs: None,
+                                lfs,
                                 marker: *marker,
                                 extra: extra.clone(),
                                 group: group.clone(),
@@ -1621,6 +1626,9 @@ impl Source {
             if let Some(branch) = branch {
                 return Err(SourceError::UnusedBranch(name.to_string(), branch));
             }
+            if let Some(true) = lfs {
+                return Err(SourceError::UnusedLfs(name.to_string()));
+            }
         }
 
         // If we resolved a non-path source, and user specified an `--editable` flag, error.
@@ -1713,7 +1721,7 @@ impl Source {
                         rev: rev.cloned(),
                         tag,
                         branch,
-                        lfs: None,
+                        lfs,
                         git: git.repository().clone(),
                         subdirectory: subdirectory.map(PortablePathBuf::from),
                         marker: MarkerTree::TRUE,
@@ -1725,7 +1733,7 @@ impl Source {
                         rev,
                         tag,
                         branch,
-                        lfs: None,
+                        lfs,
                         git: git.repository().clone(),
                         subdirectory: subdirectory.map(PortablePathBuf::from),
                         marker: MarkerTree::TRUE,
diff --git a/crates/uv/src/commands/project/add.rs b/crates/uv/src/commands/project/add.rs
@@ -83,6 +83,7 @@ pub(crate) async fn add(
     rev: Option<String>,
     tag: Option<String>,
     branch: Option<String>,
+    lfs: Option<bool>,
     extras_of_dependency: Vec<ExtraName>,
     package: Option<PackageName>,
     python: Option<String>,
@@ -373,6 +374,7 @@ pub(crate) async fn add(
                     rev.as_deref(),
                     tag.as_deref(),
                     branch.as_deref(),
+                    lfs,
                     marker,
                 )
             })
@@ -640,6 +642,7 @@ pub(crate) async fn add(
         rev.as_deref(),
         tag.as_deref(),
         branch.as_deref(),
+        lfs,
         &extras_of_dependency,
         index,
         &mut toml,
@@ -771,6 +774,7 @@ fn edits(
     rev: Option<&str>,
     tag: Option<&str>,
     branch: Option<&str>,
+    lfs: Option<bool>,
     extras: &[ExtraName],
     index: Option<&IndexName>,
     toml: &mut PyProjectTomlMut,
@@ -801,6 +805,7 @@ fn edits(
                     rev.map(ToString::to_string),
                     tag.map(ToString::to_string),
                     branch.map(ToString::to_string),
+                    lfs,
                     script_dir,
                     existing_sources,
                 )?
@@ -825,6 +830,7 @@ fn edits(
                     rev.map(ToString::to_string),
                     tag.map(ToString::to_string),
                     branch.map(ToString::to_string),
+                    lfs,
                     project.root(),
                     existing_sources,
                 )?
@@ -1183,6 +1189,7 @@ fn augment_requirement(
     rev: Option<&str>,
     tag: Option<&str>,
     branch: Option<&str>,
+    lfs: Option<bool>,
     marker: Option<MarkerTree>,
 ) -> UnresolvedRequirement {
     match requirement {
@@ -1209,6 +1216,11 @@ fn augment_requirement(
                         } else {
                             git
                         };
+                        let git = if let Some(lfs) = lfs {
+                            git.with_lfs(lfs.into())
+                        } else {
+                            git
+                        };
                         RequirementSource::Git {
                             git,
                             subdirectory,
@@ -1262,6 +1274,7 @@ fn resolve_requirement(
     rev: Option<String>,
     tag: Option<String>,
     branch: Option<String>,
+    lfs: Option<bool>,
     root: &Path,
     existing_sources: Option<&BTreeMap<PackageName, Sources>>,
 ) -> Result<(uv_pep508::Requirement, Option<Source>), anyhow::Error> {
@@ -1274,6 +1287,7 @@ fn resolve_requirement(
         rev,
         tag,
         branch,
+        lfs,
         root,
         existing_sources,
     );
diff --git a/crates/uv/src/lib.rs b/crates/uv/src/lib.rs
@@ -2074,6 +2074,7 @@ async fn run_project(
                 args.rev,
                 args.tag,
                 args.branch,
+                args.lfs,
                 args.extras,
                 args.package,
                 args.python,
diff --git a/crates/uv/src/settings.rs b/crates/uv/src/settings.rs
@@ -1469,6 +1469,7 @@ pub(crate) struct AddSettings {
     pub(crate) rev: Option<String>,
     pub(crate) tag: Option<String>,
     pub(crate) branch: Option<String>,
+    pub(crate) lfs: Option<bool>,
     pub(crate) package: Option<PackageName>,
     pub(crate) script: Option<PathBuf>,
     pub(crate) python: Option<String>,
@@ -1506,6 +1507,7 @@ impl AddSettings {
             rev,
             tag,
             branch,
+            lfs,
             no_sync,
             locked,
             frozen,
@@ -1600,6 +1602,7 @@ impl AddSettings {
             .unwrap_or_default();
 
         let bounds = bounds.or(filesystem.as_ref().and_then(|fs| fs.add.add_bounds));
+        let lfs = lfs.then_some(true);
 
         Self {
             locked,
@@ -1619,6 +1622,7 @@ impl AddSettings {
             rev,
             tag,
             branch,
+            lfs,
             package,
             script,
             python: python.and_then(Maybe::into_option),
diff --git a/crates/uv/tests/it/edit.rs b/crates/uv/tests/it/edit.rs
@@ -630,6 +630,16 @@ fn add_git_error() -> Result<()> {
     error: `flask` did not resolve to a Git repository, but a Git reference (`--branch 0.0.1`) was provided.
     "###);
 
+    // Request lfs without a Git source.
+    uv_snapshot!(context.filters(), context.add().arg("flask").arg("--lfs"), @r###"
+    success: false
+    exit_code: 2
+    ----- stdout -----
+
+    ----- stderr -----
+    error: `flask` did not resolve to a Git repository, but a Git extension (`--lfs`) was provided.
+    "###);
+
     Ok(())
 }
 
@@ -662,6 +672,103 @@ fn add_git_branch() -> Result<()> {
     Ok(())
 }
 
+#[test]
+#[cfg(feature = "git")]
+fn add_git_lfs() -> Result<()> {
+    let context = TestContext::new("3.13");
+
+    let pyproject_toml = context.temp_dir.child("pyproject.toml");
+    pyproject_toml.write_str(indoc! {r#"
+        [project]
+        name = "project"
+        version = "0.1.0"
+        requires-python = ">=3.13"
+        dependencies = []
+    "#})?;
+
+    uv_snapshot!(context.filters(), context.add().arg("test-lfs-repo @ git+https://github.com/samypr100/test-lfs-repo").arg("--rev").arg("657500f0703dc173ac5d68dfa1d7e8c985c84424").arg("--lfs"), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Resolved 2 packages in [TIME]
+    Prepared 1 package in [TIME]
+    Installed 1 package in [TIME]
+     + test-lfs-repo==0.1.0 (from git+https://github.com/samypr100/test-lfs-repo@657500f0703dc173ac5d68dfa1d7e8c985c84424#lfs=true)
+    ");
+
+    let pyproject_toml = context.read("pyproject.toml");
+
+    insta::with_settings!({
+        filters => context.filters(),
+    }, {
+        assert_snapshot!(
+            pyproject_toml, @r#"
+        [project]
+        name = "project"
+        version = "0.1.0"
+        requires-python = ">=3.13"
+        dependencies = [
+            "test-lfs-repo",
+        ]
+
+        [tool.uv.sources]
+        test-lfs-repo = { git = "https://github.com/samypr100/test-lfs-repo", rev = "657500f0703dc173ac5d68dfa1d7e8c985c84424", lfs = true }
+        "#
+        );
+    });
+
+    let lock = context.read("uv.lock");
+
+    insta::with_settings!({
+        filters => context.filters(),
+    }, {
+        assert_snapshot!(
+            lock, @r#"
+        version = 1
+        revision = 3
+        requires-python = ">=3.13"
+
+        [options]
+        exclude-newer = "2024-03-25T00:00:00Z"
+
+        [[package]]
+        name = "project"
+        version = "0.1.0"
+        source = { virtual = "." }
+        dependencies = [
+            { name = "test-lfs-repo" },
+        ]
+
+        [package.metadata]
+        requires-dist = [{ name = "test-lfs-repo", git = "https://github.com/samypr100/test-lfs-repo?lfs=true&rev=657500f0703dc173ac5d68dfa1d7e8c985c84424" }]
+
+        [[package]]
+        name = "test-lfs-repo"
+        version = "0.1.0"
+        source = { git = "https://github.com/samypr100/test-lfs-repo?lfs=true&rev=657500f0703dc173ac5d68dfa1d7e8c985c84424#657500f0703dc173ac5d68dfa1d7e8c985c84424" }
+        "#
+        );
+    });
+
+    uv_snapshot!(context.filters(), context.add().arg("test-lfs-repo @ git+https://github.com/samypr100/test-lfs-repo").arg("--rev").arg("4e82e85f6a8b8825d614ea23c550af55b2b7738c").arg("--lfs"), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Resolved 2 packages in [TIME]
+    Prepared 1 package in [TIME]
+    Uninstalled 1 package in [TIME]
+    Installed 1 package in [TIME]
+     - test-lfs-repo==0.1.0 (from git+https://github.com/samypr100/test-lfs-repo@657500f0703dc173ac5d68dfa1d7e8c985c84424#lfs=true)
+     + test-lfs-repo==0.1.0 (from git+https://github.com/samypr100/test-lfs-repo@4e82e85f6a8b8825d614ea23c550af55b2b7738c#lfs=true)
+    ");
+
+    Ok(())
+}
+
 /// Add a Git requirement using the `--raw-sources` API.
 #[test]
 #[cfg(feature = "git")]
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
@@ -865,7 +865,8 @@ uv add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>
 <ul>
 <li><code>disabled</code>:  Do not use keyring for credential lookup</li>
 <li><code>subprocess</code>:  Use the <code>keyring</code> command for credential lookup</li>
-</ul></dd><dt id="uv-add--link-mode"><a href="#uv-add--link-mode"><code>--link-mode</code></a> <i>link-mode</i></dt><dd><p>The method to use when installing packages from the global cache.</p>
+</ul></dd><dt id="uv-add--lfs"><a href="#uv-add--lfs"><code>--lfs</code></a></dt><dd><p>Whether to use Git LFS when adding a dependency from Git</p>
+</dd><dt id="uv-add--link-mode"><a href="#uv-add--link-mode"><code>--link-mode</code></a> <i>link-mode</i></dt><dd><p>The method to use when installing packages from the global cache.</p>
 <p>Defaults to <code>clone</code> (also known as Copy-on-Write) on macOS, and <code>hardlink</code> on Linux and Windows.</p>
 <p>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 (<code>uv cache clean</code>) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.</p>
 <p>May also be set with the <code>UV_LINK_MODE</code> environment variable.</p><p>Possible values:</p>
