Repository.walk() keeps .pack files open until Repository.free() or gc.collect()

[lpsozi]

Environment:

• Windows 11
• Python 3.12 (reproducible with 3.14)
• pygit2 1.19.2
• libgit2 1.9.2

Minimal example:

RepoWalkerFileHandles.py

Required changes to run: Change repo_path to any directory with a git repository.

Explanation:

Opening a repository with pygit2.Repository and using a commit walker with repo.walk seems to keep the file handles over some .pack files in the repository. When I attempt to delete the repository afterwards with shutil.rmtree, I get an WinError 32 stating that the .pack files are blocked by another process. These file handles are not removed when deleting the pygit2.Repository object or the walker object. They can only be removed by explicitly calling Repository.free() or gc.collect().

Question:

Is this expected behavior, or should pygit2.Repository release these handles automatically when the Repository object is destroyed?

[SirHegel]

del repo is not the same as running the Repository deallocator in this reproducer.

In pygit2 1.19.2, Repository._common_init() installs branches, references, remotes, and submodules, and each collection keeps a reference back to the repository. Those references form cycles. Therefore, after deleting the explicit walker and branch, deleting the local repo name may leave the repository alive until cyclic GC runs. That is why gc.collect() closes the handles.

When the repository is actually deallocated, pygit2 calls git_repository_free(), so the destructor does perform cleanup. The walker also has a real deallocator: walk() retains the repository, and Walker_dealloc releases it and calls git_revwalk_free().

For deterministic cleanup before shutil.rmtree() on Windows, Repository.free() is the appropriate API. It was added specifically to release Git database handles without waiting for repository deallocation. Release every walker and other pygit2 object derived from the repository first, then make free() the final repository operation:

repo = pygit2.Repository(repo_path)
branch = walker = commit = None

try:
    branch = repo.branches["main"]
    walker = repo.walk(branch.target)
    for commit in walker:
        # Process the commit without retaining it past cleanup.
        pass
finally:
    # Also clear containers that retain commits or other pygit2 objects.
    commit = None
    walker = None
    branch = None
    repo.free()
    repo = None

shutil.rmtree(repo_path, onexc=remove_readonly)

The ordering matters: a libgit2 revwalker owns an additional ODB reference, so calling repo.free() while a walker remains alive is not guaranteed to close the pack backend. Also avoid using the repository again after free() and before deletion, because a later operation may reopen resources.