FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

refactor(db): deprecate the pure-Python `GitDB` backend · gitpython-developers/GitPython@0b64501 · GitHub

  1. gitpython-developers
  2. GitPython

Repository navigation

Commit 0b64501

Browse files
codex
authored and
Byron
committed
refactor(db): deprecate the pure-Python GitDB backend
<!-- Byron --> rubber-stamp, after checking diff quickly. <!-- agent --> The pure-Python `GitDB` backend has performance and security issues in object reading and resolution, including unbounded delta processing and incorrect object selection or reconstruction. `GitCmdObjectDB` is already the default and delegates these operations to Git. Emit `DeprecationWarning` from `Repo.__init__` when `odbt` selects `GitDB` or a subclass, directing callers to `GitCmdObjectDB`. Repository opening, initialization, and cloning all construct a `Repo` through this path. Keep the existing backend behavior available for compatibility and retain the `gitdb` dependency needed for shared types and utilities. Deprecation does not repair or disable the legacy parsers. Update backend-selection docstrings, the tutorial, and the changelog with migration guidance. Add regression checks that the deprecated backend and its subclasses warn at the direct caller's location while continuing to read objects, and that default, explicit, and subclassed `GitCmdObjectDB` use remains free of deprecation warnings. CI follow-up: the new deprecation test exposed that backend annotations accepted only `LooseObjectDB` descendants, excluding the supported legacy `GitDB`. Include both types in construction, initialization, and clone helpers. `basedpyright --warnings` and `mypy --python-version=3.12` pass; 16 focused deprecation/database tests and Ruff checks pass.
1 parent f8776ee commit 0b64501

4 files changed

Lines changed: 72 additions & 19 deletions

File tree

‎doc/source/changes.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,15 @@
22
Changelog
33
=========
44

5+
Unreleased
6+
==========
7+
8+
* Deprecate the pure-Python ``GitDB`` object database backend due to security and
9+
performance issues. Selecting it or a subclass through ``odbt`` now emits a
10+
``DeprecationWarning``. Remove ``odbt=GitDB`` to use ``GitCmdObjectDB``, the
11+
existing default, or select ``odbt=GitCmdObjectDB`` explicitly. The ``gitdb``
12+
package remains a dependency for shared types and utilities.
13+
514
3.2.1
615
=====
716

‎doc/source/tutorial.rst‎

Lines changed: 18 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -513,24 +513,29 @@ Object Databases
513513

514514
The type of the database determines certain performance characteristics, such as the quantity of objects that can be read per second, the resource usage when reading large data files, as well as the average memory footprint of your application.
515515

516-
GitDB
517-
=====
518-
The GitDB is a pure-python implementation of the git object database. It is the default database to use in GitPython 0.3. It uses less memory when handling huge files, but will be 2 to 5 times slower when extracting large quantities of small objects from densely packed repositories::
516+
GitCmdObjectDB
517+
==============
518+
``GitCmdObjectDB`` is the default and recommended backend. It reads objects and
519+
resolves abbreviated object IDs through persistent ``git cat-file`` processes::
519520

520-
repo = Repo("path/to/repo", odbt=GitDB)
521+
repo = Repo("path/to/repo")
522+
# Equivalent explicit selection:
523+
repo = Repo("path/to/repo", odbt=GitCmdObjectDB)
521524

525+
GitDB
526+
=====
522527
.. warning::
523-
``GitDB`` may fail or become extremely slow when traversing trees in
524-
repositories with very large commits (thousands of changed files in a
525-
single commit). If you encounter ``RecursionError`` or excessive
526-
slowness during tree traversal, switch to ``GitCmdObjectDB`` instead.
528+
The pure-Python ``GitDB`` backend is deprecated due to security and performance
529+
issues. Its object parsers can exhaust resources or return incorrect object
530+
data when processing untrusted repositories. Do not use it for untrusted data.
527531

532+
Selecting ``odbt=GitDB`` (including a subclass) emits a ``DeprecationWarning``.
533+
To migrate, remove ``odbt=GitDB`` or replace it with ``odbt=GitCmdObjectDB`` when
534+
opening, initializing, or cloning a repository. The deprecated backend remains
535+
available for compatibility; deprecation does not fix its parsing issues.
528536

529-
GitCmdObjectDB
530-
==============
531-
The git command database uses persistent git-cat-file instances to read repository information. These operate very fast under all conditions, but will consume additional memory for the process itself. When extracting large files, memory usage will be much higher than ``GitDB``::
532-
533-
repo = Repo("path/to/repo", odbt=GitCmdObjectDB)
537+
The ``gitdb`` package remains a dependency because GitPython still uses its shared
538+
types and utilities.
534539

535540
Git Command Debugging and Customization
536541
***************************************

‎git/repo/base.py‎

