docs: warn about GitDB performance with large commits

mvanhorn · mvanhorn · commit 859ea95b6d62 · 2026-03-22T00:11:12.000-07:00
Add a warning note in the Object Database section of the tutorial about GitDB failing or becoming extremely slow when traversing trees in repositories with very large commits (thousands of changed files). Directs users to switch to GitCmdObjectDB instead. Closes #2065
diff --git a/doc/source/tutorial.rst b/doc/source/tutorial.rst
@@ -513,6 +513,12 @@ The GitDB is a pure-python implementation of the git object database. It is the
 
     repo = Repo("path/to/repo", odbt=GitDB)
 
+.. warning::
+   ``GitDB`` may fail or become extremely slow when traversing trees in
+   repositories with very large commits (thousands of changed files in a
+   single commit). If you encounter ``RecursionError`` or excessive
+   slowness during tree traversal, switch to ``GitCmdObjectDB`` instead.
+
 
 GitCmdObjectDB
 ==============
