docs(repo): demonstrate closing repositories before deletion (#2101)

Reading `repo.head.commit` can open persistent object readers or retain a
native repository handle. Deleting the repository while its handles remain
open is not a supported sequence on Windows. Git's read-only object files
can independently prevent plain `shutil.rmtree()` from removing a clone.

`Repo.close()` and its context-manager support already release the retained
handle and terminate persistent Git readers synchronously. Document that
contract in the API reference, tutorial and README, replacing the old advice
to invoke destructors manually. Demonstrate closing the repository first,
then using the existing strict `git.util.rmtree()` helper for read-only files.
All instances and separately opened readers must be closed by their owners.

Add a packed-repository fixture and a tutorial regression that reads HEAD
and blob data, verifies reader processes have exited and caches are released,
and removes the directory without suppressing deletion errors. The test
passes with both CLI and Gix backends on macOS with Git 2.54.0. Sphinx's
strict HTML build, Ruff and ShellCheck pass. Windows execution is left to CI;
no automatic cleanup of a still-live repository is introduced.

Author: codex

README.md

@@ -161,8 +161,12 @@ GitPython is not suited for long-running processes (like daemons) as it tends to
 leak system resources. It was written in a time where destructors (as implemented
 in the `__del__` method) still ran deterministically.
 
-In case you still want to use it in such a context, you will want to search the
-codebase for `__del__` implementations and call these yourself when you see fit.
+Use `Repo` as a context manager (`with Repo(path) as repo:`), or call
+`repo.close()` explicitly when finished, to release its native repository handle
+and persistent Git object readers. Close every repository instance and any
+separately opened readers before removing its directory. On Windows,
+`git.util.rmtree(path)` also handles Git's read-only files, which plain
+`shutil.rmtree()` may be unable to remove even after handles are closed.
 
 Another way assure proper cleanup of resources is to factor out GitPython into a
 separate process which can be dropped periodically.

doc/source/tutorial.rst

@@ -63,6 +63,32 @@ Archive the repository contents to a tar file.
     :start-after: # [6-test_init_repo_object]
     :end-before: # ![6-test_init_repo_object]
 
+Closing a repository
+====================
+
+Use a :class:`~git.repo.base.Repo` context manager, or call
+:meth:`~git.repo.base.Repo.close` explicitly when finished. Exiting the context
+releases its native handle and persistent Git object readers, including when an
+exception is raised.
+
+.. literalinclude:: ../../test/test_docs.py
+    :language: python
+    :dedent: 8
+    :start-after: # [close-repo-context]
+    :end-before: # ![close-repo-context]
+
+Close every repository instance and any separately opened readers before deleting
+the directory. Windows prevents deletion while files remain open; Git's read-only
+object files can also make plain ``shutil.rmtree()`` fail. The existing
+:func:`git.util.rmtree` helper handles those read-only files while still reporting
+deletion failures:
+
+.. literalinclude:: ../../test/test_docs.py
+    :language: python
+    :dedent: 8
+    :start-after: # [remove-repo-directory]
+    :end-before: # ![remove-repo-directory]
+
 Advanced Repo Usage
 ===================
 

git/repo/base.py

@@ -535,6 +535,13 @@ def __del__(self) -> None:
             pass
 
     def close(self) -> None:
+        """Release native repository state and persistent Git object readers.
+
+        Use ``with Repo(path) as repo:`` to close automatically, including on errors.
+        Close every repository instance and any separately opened readers before
+        removing its directory, especially on Windows where open handles prevent
+        deletion. :func:`git.util.rmtree` also handles Git's read-only files.
+        """
         self._gix_repository = self._gix_state = None
         if self.git:
             self.git.clear_cache()

test/test_docs.py

@@ -12,6 +12,29 @@
 from test.lib.fixtures import writable_fixture
 
 
+def test_repo_context_releases_resources_before_removal():
+    with writable_fixture("repo-close.sh") as temporary:
+        path = temporary.path() / "repo"
+        # [close-repo-context]
+        from git import Repo
+
+        with Repo(path) as repo:
+            print(repo.head.commit.hexsha)
+            # ![close-repo-context]
+            assert repo.head.commit.tree["file"].data_stream.read() == b"contents\n"
+            processes = [reader.proc for reader in (repo.git.cat_file_header, repo.git.cat_file_all) if reader]
+
+        assert repo._gix_repository is None
+        assert repo.git.cat_file_header is repo.git.cat_file_all is None
+        assert all(process.poll() is not None for process in processes)
+        # [remove-repo-directory]
+        from git.util import rmtree
+
+        rmtree(path)
+        # ![remove-repo-directory]
+        assert not path.exists()
+
+
 class Tutorials(TestBase):
     def tearDown(self):
         gc.collect()

tests/fixtures/repo-close.sh

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