refactor!: delegate index state and metadata decoding to Git and Gix

Python previously retained mutable index dictionaries and reconstructed index
files from those entries. That duplicated Git semantics and allowed validation
and publication to diverge. Keep deferred and virtual indexes as opaque bytes;
materialize a private file before Git edits it, verify requested entries survived,
and publish through the existing atomic lock. Replace `IndexFile.entries` with
`iter_entries()` and `entry()` and migrate submodule, tutorial and test callers.

Preserve deferred add/remove and conflict resolution, alternate publication,
index versions and flags, split snapshots, checkout/diff visibility and hook
edits. Failed ordinary edits retain pending and published state. Reject NULs
before encoding stdin records. Keep source containment checks because Python
reads those paths before Git validates the recorded destination.

Use GixPython's structured commit/tag decoders, including signature headers and
encoding, instead of parsing native object bytes. Retain raw CLI commit/tag
metadata decoding where formatted Git output cannot preserve those fields.
Delegate textual date syntax and trailer discovery to Git. Record Gix's unsafe
index insertion, missing date parser and missing strict tag validation as
`GIX-26` through `GIX-28`; private index edits and tag storage use CLI fallbacks.
A native byte round trip alone does not prove Git-compatible validation.

Remove the deprecated `GitDB` selection, API aliases, global shell switch,
automatic environment expansion and Windows error-hiding switches. Keep explicit
shell selection and tilde expansion. Document replacements and changed timezone
and trailer behavior in `doc/source/changes.rst`.

Delete obsolete parser/deprecation tests, repeated rejection matrices and
historical timing-only tests. Retain happy paths, Python glue/security failures,
atomicity and demonstrated compatibility regressions. The maintained benchmark
continues to check parity and CLI process budgets.

Replace Python-built repository and filesystem initial states across the
maintained tests with Bash scripts executed by `gix.testtools`. Git CLI creates
the states and defines expected behavior; both backends exercise the same
fixtures. Read-only calls share cached script output. Mutators receive native
writable copies, with explicit execution only for symlinks, permissions,
virtual environments or metadata that embeds its own absolute location.
Keep immutable parser byte samples and operations under test in Python.

Move repository seeding for discovery, refs, objects, index, configuration,
diffs, submodules, remotes, tutorials, installation and filesystem tests into
scripts. Preserve the original assertions, including literal filenames and
Git's large-integer configuration behavior from the updated `main` base.
Serialization, raw object writes and optional index-refreshing commands now
use private fixtures instead of modifying the shared read-only repository.

Use the supported versioned fixture API to avoid GixPython 0.2.0 memoization
collisions when arguments contain absolute paths. Sanitize fixture errors that
otherwise expose inherited environment variables. Preserve best-effort cleanup
and failed-test artifacts around the native temporary owner, including a
backup when a locked directory cannot be renamed. Record these upstream
limitations in `doc/gix-backend.md`. Generated fixture data and archives stay
out of the source distribution; no archives are required. Document the Python
3.11+ fixture-suite requirement and keep Cygwin Python 3.9 as an import smoke job.

Validation with CPython 3.12 on macOS, Git 2.54.0 and GixPython 0.2.0:

- Full CLI suite: 1,691 passed, 151 skipped, one existing expected failure,
  and 44 subtests passed. Full Gix suite: 1,793 passed, 51 skipped, one
  existing expected failure, and 44 subtests passed.
- Final cleanup/cache and shared-write corrections: 29 passed and one
  platform skip on each backend, after the full runs.
- SWE-bench's four local storage-format checks passed on each backend.
- All 14 benchmark result digests matched and existing Gix CLI-process
  ceilings passed; single-value runs establish no timing conclusion.
- `pre-commit`, Ruff, `mypy`, `basedpyright`, ShellCheck, actionlint,
  warnings-as-errors Sphinx and `git diff --check` passed.

Hosted CI, Windows, Alpine, Cygwin and older interpreters were not executed
locally. Removed APIs and corrected date/trailer behavior require migration.

Author: codex

.basedpyright/baseline.json

@@ -228,24 +228,6 @@
         }
       }
     ],
-    "./git/remote.py": [
-      {
-        "code": "reportAttributeAccessIssue",
-        "range": {
-          "startColumn": 26,
-          "endColumn": 38,
-          "lineCount": 1
-        }
-      },
-      {
-        "code": "reportAttributeAccessIssue",
-        "range": {
-          "startColumn": 26,
-          "endColumn": 38,
-          "lineCount": 1
-        }
-      }
-    ],
     "./git/repo/base.py": [
       {
         "code": "reportTypedDictNotRequiredAccess",
@@ -311,16 +293,6 @@
           "lineCount": 1
         }
       }
