From 859ea95b6d6207dab3d406f28234e6507ff1f527 Mon Sep 17 00:00:00 2001
From: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Sun, 22 Mar 2026 00:11:12 -0700
Subject: [PATCH] docs: warn about GitDB performance with large commits

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
---
 doc/source/tutorial.rst | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/doc/source/tutorial.rst b/doc/source/tutorial.rst
index fd3b14c57..d095d3be3 100644
--- 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
 ==============