sync/git(feat[GitSync]): Honor arbitrary clone depth

why: GitSync could express shallow-vs-full but not a numeric clone depth, so
downstream tools could only persist a boolean shallow flag. Addresses the core
of #531.
what:
- Add a depth keyword-only param to GitSync; obtain() forwards it to
  git clone --depth N. An explicit depth wins over git_shallow; unset keeps the
  prior depth-1-if-git_shallow-else-full behavior
- Document depth in the GitSync docstring
- Record the deferred update-time deepen/unshallow (#532) in a update_repo()
  .. todo:: with the two git edges it must handle
- Parametrized obtain() depth matrix test (full / git_shallow / depth=N /
  depth-overrides-git_shallow) over a 6-commit file:// remote
- CHANGES: What's new entry

Author: tony

CHANGES

@@ -20,6 +20,12 @@ $ uv add libvcs --prerelease allow
 _Notes on the upcoming release will go here._
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### What's new
+
+#### GitSync honors an arbitrary clone depth (#531)
+
+{class}`~libvcs.sync.git.GitSync` accepts a `depth` keyword argument that {meth}`~libvcs.sync.git.GitSync.obtain` forwards to `git clone --depth N`. When `depth` is unset the prior behavior is preserved: `git_shallow=True` clones at depth 1, and otherwise the clone is full. Downstream tools can now persist and apply a numeric shallow depth instead of only a boolean shallow flag.
+
 ### Fixes
 
 #### GitSync honors `git_shallow` and `tls_verify` constructor arguments (#531)

src/libvcs/sync/git.py

@@ -213,6 +213,7 @@ def __init__(
         remotes: GitRemotesArgs = None,
         git_shallow: bool = False,
         tls_verify: bool = False,
+        depth: int | None = None,
         **kwargs: t.Any,
     ) -> None:
         """Local git repository.
@@ -226,6 +227,11 @@ def __init__(
             Clone with history truncated to the latest commit (``--depth 1``,
             default False)
 
+        depth : int, optional
+            Clone with history truncated to ``depth`` commits
+            (``git clone --depth N``). Takes precedence over ``git_shallow``.
+            Default None (full clone).
+
         tls_verify : bool
             Should certificate for https be checked (default False)
 
@@ -266,6 +272,7 @@ def __init__(
         """
         self.git_shallow = git_shallow
         self.tls_verify = tls_verify
+        self.depth = depth
 
         self._remotes: GitSyncRemoteDict
 
@@ -368,10 +375,19 @@ def obtain(self, *args: t.Any, **kwargs: t.Any) -> None:
         url = self.url
 
         self.log.info("Cloning.")
+        # An explicit depth wins; otherwise git_shallow keeps the depth-1
+        # behavior, and neither means a full clone.
+        clone_depth: int | None
+        if self.depth is not None:
+            clone_depth = self.depth
+        elif self.git_shallow:
+            clone_depth = 1
+        else:
+            clone_depth = None
         self.cmd.clone(
             url=url,
             progress=True,
-            depth=1 if self.git_shallow else None,
+            depth=clone_depth,
             config={"http.sslVerify": False} if self.tls_verify else None,
             log_in_real_time=True,
         )
@@ -396,6 +412,15 @@ def update_repo(
     ) -> SyncResult:
         """Pull latest changes from git remote.
 
+        .. todo::
+
+            Honor ``depth`` on update by deepening or unshallowing the existing
+            checkout when the requested depth differs from what is on disk.
+            Tracked in https://github.com/vcs-python/libvcs/issues/532. Edges to
+            handle: ``git fetch --depth N`` against a full checkout truncates it
+            to shallow, and ``git fetch --unshallow`` against a complete repo is
+            a fatal error (guard with ``git rev-parse --is-shallow-repository``).
+
         Parameters
         ----------
         set_remotes : bool

tests/sync/test_git.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import datetime
+import os
 import pathlib
 import random
 import shutil
@@ -28,7 +29,7 @@
 if t.TYPE_CHECKING:
     from pytest_mock import MockerFixture
 
-    from libvcs.pytest_plugin import CreateRepoFn
+    from libvcs.pytest_plugin import CreateRepoFn, GitCommitEnvVars
 
 if not shutil.which("git"):
     pytestmark = pytest.mark.skip(reason="git is not available")
@@ -157,6 +158,79 @@ def test_git_shallow_and_tls_verify_kwargs_are_honored(
     assert is_shallow == "true"
 
 
+class DepthFixture(t.NamedTuple):
+    """Parameters for :func:`test_obtain_honors_clone_depth`."""
+
+    test_id: str
+    sync_kwargs: dict[str, t.Any]
+    expected_count: int
+    expected_shallow: bool
+
+
+DEPTH_FIXTURES: list[DepthFixture] = [
+    DepthFixture(
+        test_id="full-clone",
+        sync_kwargs={},
+        expected_count=6,
+        expected_shallow=False,
+    ),
+    DepthFixture(
+        test_id="git_shallow-depth-1",
+        sync_kwargs={"git_shallow": True},
+        expected_count=1,
+        expected_shallow=True,
+    ),
+    DepthFixture(
+        test_id="depth-3",
+        sync_kwargs={"depth": 3},
+        expected_count=3,
+        expected_shallow=True,
+    ),
+    DepthFixture(
+        test_id="depth-overrides-git_shallow",
+        sync_kwargs={"git_shallow": True, "depth": 2},
+        expected_count=2,
+        expected_shallow=True,
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    list(DepthFixture._fields),
+    DEPTH_FIXTURES,
+    ids=[test.test_id for test in DEPTH_FIXTURES],
+)
+def test_obtain_honors_clone_depth(
+    tmp_path: pathlib.Path,
+    create_git_remote_repo: CreateRepoFn,
+    git_commit_envvars: GitCommitEnvVars,
+    test_id: str,
+    sync_kwargs: dict[str, t.Any],
+    expected_count: int,
+    expected_shallow: bool,
+) -> None:
+    """obtain() clones at the requested depth; an explicit depth wins.
+
+    The ``file://`` URL matters: git ignores ``--depth`` for local-path clones.
+    """
+    remote_repo = create_git_remote_repo()
+    env = os.environ.copy()
+    env.update(git_commit_envvars)
+    for i in range(1, 7):
+        (remote_repo / "f.txt").write_text(str(i))
+        run(["git", "add", "f.txt"], cwd=remote_repo, env=env)
+        run(["git", "commit", "-m", f"c{i}"], cwd=remote_repo, env=env)
+
+    checkout = tmp_path / "checkout"
+    git_repo = GitSync(url=remote_repo.as_uri(), path=checkout, **sync_kwargs)
+    git_repo.obtain()
+
+    commit_count = run(["git", "rev-list", "--count", "HEAD"], cwd=checkout)
+    is_shallow = run(["git", "rev-parse", "--is-shallow-repository"], cwd=checkout)
+    assert int(commit_count) == expected_count
+    assert is_shallow == ("true" if expected_shallow else "false")
+
+
 @pytest.mark.parametrize(
     # Postpone evaluation of options so fixture variables can interpolate
     ("constructor", "lazy_constructor_options"),