docs: align documentation with released behavior

The documentation described temporary development regressions as restored
public behavior, including a `TreeModifier` deprecation that never shipped.
Audit current guidance and the changelog against `3.2.1` and the relevant
historical release tags so dependants see the net changes from releases.

Describe tree editing, configuration assignment, revision paths, literal
paths and compatibility imports directly. Clarify that `GitDB` selects the
managed backend, and scope the version lookup improvement to source checkouts.
Remove the historical tree-removal entry: its announcement shipped in `1.0.2`,
but the API was present in both `1.0.1` and `1.0.2`. Keep genuine released
deprecations and fixes.

Identify the Gix integration as unreleased and its measurements as development
validation. Remove internal restoration and commit-rewrite narration while
preserving compatibility bugs, reproduction evidence and measurement caveats.

The strict Sphinx HTML build, Ruff lint/format checks and `git diff --check`
pass. Python AST comparison confirms that source edits affect only docstrings
and comments; runtime tests were not rerun for this documentation-only change.

Author: codex

doc/gix-backend.md

@@ -51,40 +51,28 @@ Git executable and safety
 API changes
 -----------
 
-* Packed tag names containing non-UTF-8 bytes remain losslessly represented as
+* Packed tag names containing non-UTF-8 bytes are represented losslessly as
   surrogate-escaped strings. ``safe_encode()`` recovers their original bytes,
   and Gix reference validation and resolution receive those bytes directly.
 * Raw diffs preserve non-UTF-8 filename bytes in ``a_rawpath``, ``b_rawpath``,
   and raw rename fields. Staged-file diffs no longer fail while decoding legacy
   filenames; blob contents remain byte streams regardless of their encoding.
-* ``Tree.cache`` and ``TreeModifier`` remain supported. They edit one tree's
-  in-memory entries; object IDs and parent trees do not change automatically.
-  Tree serialization now delegates construction to Git or the supported Gix
-  backend. Prefer ``IndexFile.write_tree()`` for changes to staged paths.
+* Tree serialization now delegates construction to Git or the supported Gix
+  backend. ``Tree.cache`` and ``TreeModifier`` edit one tree's in-memory entries;
+  object IDs and parent trees do not change automatically. Prefer
+  ``IndexFile.write_tree()`` for changes to staged paths.
 * ``Commit.stats`` preserves Unicode line separators in filenames when
   ``core.quotePath=false``. Git's LF-delimited output remains intact for root,
-  subsequent and empty commits, including the Gix backend's existing filename
+  subsequent and empty commits, including the Gix backend's filename
   quoting fallback.
-* ``GitConfigParser[section] = values`` again replaces a nonempty section,
-  restoring Kas's Git identity cleanup. Git performs each mutation and locks
-  it independently; replacement is not one atomic transaction. Empty sections
-  and ``add_section()`` remain unsupported, including Kas's SSH key setup.
-* Explicit ``from git import Union`` and ``Optional`` imports remain available
-  for Demisto SDK's validator registration and MkDocs RSS Plugin imports,
-  retaining the historical ``typing`` aliases.
-* Editable/source imports expose the release version in ``git.__version__``,
-  matching built distributions. Salt's GitPython provider checks can parse the
-  version instead of rejecting the unstamped ``"git"`` build placeholder.
+* Imports from a source checkout now read ``git.__version__`` from ``VERSION``.
+  Built wheels and source distributions continue to carry their stamped release
+  version.
 * ``Repo`` construction validates repository configuration through Git/Gix.
   A subclass override of ``config_reader()`` no longer controls discovery or
   suppresses its include graph. Malformed configuration and invalid repository
-  extensions can fail before downstream custom validation runs. sbxloop's
-  metadata-reader subclass exposes this remaining compatibility break; callers
-  must prepare their trusted metadata view before opening it with ``Repo``.
-* Revision root trees such as ``Repo.rev_parse("HEAD:")`` retain their empty
-  path and can be iterated. Missing paths within a valid tree revision retain
-  ``Tree.join()``'s ``KeyError`` and missing-component message, restoring MCP
-  Server Git's directory display and path-error reporting.
+  extensions can fail before downstream custom validation runs. Callers using
+  custom metadata views must prepare them before opening with ``Repo``.
 * ``Head.tracking_branch()`` returns a local ``Head`` when Git configures the
   current repository (``branch.<name>.remote=.``) as the upstream, instead of
   constructing an invalid ``refs/remotes/./...`` reference. Git resolves the
@@ -133,16 +121,21 @@ API changes
 * ``GitConfigParser`` uses Git's configuration syntax and canonical key spelling,
   and no longer subclasses ``configparser.RawConfigParser``.
   Common getters, typed values, duplicate values, file/stream inputs and mutation
-  methods remain. Invalid Git syntax previously accepted by Python is rejected.
-  Empty-section creation and valueless writes are removed; valueless reads remain.
-  Relative includes from streams are rejected by Git. Locks cover each native
-  mutation rather than the writer object's lifetime.
+  methods remain, including ``GitConfigParser[section] = values`` for replacing
+  nonempty sections. Invalid Git syntax previously accepted by Python is rejected.
+  Empty-section creation, including ``add_section()``, and valueless writes are
+  removed; valueless reads remain. Relative includes from streams are rejected
+  by Git. Locks cover each native mutation rather than the writer object's
+  lifetime; replacing a section is not one atomic transaction.
 * ``Submodule.rename()`` is removed. Moving a submodule preserves its logical name,
   matching Git. Normal removal retains Git's recoverable submodule metadata.
   Re-adding with ``no_checkout=True`` can reuse that metadata without changing refs;
   incompatible URLs, branches, and clone-only options are rejected before mutation.
   Fetch/pull results are derived from command output rather than ``FETCH_HEAD``
-  file parsing. Revision strings follow Git's native revision grammar.
+  file parsing. Revision strings follow Git's native revision grammar. Root trees
+  such as ``Repo.rev_parse("HEAD:")`` have an empty path and can be iterated.
+  Missing paths within a valid tree revision raise ``Tree.join()``'s ``KeyError``
+  with its missing-component message.
 
 * ``IndexFile.entries`` returns an immutable snapshot keyed by ``(path, stage)``
   for compatibility with existing readers. Each access queries the current
@@ -166,8 +159,8 @@ API changes
 * 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.
+  remains readable. ``Actor.from_string()`` and ``parse_actor_and_date()`` provide
+  identity parsing.
 * ``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
@@ -182,9 +175,10 @@ API changes
   ``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
+  ``GitObjectTypeString``). Top-level typing exports other than explicit
+  ``Union`` and ``Optional`` imports are removed, along with private module
+  aliases; 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. ``Repo``
   still accepts ``expand_vars=False`` for callers that explicitly select literal
@@ -1145,10 +1139,6 @@ Please note that due to breaking changes, we have to increase the major version.
 * CRITICAL: fixed incorrect `Commit` object serialization when authored or commit date had timezones which were not
   divisiblej by 3600 seconds. This would happen if the timezone was something like `+0530` for instance.
 * A list of all additional fixes can be found `on GitHub <https://github.com/gitpython-developers/GitPython/issues?q=milestone%3A%22v1.0.2+-+Fixes%22+is%3Aclosed>`__
-* Historical correction: ``Tree.cache`` was announced as removed, but the interface
-  remained available. Its current behavior and limitations are documented in
-  :class:`~git.objects.tree.TreeModifier`. Prefer ``IndexFile.write_tree()`` when
-  building trees from the staging area.
 
 1.0.1 - Fixes
 =============

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 is removed.
+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. ``GitDB`` is an alias for ``GitCmdObjectDB``; the pure-Python storage implementation is unavailable.
 
 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.
 

doc/source/intro.rst

@@ -548,9 +548,10 @@ resolves abbreviated object IDs through persistent ``git cat-file`` processes::
     # Equivalent explicit selection:
     repo = Repo("path/to/repo", odbt=GitCmdObjectDB)
 
-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.
+Only ``GitCmdObjectDB`` and subclasses can be selected through ``odbt``.
+``GitDB`` is an alias for ``GitCmdObjectDB``; passing ``odbt=GitDB`` selects the
+same backend. The pure-Python storage implementation is unavailable. The
+``gitdb`` package provides shared types and utilities.
 
 Git Command Debugging and Customization
 ***************************************

