Add Commit.is_shallow property and document stats() limitation at shallow boundary

harshitayadavv · claude · harshitayadavv · commit 837a4f068e6b · 2026-07-05T18:27:41.000+05:30
Accessing .stats on a commit at the boundary of a shallow clone raises
GitCommandError because the commit's parent SHA was never fetched. This
adds an is_shallow property to detect this case ahead of time by checking
the repository's shallow file, and documents the limitation on stats().

Co-authored-by: Claude &lt;noreply@anthropic.com&gt;
diff --git a/AUTHORS b/AUTHORS
@@ -57,5 +57,6 @@ Contributors are:
 -Jonas Scharpf <jonas.scharpf _at_ checkmk.com>
 -Gordon Marx
 -Enji Cooper
+-Harshita Yadav <harshitayadav504 _at_ gmail.com>
 
 Portions derived from other open source works and are clearly marked.
diff --git a/git/objects/commit.py b/git/objects/commit.py
@@ -368,12 +368,38 @@ def iter_parents(self, paths: Union[PathLike, Sequence[PathLike]] = "", **kwargs
         kwargs["skip"] = skip
 
         return self.iter_items(self.repo, self, paths, **kwargs)
+    @property
+    def is_shallow(self) -> bool:
+        """Check whether this commit is a shallow boundary (graft) commit.
+
+        A commit at the boundary of a shallow clone appears to have no
+        parents from Git's perspective, even though the underlying commit
+        object still references a parent SHA that was never fetched. Calling
+        :attr:`stats` (or anything else that diffs against the parent) on
+        such a commit will raise :exc:`~git.exc.GitCommandError` because the
+        parent object does not exist locally.
 
+        :return:
+            True if this commit's hexsha appears in the repository's
+            ``shallow`` file, False otherwise (including for non-shallow
+            repositories).
+        """
+        shallow_file = os.path.join(self.repo.git_dir, "shallow")
+        if not os.path.isfile(shallow_file):
+            return False
+        with open(shallow_file, "r") as f:
+            return self.hexsha in f.read().split()
+    
     @property
     def stats(self) -> Stats:
         """Create a git stat from changes between this commit and its first parent
         or from all changes done if this is the very first commit.
 
+        :note:
+            If this commit is at the boundary of a shallow clone (see
+            :attr:`is_shallow`), this will raise :exc:`~git.exc.GitCommandError`
+            because the parent object was never fetched.
+
         :return:
             :class:`Stats`
         """
diff --git a/test/test_commit.py b/test/test_commit.py
@@ -14,7 +14,7 @@
 
 from gitdb import IStream
 
-from git import Actor, Commit, Repo
+from git import Actor, Commit, GitCommandError, Repo
 from git.objects.util import tzoffset, utc
 from git.repo.fun import touch
 
@@ -163,6 +163,25 @@ def check_entries(d, has_change_type=False):
         self.assertEqual(commit.author_tz_offset, 14400, commit.author_tz_offset)
         self.assertEqual(commit.committer_tz_offset, 14400, commit.committer_tz_offset)
         self.assertEqual(commit.message, "initial project\n")
+    
+    @with_rw_directory
+    def test_is_shallow(self, rw_dir):
+        """A commit at the shallow boundary should report is_shallow, and
+        accessing its stats should raise GitCommandError."""
+        full_repo = self.rorepo
+        shallow_path = osp.join(rw_dir, "shallow_clone")
+        shallow_repo = Repo.clone_from(full_repo.git_dir, shallow_path, depth=2, no_local=True)
+
+        commits = list(shallow_repo.iter_commits())
+        boundary_commit = commits[-1]
+
+        self.assertTrue(boundary_commit.is_shallow)
+        with self.assertRaises(GitCommandError):
+            boundary_commit.stats
+
+        if len(commits) > 1:
+            non_boundary_commit = commits[0]
+            self.assertFalse(non_boundary_commit.is_shallow)
 
     def test_renames(self):
         commit = self.rorepo.commit("185d847ec7647fd2642a82d9205fb3d07ea71715")