-    ],
-    "./test/deprecation/test_basic.py": [
-      {
-        "code": "reportUnusedExpression",
-        "range": {
-          "startColumn": 12,
-          "endColumn": 62,
-          "lineCount": 1
-        }
-      }
     ]
   }
 }

.github/workflows/cygwin-test.yml

@@ -1,4 +1,4 @@
-name: test-cygwin
+name: import-cygwin
 
 on:
   push:
@@ -11,22 +11,12 @@ permissions:
 
 jobs:
   test:
-    strategy:
-      matrix:
-        selection: [fast, perf]
-        include:
-        - selection: fast
-          additional-pytest-args: --ignore=test/performance
-        - selection: perf
-          additional-pytest-args: test/performance
-
-      fail-fast: false
-
     runs-on: windows-latest
 
     env:
       CHERE_INVOKING: "1"
       CYGWIN_NOWINPATH: "1"
+      GIT_PYTHON_BACKEND: cli
 
     defaults:
       run:
@@ -94,9 +84,9 @@ jobs:
       run: |
         python -m pip install -U 'setuptools; python_version<"3.12"' wheel
 
-    - name: Install project and test dependencies
+    - name: Install project
       run: |
-        pip install ./smmap ./gitdb '.[test]'
+        pip install ./smmap ./gitdb .
 
     - name: Verify Cygwin Git detection
       run: python -c 'from git import Git; assert Git.is_cygwin()'
@@ -149,6 +139,5 @@ jobs:
         python --version
         python -c 'import os, sys; print(f"{sys.platform=}, {os.name=}")'
 
-    - name: Test with pytest (${{ matrix.additional-pytest-args }})
-      run: |
-        pytest --color=yes -p no:sugar --instafail -vv ${{ matrix.additional-pytest-args }}
+    - name: Smoke check the installed package on Python 3.9
+      run: python -I -c "import git; from git import _backend; assert _backend.name == 'cli'; print(git.__version__)"

CONTRIBUTING.md

@@ -40,9 +40,19 @@ origin.
 
 ## Temporary test directories
 
-Use `test.cleanup.TemporaryDirectory` for isolated temporary directories and
-`test.cleanup.cleanup_directory` when disposing of directories created by test
-fixtures. Close repository handles before removing their files. Cleanup is
+Tests require Python 3.11+, Git 2.52+, Bash, and the `test` extra, which installs
+GixPython even when testing the CLI backend. Select `GIT_PYTHON_BACKEND=cli` or
+`GIT_PYTHON_BACKEND=gix` before running pytest.
+
+Put initial repository and filesystem states in `tests/fixtures/*.sh` and use
+`test.lib.fixtures` to run them through `gix.testtools`. Read-only tests share
+cached output; mutating tests use writable copies. Use `execute=True` only when
+the fixture cannot be copied, and explain the reason at its call site. Keep
+operations under test in Python. Immutable parser byte samples remain in
+`test/fixtures`; generated caches and archives are ignored.
+
+Use `test.cleanup.cleanup_directory` for cleanup outside the shared fixture
+owners. Close repository handles before removing their files. Cleanup is
 best-effort: it logs filesystem errors, removes whatever it can, and leaves
 locked files behind without failing or skipping a test. The shared writable
 repository decorators still keep failed tests' directories for debugging.

MANIFEST.in

@@ -11,5 +11,6 @@ include git/py.typed
 
 recursive-include doc *
 recursive-exclude test *
+prune tests
 
 global-exclude __pycache__ *.pyc

doc/gix-backend.md

@@ -51,8 +51,10 @@ API changes
 * ``GitCmdObjectDB`` no longer inherits ``LooseObjectDB``. Its object reads,
   writes, existence checks, and enumeration use Git, including packed objects.
   Precompressed input streams and custom object-output writers are unsupported.