Lines changed: 18 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -228,7 +228,7 @@ class Repo:
228228
def __init__(
229229
self,
230230
path: Optional[PathLike] = None,
231-
odbt: Type[LooseObjectDB] = GitCmdObjectDB,
231+
odbt: Type[Union[LooseObjectDB, gitdb.GitDB]] = GitCmdObjectDB,
232232
search_parent_directories: bool = False,
233233
expand_vars: bool = True,
234234
) -> None:
@@ -255,7 +255,9 @@ def __init__(
255255
:param odbt:
256256
Object DataBase type - a type which is constructed by providing the
257257
directory containing the database objects, i.e. ``.git/objects``. It will be
258-
used to access all object data.
258+
used to access all object data. The pure-Python ``GitDB`` backend is
259+
deprecated due to security and performance issues. Use the default
260+
:class:`~git.db.GitCmdObjectDB` instead.
259261
260262
:param search_parent_directories:
261263
If ``True``, all parent directories will be searched for a valid repo as
@@ -411,6 +413,13 @@ def __init__(
411413
if issubclass(odbt, GitCmdObjectDB):
412414
self.odb = odbt(rootpath, self.git)
413415
else:
416+
if issubclass(odbt, gitdb.GitDB):
417+
warnings.warn(
418+
"GitDB is deprecated as a GitPython backend due to security and performance issues. "
419+
"Use the default GitCmdObjectDB backend instead.",
420+
DeprecationWarning,
421+
stacklevel=2,
422+
)
414423
self.odb = odbt(rootpath)
415424

416425
def __enter__(self) -> "Repo":
@@ -1456,7 +1465,7 @@ def init(
14561465
cls,
14571466
path: Union[PathLike, None] = None,
14581467
mkdir: bool = True,
1459-
odbt: Type[GitCmdObjectDB] = GitCmdObjectDB,
1468+
odbt: Type[Union[LooseObjectDB, gitdb.GitDB]] = GitCmdObjectDB,
14601469
expand_vars: bool = True,
14611470
allow_unsafe_options: bool = False,
14621471
**kwargs: Any,
@@ -1476,7 +1485,8 @@ def init(
14761485
:param odbt:
14771486
Object DataBase type - a type which is constructed by providing the
14781487
directory containing the database objects, i.e. ``.git/objects``. It will be
1479-
used to access all object data.
1488+
used to access all object data. The pure-Python ``GitDB`` backend is
1489+
deprecated; use the default :class:`~git.db.GitCmdObjectDB` instead.
14801490
14811491
:param expand_vars:
14821492
If specified, environment variables will not be escaped. This can lead to
@@ -1515,7 +1525,7 @@ def _clone(
15151525
git: "Git",
15161526
url: PathLike,
15171527
path: PathLike,
1518-
odb_default_type: Type[LooseObjectDB],
1528+
odb_default_type: Type[Union[LooseObjectDB, gitdb.GitDB]],
15191529
progress: Union["RemoteProgress", "UpdateProgress", Callable[..., "RemoteProgress"], None] = None,
15201530
multi_options: Optional[List[str]] = None,
15211531
allow_unsafe_protocols: bool = False,
@@ -1639,7 +1649,9 @@ def clone(
16391649
16401650
:param kwargs:
16411651
* ``odbt`` = ObjectDatabase Type, allowing to determine the object database
1642-
implementation used by the returned :class:`Repo` instance.
1652+
implementation used by the returned :class:`Repo` instance. The
1653+
pure-Python ``GitDB`` backend is deprecated; use the default
1654+
:class:`~git.db.GitCmdObjectDB` instead.
16431655
* All remaining keyword arguments are given to the :manpage:`git-clone(1)`
16441656
command.
16451657

‎test/deprecation/test_basic.py‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717

1818
import pytest
1919

20+
from git.db import GitCmdObjectDB, GitDB
2021
from git.diff import NULL_TREE
2122
from git.objects.util import Traversable
2223
from git.repo import Repo
@@ -60,6 +61,32 @@ def diffs(commit: "Commit") -> Generator["DiffIndex", None, None]:
6061
yield commit.diff(NULL_TREE)
6162

6263

64+
def test_gitdb_backend_warns(commit: "Commit") -> None:
65+
class DerivedGitDB(GitDB):
66+
pass
67+
68+
for backend in (GitDB, DerivedGitDB):
69+
with pytest.deprecated_call(match="GitDB.*deprecated.*GitCmdObjectDB") as caught:
70+
with Repo(commit.repo.working_dir, odbt=backend) as repo:
71+
assert type(repo.odb) is backend
72+
assert repo.head.commit.message == commit.message
73+
assert len(caught) == 1
74+
assert caught[0].filename == __file__
75+
76+
77+
def test_gitcmdobjectdb_backend_does_not_warn(commit: "Commit") -> None:
78+
class DerivedGitCmdObjectDB(GitCmdObjectDB):
79+
pass
80+
81+
with assert_no_deprecation_warning():
82+
with Repo(commit.repo.working_dir) as repo:
83+
assert type(repo.odb) is GitCmdObjectDB
84+
for backend in (GitCmdObjectDB, DerivedGitCmdObjectDB):
85+
with Repo(commit.repo.working_dir, odbt=backend) as repo:
86+
assert type(repo.odb) is backend
87+
assert repo.head.commit.message == commit.message
88+
89+
6390
def test_diff_renamed_warns(diff: "Diff") -> None:
6491
"""The deprecated Diff.renamed property issues a deprecation warning."""
6592
with pytest.deprecated_call():

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL