docs(tree): clarify supported cache editing behavior (#1771)

`Tree.cache` and `TreeModifier` were announced as removed in an old
changelog, but remain exported and supported. Their documentation also
suggested sorting alone would make edits persistent, leaving their status
and practical limits unclear.

Document that cache edits affect one instance and do not update its object
ID, stored tree, parents, index, or commits. Correct the historical removal
claim and recommend `IndexFile.write_tree()` for staged path changes.
Serialization already delegates construction to Git or Gix; no deprecation
or replacement implementation is needed. Git's `Documentation/git-mktree.adoc`
confirms that `mktree` normalizes entry order without pre-sorted input.

Add a regression covering local subtree edits, serialization into a new
object, and unchanged parent references. The focused tree tests passed
with both CLI and Gix backends (3 tests each), using Git 2.54.0 and
GixPython 0.3.0. The HTML build rendered the updated documentation; its
strict check reported one existing field-list warning in
`git.objects.submodule.util.is_relative_url`.

Author: codex

doc/source/changes.rst

@@ -51,6 +51,10 @@ Git executable and safety
 API changes
 -----------
 
+* ``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.
 * ``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
@@ -1135,7 +1139,10 @@ 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>`__
-* CRITICAL: `Tree.cache` was removed without replacement. It is technically impossible to change individual trees and expect their serialization results to be consistent with what *git* expects. Instead, use the `IndexFile` facilities to adjust the content of the staging area, and write it out to the respective tree objects using `IndexFile.write_tree()` instead.
+* 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
 =============

git/objects/tree.py

@@ -55,12 +55,17 @@ def cmp(a: str, b: str) -> int:
 
 
 class TreeModifier:
-    """A utility class providing methods to alter the underlying cache in a list-like
-    fashion.
+    """Edit the entries cached by one :class:`Tree` instance.
 
-    Once all adjustments are complete, the :attr:`_cache`, which really is a reference
-    to the cache of a tree, will be sorted. This ensures it will be in a serializable
-    state.
+    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.
+
+    Tree serialization delegates construction and ordering to Git or the supported
+    Gix backend. Prefer :class:`~git.index.base.IndexFile` and
+    :meth:`~git.index.base.IndexFile.write_tree` when building a new tree from staged
+    paths, especially when changes must propagate through nested trees.
     """
 
     __slots__ = ("_cache",)
@@ -303,10 +308,10 @@ def blobs(self) -> List[Blob]:
     def cache(self) -> TreeModifier:
         """
         :return:
-            An object allowing modification of the internal cache. This can be used to
-            change the tree's contents. When done, make sure you call
-            :meth:`~TreeModifier.set_done` on the tree modifier, or serialization
-            behaviour will be incorrect.
+            A supported editor for this instance's cached entries. Call
+            :meth:`~TreeModifier.set_done` after editing to restore iteration order.
+            Editing does not change this tree's object ID or persist changes to its
+            stored object, parents, or commits.
 
         :note:
             See :class:`TreeModifier` for more information on how to alter the cache.

test/test_tree.py

@@ -15,11 +15,32 @@
 from git.objects import Blob, Tree
 from git.objects.tree import TreeModifier
 from test.lib import TestBase, with_rw_repo
-from test.lib.fixtures import read_only_fixture
+from test.lib.fixtures import fixture_repo, read_only_fixture
 
 from .lib.helper import PathLikeMock
 
 
+def test_tree_cache_edits_do_not_update_object_ids_or_parents():
+    with fixture_repo("tree-cache.sh", write=True) as repo:
+        root = repo.head.commit.tree
+        subtree = root["sub"]
+        original_oid = subtree.hexsha
+        del subtree.cache["file"]
+        subtree.cache.set_done()
+        assert not list(subtree)
+        assert subtree.hexsha == original_oid
+        assert root["sub"].hexsha == original_oid
+        assert [item.name for item in repo.head.commit.tree["sub"]] == ["file"]
+
+        data = BytesIO()
+        subtree._serialize(data)
+        data.seek(0)
+        stored = repo.odb.store(IStream("tree", len(data.getvalue()), data))
+        assert stored.binsha != subtree.binsha
+        assert not list(Tree(repo, stored.binsha, path=""))
+        assert repo.head.commit.tree["sub"].hexsha == original_oid
+
+
 @ddt.ddt
 class TestTree(TestBase):
     @with_rw_repo("HEAD")

tests/fixtures/tree-cache.sh

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+set -eu
+git init --initial-branch=main repo
+mkdir repo/sub
+printf 'original\n' >repo/sub/file
+git -C repo add sub/file
+git -C repo commit -m initial