-  The deprecated ``GitDB`` remains explicitly selectable with its existing
-  warning and limitations; ``gitdb`` remains a dependency for shared types.
+  ``GitDB`` exports and backend selection are removed. ``odbt`` accepts only
+  ``GitCmdObjectDB`` and its subclasses, rejecting unsupported types before
+  initialization or cloning. Remove ``odbt=GitDB`` or select ``GitCmdObjectDB``.
+  ``gitdb`` remains a dependency for shared types and utilities.
 * ``Repo.object_format`` and ``Repo.ref_format`` report Git's storage formats.
   ``Repo.alternates`` is read-only and reports effective absolute alternate
   directories, including environment and transitive alternates. Direct editing
@@ -99,6 +101,52 @@ API changes
   Fetch/pull results are derived from command output rather than ``FETCH_HEAD``
   file parsing. Revision strings follow Git's native revision grammar.
 
+* ``IndexFile.entries`` is removed. Use ``iter_entries()`` for immutable query
+  records, ``entry(path, stage=0)`` for exact lookup (missing entries raise
+  ``KeyError``), ``add()``, and ``remove()`` for edits. Python retains only opaque
+  index-file bytes for deferred/virtual indexes. Git edits private files and
+  validates readback before atomic publication. ``add(write=False)`` and
+  ``resolve_blobs()`` retain deferred edits; ``remove(..., write=False)`` now does
+  too, unless ``working_tree=True``. ``write(file_path)`` publishes to an alternate
+  path. Checkout and diff use pending bytes. Git owns versions, flags, sparse and
+  split indexes; deferred split snapshots are made standalone through Git.
+  Ordinary failed index edits preserve pending and published state. Worktree,
+  object storage and hook side effects are not rolled back. Commit hooks see the
+  materialized index; their index edits survive failures without advancing HEAD.
+  Binary-parser tests and duplicate filename-rejection matrices are replaced by
+  happy paths, Python glue failures and representative compatibility regressions.
+  Historical timing-only tests are removed; the maintained backend benchmark
+  checks result parity and CLI budgets.
+* Commit/tag metadata uses structured Gix decoders when the Gix backend supports
+  the repository. The CLI backend retains raw decoding because Git has no faithful
+  formatted query for all commit headers or arbitrary tag objects. ``gpgsig``
+  remains readable. The small ``Actor.from_string()`` and
+  ``parse_actor_and_date()`` identity helpers remain supported.
+* ``parse_date()`` delegates text syntax and timezone interpretation to Git;
+  aware datetimes retain direct conversion and invalid inputs raise ``ValueError``.
+  ISO/RFC dates now apply their timezone to the UTC timestamp, correcting the
+  previous behavior. Dates without a zone use Git's local timezone, and accepted
+  date syntax follows the installed Git version. Use an explicit timezone for
+  reproducible results. ``co_authors`` now uses Git's final trailer block rather
+  than scanning arbitrary message lines; use a valid trailer block after a blank
+  line.
+* Removed deprecated APIs: ``Git.USE_SHELL`` (explicit ``Git.execute(shell=...)``
+  remains), ``Diff.renamed`` (use ``renamed_file``), ``Commit.trailers`` (use
+  ``trailers_list`` or ``trailers_dict``), ``Actor.name_email_regex`` (use
+  ``Actor.from_string``), ``git.util.Iterable`` (use ``IterableObj``),
+  ``git.compat.is_win/is_posix/is_darwin`` (use ``os.name``/``sys.platform``), and
+  ``git.types.Lit_commit_ish`` (use ``Literal["commit", "tag"]`` or
+  ``GitObjectTypeString``). Top-level typing exports and private module aliases
+  are removed; import from ``typing`` or the owning module. ``git.util`` now
+  exposes the actual utility module. Abstract ``Traversable.traverse`` and
+  ``list_traverse`` raise ``NotImplementedError``; use concrete implementations.
+* Paths and URLs no longer expand ``$VAR``/``%VAR%`` automatically. Removed
+  ``expand_vars`` switches from ``Repo``, ``Repo.init``, ``expand_path``,
+  ``cygpath`` and ``Git.polish_url``. Expand explicitly with
+  ``os.path.expandvars`` if wanted; initial ``~`` expansion remains.
+  ``HIDE_WINDOWS_KNOWN_ERRORS`` and ``HIDE_WINDOWS_FREEZE_ERRORS`` are removed.
+  ``rmtree`` propagates filesystem errors rather than raising ``SkipTest``.
+
 3.2.1
 =====
 

doc/source/changes.rst

@@ -6,7 +6,7 @@ Overview / Install
 
 GitPython is a python library used to interact with git repositories, high-level like git-porcelain, or low-level like git-plumbing.
 