doc/source/tutorial.rst

@@ -71,8 +71,8 @@ Contains Python files for each fuzz test.
 **Things to Know**:
 
 - Each fuzz test targets a specific part of GitPython's functionality.
-- Repository and object targets exercise Git-backed workflows. Removed Python index/tree binary parsers are no longer
-  fuzz targets; malformed configuration and object IDs can now be rejected by Git or by Python input validation.
+- Repository and object targets exercise Git-backed workflows. Git or Python input validation may reject malformed
+  configuration and object IDs.
 - Test files adhere to the naming convention: `fuzz_<API Under Test>.py`, where `<API Under Test>` indicates the
   functionality targeted by the test.
 - Any functionality that involves performing operations on input data is a possible candidate for fuzz testing, but

fuzzing/README.md

@@ -109,6 +109,5 @@ def partial_to_complete_sha_hex(self, partial_hexsha: str) -> bytes:
             raise BadObject(partial_hexsha) from exc
 
 
-# Preserve the public object-backend selector used by downstream applications.
-# Storage remains owned by Git/Gix; this does not restore gitdb's Python backend.
+# Keep the public backend selector using the same Git/Gix-managed storage.
 GitDB = GitCmdObjectDB

git/db.py

@@ -57,10 +57,9 @@ def cmp(a: str, b: str) -> int:
 class TreeModifier:
     """Edit the entries cached by one :class:`Tree` instance.
 
-    This interface is supported; it is not deprecated. Changes affect only that
-    instance's in-memory entries. They do not update its object ID, the stored tree,
-    parent trees, the index, or any commit. Call :meth:`set_done` to restore entry
-    order for iteration after editing.
+    Changes affect only that instance's in-memory entries. They do not update its
+    object ID, the stored tree, parent trees, the index, or any commit. Call
+    :meth:`set_done` to restore entry order for iteration after editing.
 
     Tree serialization delegates construction and ordering to Git or the supported
     Gix backend. Prefer :class:`~git.index.base.IndexFile` and

git/objects/tree.py

@@ -266,7 +266,8 @@ def __init__(
             Object DataBase type - a type which is constructed by providing the
             directory containing the database objects, i.e. ``.git/objects``. It will be
             used to access all object data. Only :class:`~git.db.GitCmdObjectDB`
-            and its subclasses are supported.
+            and its subclasses are supported. ``GitDB`` is an alias for
+            ``GitCmdObjectDB``.
 
         :param search_parent_directories:
             If ``True``, all parent directories will be searched for a valid repo as
@@ -276,9 +277,8 @@ def __init__(
             GitPython, which is considered a bug though.
 
         :param expand_vars:
-            The legacy ``False`` option remains accepted to select literal paths.
-            ``True`` is unsupported; expand environment variables explicitly
-            before opening a repository. Initial ``~`` expansion remains enabled.
+            Only ``False`` is supported. Expand environment variables explicitly
+            before opening a repository. Initial ``~`` expansion is enabled.
 
         :raise git.exc.InvalidGitRepositoryError:
 
@@ -1602,7 +1602,8 @@ def init(
             Object DataBase type - a type which is constructed by providing the
             directory containing the database objects, i.e. ``.git/objects``. It will be
             used to access all object data. Only :class:`~git.db.GitCmdObjectDB`
-            and its subclasses are supported.
+            and its subclasses are supported. ``GitDB`` is an alias for
+            ``GitCmdObjectDB``.
 
         :param allow_unsafe_options:
             Allow unsafe options to be used, such as ``--template`` and
@@ -1786,8 +1787,8 @@ def clone(
         :param kwargs:
             * ``odbt`` = ObjectDatabase Type, allowing to determine the object database
               implementation used by the returned :class:`Repo` instance. The
-              backend must be ``GitCmdObjectDB`` or its subclass; use the default
-              :class:`~git.db.GitCmdObjectDB` instead.
+              backend must be :class:`~git.db.GitCmdObjectDB` or its subclass.
+              ``GitDB`` is an alias for ``GitCmdObjectDB``.
             * All remaining keyword arguments are given to the :manpage:`git-clone(1)`
               command.