-It provides Python objects for repository data and delegates Git operations to the Git executable. The default backend supports both SHA-1 and SHA-256 object IDs and both files and reftable reference storage. The legacy pure-Python GitDB backend remains available but is deprecated.
+It provides Python objects for repository data and delegates Git operations to the Git executable. The default backend supports both SHA-1 and SHA-256 object IDs and both files and reftable reference storage. The legacy pure-Python GitDB backend is removed.
 
 The object database implementation is optimized for handling large quantities of objects and large datasets, which is achieved by using low-level structures and data streaming.
 
@@ -15,7 +15,7 @@ Requirements
 
 * `Python`_ >= 3.8
 * `Git`_ 2.52 or newer
-* `GitDB`_ - shared data types and the deprecated legacy object database
+* `GitDB`_ - shared data types and utilities
 * `typing_extensions`_ >= 3.7.3.4 (if python < 3.10)
 
 .. _Python: https://www.python.org

doc/source/intro.rst

@@ -341,7 +341,7 @@ As trees allow direct access to their intermediate child entries only, use the t
 
 The Index Object
 ****************
-The git index is the stage containing changes to be written with the next commit or where merges finally have to take place. You may access and manipulate semantic entries (mode, object ID, path, and stage) using the :class:`IndexFile <git.index.base.IndexFile>` object. Git reads and writes the underlying index; raw stat fields and binary index extensions are not exposed.
+The git index is the stage containing changes to be written with the next commit or where merges finally have to take place. Use :meth:`IndexFile.iter_entries <git.index.base.IndexFile.iter_entries>` and :meth:`IndexFile.entry <git.index.base.IndexFile.entry>` to query immutable entry records (mode, object ID, path, and stage); use ``add`` and ``remove`` to edit them. Deferred edits retain opaque index-file bytes. Git reads and writes the underlying index; raw stat fields and binary index extensions are not exposed.
 Modify the index with ease
 
 .. literalinclude:: ../../test/test_docs.py
@@ -522,20 +522,9 @@ resolves abbreviated object IDs through persistent ``git cat-file`` processes::
     # Equivalent explicit selection:
     repo = Repo("path/to/repo", odbt=GitCmdObjectDB)
 
-GitDB
-=====
-.. warning::
-   The pure-Python ``GitDB`` backend is deprecated due to security and performance
-   issues. Its object parsers can exhaust resources or return incorrect object
-   data when processing untrusted repositories. Do not use it for untrusted data.
-
-Selecting ``odbt=GitDB`` (including a subclass) emits a ``DeprecationWarning``.
-To migrate, remove ``odbt=GitDB`` or replace it with ``odbt=GitCmdObjectDB`` when
-opening, initializing, or cloning a repository. The deprecated backend remains
-available for compatibility; deprecation does not fix its parsing issues.
-
-The ``gitdb`` package remains a dependency because GitPython still uses its shared
-types and utilities.
+Only ``GitCmdObjectDB`` and subclasses can be selected through ``odbt``. The
+legacy ``GitDB`` backend is removed. The ``gitdb`` package remains a dependency
+for shared types and utilities.
 
 Git Command Debugging and Customization
 ***************************************

doc/source/tutorial.rst

@@ -29,7 +29,6 @@
     "GitCommandError",
     "GitCommandNotFound",
     "GitConfigParser",
-    "GitDB",
     "GitError",
     "HEAD",
     "Head",
@@ -40,13 +39,11 @@
     "IndexObject",
     "InvalidDBRoot",
     "InvalidGitRepositoryError",
-    "List",  # Deprecated - import this from `typing` instead.
     "LockFile",
     "NULL_TREE",
     "NoSuchPathError",
     "ODBError",
     "Object",
-    "Optional",  # Deprecated - import this from `typing` instead.
     "ParseError",
     "PathLike",
     "PushInfo",
@@ -60,19 +57,15 @@
     "RepositoryDirtyError",
     "RootModule",
     "RootUpdateProgress",
-    "Sequence",  # Deprecated - import from `typing`, or `collections.abc` in 3.9+.
     "StageType",
     "Stats",
     "Submodule",
     "SymbolicReference",
-    "TYPE_CHECKING",  # Deprecated - import this from `typing` instead.
     "Tag",
     "TagObject",
     "TagReference",
     "Tree",
     "TreeModifier",
-    "Tuple",  # Deprecated - import this from `typing` instead.
-    "Union",  # Deprecated - import this from `typing` instead.
     "UnmergedEntriesError",
     "UnsafeOptionError",
     "UnsafeProtocolError",
@@ -88,12 +81,7 @@
 
 __version__ = "git"
 
-from typing import Any, List, Optional, Sequence, TYPE_CHECKING, Tuple, Union
-
-if TYPE_CHECKING:
-    from types import ModuleType
-
-import warnings
+from typing import Optional as _Optional
 
 from git.util import to_hex_sha
 
@@ -158,7 +146,7 @@
         DiffIndex,
         Diffable,
     )
-    from git.db import GitCmdObjectDB, GitDB  # @NoMove
+    from git.db import GitCmdObjectDB  # @NoMove
     from git.cmd import Git  # @NoMove
     from git.repo import Repo  # @NoMove
     from git.remote import FetchInfo, PushInfo, Remote, RemoteProgress  # @NoMove
@@ -169,9 +157,6 @@
         IndexEntry,
         IndexFile,
         StageType,
-        # NOTE: This tells type checkers what util resolves to. We delete it, and it is
-        # really resolved by __getattr__, which warns. See below on what to use instead.
-        util,
     )
     from git.util import (  # @NoMove
         Actor,
@@ -185,82 +170,12 @@
     raise ImportError("%s: %s" % (_exc.__class__.__name__, _exc)) from _exc
 
 
-def _warned_import(message: str, fullname: str) -> "ModuleType":
-    import importlib
-
-    warnings.warn(message, DeprecationWarning, stacklevel=3)
-    return importlib.import_module(fullname)
-
-
-def _getattr(name: str) -> Any:
-    # TODO: If __version__ is made dynamic and lazily fetched, put that case right here.
-
-    if name == "util":
-        return _warned_import(
-            "The expression `git.util` and the import `from git import util` actually "
-            "reference git.index.util, and not the git.util module accessed in "
-            '`from git.util import XYZ` or `sys.modules["git.util"]`. This potentially '
-            "confusing behavior is currently preserved for compatibility, but may be "
-            "changed in the future and should not be relied on.",
-            fullname="git.index.util",
-        )
-
-    for names, prefix in (
-        ({"head", "log", "reference", "symbolic", "tag"}, "git.refs"),
-        ({"base", "fun", "typ"}, "git.index"),
-    ):
-        if name not in names:
-            continue
-
-        fullname = f"{prefix}.{name}"
-
-        return _warned_import(
-            f"{__name__}.{name} is a private alias of {fullname} and subject to "
-            f"immediate removal. Use {fullname} instead.",
-            fullname=fullname,
-        )
-
-    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
-
-
-if not TYPE_CHECKING:
-    # NOTE: The expression `git.util` gives git.index.util and `from git import util`
-    # imports git.index.util, NOT git.util. It may not be feasible to change this until
-    # the next major version, to avoid breaking code inadvertently relying on it.
-    #
-    # - If git.index.util *is* what you want, use (or import from) that, to avoid
-    #   confusion.
-    #
-    # - To use the "real" git.util module, write `from git.util import ...`, or if
-    #   necessary access it as `sys.modules["git.util"]`.
-    #
-    # Note also that `import git.util` technically imports the "real" git.util... but
-    # the *expression* `git.util` after doing so is still git.index.util!
-    #
-    # (This situation differs from that of other indirect-submodule imports that are
-    # unambiguously non-public and subject to immediate removal. Here, the public
-    # git.util module, though different, makes less discoverable that the expression
-    # `git.util` refers to a non-public attribute of the git module.)
-    #
-    # This had originally come about by a wildcard import. Now that all intended imports
-    # are explicit, the intuitive but potentially incompatible binding occurs due to the
-    # usual rules for Python submodule bindings. So for now we replace that binding with
-    # git.index.util, delete that, and let __getattr__ handle it and issue a warning.
-    #
-    # For the same runtime behavior, it would be enough to forgo importing util, and
-    # delete util as created naturally; __getattr__ would behave the same. But type
-    # checkers would not know what util refers to when accessed as an attribute of git.
-    del util
-
-    # This is "hidden" to preserve static checking for undefined/misspelled attributes.
-    __getattr__ = _getattr
-
 # { Initialize git executable path
 
 GIT_OK = None
 
 
-def refresh(path: Optional[PathLike] = None) -> None:
+def refresh(path: _Optional[PathLike] = None) -> None:
     """Convenience method for setting the git executable path.
 
     :param path: