Add files using upload-large-folder tool

.gitattributes

@@ -46,3 +46,21 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 .venv/lib/python3.11/site-packages/nvidia/cuda_cupti/lib/libpcsamplingutil.so filter=lfs diff=lfs merge=lfs -text
 .venv/lib/python3.11/site-packages/nvidia/cublas/lib/libnvblas.so.12 filter=lfs diff=lfs merge=lfs -text
 .venv/lib/python3.11/site-packages/nvidia/cuda_nvrtc/lib/libnvrtc-builtins.so.12.8 filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/google/cloud/storage/__pycache__/blob.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/dill/__pycache__/_dill.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
+.venv/bin/ruff filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/google/cloud/storage/__pycache__/bucket.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/nvidia/nvshmem/lib/libnvshmem_device.a filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/nvidia/cuda_nvrtc/lib/libnvrtc-builtins.alt.so.12.8 filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/google/_upb/_message.abi3.so filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/nvidia/cudnn/lib/libcudnn.so.9 filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/msgpack/_cmsgpack.cpython-311-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/nvidia/cufft/lib/libcufftw.so.11 filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/nvidia/cuda_cupti/lib/libcheckpoint.so filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/nvidia/cudnn/lib/libcudnn_cnn.so.9 filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/nvidia/nvjitlink/lib/libnvJitLink.so.12 filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/nvidia/cuda_nvrtc/lib/libnvrtc.alt.so.12 filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/nvidia/cudnn/lib/libcudnn_engines_runtime_compiled.so.9 filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/nvidia/cuda_nvrtc/lib/libnvrtc.so.12 filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/huggingface_hub/__pycache__/hf_api.cpython-311.pyc filter=lfs diff=lfs merge=lfs -text
+.venv/lib/python3.11/site-packages/nvidia/cudnn/lib/libcudnn_graph.so.9 filter=lfs diff=lfs merge=lfs -text

.venv/bin/ruff

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1497dfe275c08dfa91e07e488b28dd6d0036db5d3ef82c8a26ed385049c25943
+size 35528032

.venv/lib/python3.11/site-packages/dill/__pycache__/_dill.cpython-311.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f88f85aa4bca2d752b3be88cf4cc5fed1e7c6be0f77d9d77dd56c603c97733aa
+size 110272

.venv/lib/python3.11/site-packages/git/__init__.py

@@ -0,0 +1,300 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+# @PydevCodeAnalysisIgnore
+
+__all__ = [
+    "Actor",
+    "AmbiguousObjectName",
+    "BadName",
+    "BadObject",
+    "BadObjectType",
+    "BaseIndexEntry",
+    "Blob",
+    "BlobFilter",
+    "BlockingLockFile",
+    "CacheError",
+    "CheckoutError",
+    "CommandError",
+    "Commit",
+    "Diff",
+    "DiffConstants",
+    "DiffIndex",
+    "Diffable",
+    "FetchInfo",
+    "Git",
+    "GitCmdObjectDB",
+    "GitCommandError",
+    "GitCommandNotFound",
+    "GitConfigParser",
+    "GitDB",
+    "GitError",
+    "HEAD",
+    "Head",
+    "HookExecutionError",
+    "INDEX",
+    "IndexEntry",
+    "IndexFile",
+    "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",
+    "RefLog",
+    "RefLogEntry",
+    "Reference",
+    "Remote",
+    "RemoteProgress",
+    "RemoteReference",
+    "Repo",
+    "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",
+    "UnsupportedOperation",
+    "UpdateProgress",
+    "WorkTreeRepositoryUnsupported",
+    "refresh",
+    "remove_password_if_present",
+    "rmtree",
+    "safe_decode",
+    "to_hex_sha",
+]
+
+__version__ = '3.1.45'
+
+from typing import Any, List, Optional, Sequence, TYPE_CHECKING, Tuple, Union
+
+if TYPE_CHECKING:
+    from types import ModuleType
+
+import warnings
+
+from gitdb.util import to_hex_sha
+
+from git.exc import (
+    AmbiguousObjectName,
+    BadName,
+    BadObject,
+    BadObjectType,
+    CacheError,
+    CheckoutError,
+    CommandError,
+    GitCommandError,
+    GitCommandNotFound,
+    GitError,
+    HookExecutionError,
+    InvalidDBRoot,
+    InvalidGitRepositoryError,
+    NoSuchPathError,
+    ODBError,
+    ParseError,
+    RepositoryDirtyError,
+    UnmergedEntriesError,
+    UnsafeOptionError,
+    UnsafeProtocolError,
+    UnsupportedOperation,
+    WorkTreeRepositoryUnsupported,
+)
+from git.types import PathLike
+
+try:
+    from git.compat import safe_decode  # @NoMove
+    from git.config import GitConfigParser  # @NoMove
+    from git.objects import (  # @NoMove
+        Blob,
+        Commit,
+        IndexObject,
+        Object,
+        RootModule,
+        RootUpdateProgress,
+        Submodule,
+        TagObject,
+        Tree,
+        TreeModifier,
+        UpdateProgress,
+    )
+    from git.refs import (  # @NoMove
+        HEAD,
+        Head,
+        RefLog,
+        RefLogEntry,
+        Reference,
+        RemoteReference,
+        SymbolicReference,
+        Tag,
+        TagReference,
+    )
+    from git.diff import (  # @NoMove
+        INDEX,
+        NULL_TREE,
+        Diff,
+        DiffConstants,
+        DiffIndex,
+        Diffable,
+    )
+    from git.db import GitCmdObjectDB, GitDB  # @NoMove
+    from git.cmd import Git  # @NoMove
+    from git.repo import Repo  # @NoMove
+    from git.remote import FetchInfo, PushInfo, Remote, RemoteProgress  # @NoMove
+    from git.index import (  # @NoMove
+        BaseIndexEntry,
+        BlobFilter,
+        CheckoutError,
+        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,
+        BlockingLockFile,
+        LockFile,
+        Stats,
+        remove_password_if_present,
+        rmtree,
+    )
+except GitError as _exc:
+    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:
+    """Convenience method for setting the git executable path.
+
+    :param path:
+        Optional path to the Git executable. If not absolute, it is resolved
+        immediately, relative to the current directory.
+
+    :note:
+        The `path` parameter is usually omitted and cannot be used to specify a custom
+        command whose location is looked up in a path search on each call. See
+        :meth:`Git.refresh <git.cmd.Git.refresh>` for details on how to achieve this.
+
+    :note:
+        This calls :meth:`Git.refresh <git.cmd.Git.refresh>` and sets other global
+        configuration according to the effect of doing so. As such, this function should
+        usually be used instead of using :meth:`Git.refresh <git.cmd.Git.refresh>` or
+        :meth:`FetchInfo.refresh <git.remote.FetchInfo.refresh>` directly.
+
+    :note:
+        This function is called automatically, with no arguments, at import time.
+    """
+    global GIT_OK
+    GIT_OK = False
+
+    if not Git.refresh(path=path):
+        return
+    if not FetchInfo.refresh():  # noqa: F405
+        return  # type: ignore[unreachable]
+
+    GIT_OK = True
+
+
+try:
+    refresh()
+except Exception as _exc:
+    raise ImportError("Failed to initialize: {0}".format(_exc)) from _exc
+
+# } END initialize git executable path

.venv/lib/python3.11/site-packages/git/cmd.py

@@ -0,0 +1,1741 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+from __future__ import annotations
+
+__all__ = ["GitMeta", "Git"]
+
+import contextlib
+import io
+import itertools
+import logging
+import os
+import re
+import signal
+import subprocess
+from subprocess import DEVNULL, PIPE, Popen
+import sys
+from textwrap import dedent
+import threading
+import warnings
+
+from git.compat import defenc, force_bytes, safe_decode
+from git.exc import (
+    CommandError,
+    GitCommandError,
+    GitCommandNotFound,
+    UnsafeOptionError,
+    UnsafeProtocolError,
+)
+from git.util import (
+    cygpath,
+    expand_path,
+    is_cygwin_git,
+    patch_env,
+    remove_password_if_present,
+    stream_copy,
+)
+
+# typing ---------------------------------------------------------------------------
+
+from typing import (
+    Any,
+    AnyStr,
+    BinaryIO,
+    Callable,
+    Dict,
+    IO,
+    Iterator,
+    List,
+    Mapping,
+    Optional,
+    Sequence,
+    TYPE_CHECKING,
+    TextIO,
+    Tuple,
+    Union,
+    cast,
+    overload,
+)
+
+if sys.version_info >= (3, 10):
+    from typing import TypeAlias
+else:
+    from typing_extensions import TypeAlias
+
+from git.types import Literal, PathLike, TBD
+
+if TYPE_CHECKING:
+    from git.diff import DiffIndex
+    from git.repo.base import Repo
+
+# ---------------------------------------------------------------------------------
+
+execute_kwargs = {
+    "istream",
+    "with_extended_output",
+    "with_exceptions",
+    "as_process",
+    "output_stream",
+    "stdout_as_string",
+    "kill_after_timeout",
+    "with_stdout",
+    "universal_newlines",
+    "shell",
+    "env",
+    "max_chunk_size",
+    "strip_newline_in_stdout",
+}
+
+_logger = logging.getLogger(__name__)
+
+
+# ==============================================================================
+## @name Utilities
+# ------------------------------------------------------------------------------
+# Documentation
+## @{
+
+
+def handle_process_output(
+    process: "Git.AutoInterrupt" | Popen,
+    stdout_handler: Union[
+        None,
+        Callable[[AnyStr], None],
+        Callable[[List[AnyStr]], None],
+        Callable[[bytes, "Repo", "DiffIndex"], None],
+    ],
+    stderr_handler: Union[None, Callable[[AnyStr], None], Callable[[List[AnyStr]], None]],
+    finalizer: Union[None, Callable[[Union[Popen, "Git.AutoInterrupt"]], None]] = None,
+    decode_streams: bool = True,
+    kill_after_timeout: Union[None, float] = None,
+) -> None:
+    R"""Register for notifications to learn that process output is ready to read, and
+    dispatch lines to the respective line handlers.
+
+    This function returns once the finalizer returns.
+
+    :param process:
+        :class:`subprocess.Popen` instance.
+
+    :param stdout_handler:
+        f(stdout_line_string), or ``None``.
+
+    :param stderr_handler:
+        f(stderr_line_string), or ``None``.
+
+    :param finalizer:
+        f(proc) - wait for proc to finish.
+
+    :param decode_streams:
+        Assume stdout/stderr streams are binary and decode them before pushing their
+        contents to handlers.
+
+        This defaults to ``True``. Set it to ``False`` if:
+
+        - ``universal_newlines == True``, as then streams are in text mode, or
+        - decoding must happen later, such as for :class:`~git.diff.Diff`\s.
+
+    :param kill_after_timeout:
+        :class:`float` or ``None``, Default = ``None``
+
+        To specify a timeout in seconds for the git command, after which the process
+        should be killed.
+    """
+
+    # Use 2 "pump" threads and wait for both to finish.
+    def pump_stream(
+        cmdline: List[str],
+        name: str,
+        stream: Union[BinaryIO, TextIO],
+        is_decode: bool,
+        handler: Union[None, Callable[[Union[bytes, str]], None]],
+    ) -> None:
+        try:
+            for line in stream:
+                if handler:
+                    if is_decode:
+                        assert isinstance(line, bytes)
+                        line_str = line.decode(defenc)
+                        handler(line_str)
+                    else:
+                        handler(line)
+
+        except Exception as ex:
+            _logger.error(f"Pumping {name!r} of cmd({remove_password_if_present(cmdline)}) failed due to: {ex!r}")
+            if "I/O operation on closed file" not in str(ex):
+                # Only reraise if the error was not due to the stream closing.
+                raise CommandError([f"<{name}-pump>"] + remove_password_if_present(cmdline), ex) from ex
+        finally:
+            stream.close()
+
+    if hasattr(process, "proc"):
+        process = cast("Git.AutoInterrupt", process)
+        cmdline: str | Tuple[str, ...] | List[str] = getattr(process.proc, "args", "")
+        p_stdout = process.proc.stdout if process.proc else None
+        p_stderr = process.proc.stderr if process.proc else None
+    else:
+        process = cast(Popen, process)  # type: ignore[redundant-cast]
+        cmdline = getattr(process, "args", "")
+        p_stdout = process.stdout
+        p_stderr = process.stderr
+
+    if not isinstance(cmdline, (tuple, list)):
+        cmdline = cmdline.split()
+
+    pumps: List[Tuple[str, IO, Callable[..., None] | None]] = []
+    if p_stdout:
+        pumps.append(("stdout", p_stdout, stdout_handler))
+    if p_stderr:
+        pumps.append(("stderr", p_stderr, stderr_handler))
+
+    threads: List[threading.Thread] = []
+
+    for name, stream, handler in pumps:
+        t = threading.Thread(target=pump_stream, args=(cmdline, name, stream, decode_streams, handler))
+        t.daemon = True
+        t.start()
+        threads.append(t)
+
+    # FIXME: Why join? Will block if stdin needs feeding...
+    for t in threads:
+        t.join(timeout=kill_after_timeout)
+        if t.is_alive():
+            if isinstance(process, Git.AutoInterrupt):
+                process._terminate()
+            else:  # Don't want to deal with the other case.
+                raise RuntimeError(
+                    "Thread join() timed out in cmd.handle_process_output()."
+                    f" kill_after_timeout={kill_after_timeout} seconds"
+                )
+            if stderr_handler:
+                error_str: Union[str, bytes] = (
+                    f"error: process killed because it timed out. kill_after_timeout={kill_after_timeout} seconds"
+                )
+                if not decode_streams and isinstance(p_stderr, BinaryIO):
+                    # Assume stderr_handler needs binary input.
+                    error_str = cast(str, error_str)
+                    error_str = error_str.encode()
+                # We ignore typing on the next line because mypy does not like the way
+                # we inferred that stderr takes str or bytes.
+                stderr_handler(error_str)  # type: ignore[arg-type]
+
+    if finalizer:
+        finalizer(process)
+
+
+safer_popen: Callable[..., Popen]
+
+if sys.platform == "win32":
+
+    def _safer_popen_windows(
+        command: Union[str, Sequence[Any]],
+        *,
+        shell: bool = False,
+        env: Optional[Mapping[str, str]] = None,
+        **kwargs: Any,
+    ) -> Popen:
+        """Call :class:`subprocess.Popen` on Windows but don't include a CWD in the
+        search.
+
+        This avoids an untrusted search path condition where a file like ``git.exe`` in
+        a malicious repository would be run when GitPython operates on the repository.
+        The process using GitPython may have an untrusted repository's working tree as
+        its current working directory. Some operations may temporarily change to that
+        directory before running a subprocess. In addition, while by default GitPython
+        does not run external commands with a shell, it can be made to do so, in which
+        case the CWD of the subprocess, which GitPython usually sets to a repository
+        working tree, can itself be searched automatically by the shell. This wrapper
+        covers all those cases.
+
+        :note:
+            This currently works by setting the
+            :envvar:`NoDefaultCurrentDirectoryInExePath` environment variable during
+            subprocess creation. It also takes care of passing Windows-specific process
+            creation flags, but that is unrelated to path search.
+
+        :note:
+            The current implementation contains a race condition on :attr:`os.environ`.
+            GitPython isn't thread-safe, but a program using it on one thread should
+            ideally be able to mutate :attr:`os.environ` on another, without
+            unpredictable results. See comments in:
+            https://github.com/gitpython-developers/GitPython/pull/1650
+        """
+        # CREATE_NEW_PROCESS_GROUP is needed for some ways of killing it afterwards.
+        # https://docs.python.org/3/library/subprocess.html#subprocess.Popen.send_signal
+        # https://docs.python.org/3/library/subprocess.html#subprocess.CREATE_NEW_PROCESS_GROUP
+        creationflags = subprocess.CREATE_NO_WINDOW | subprocess.CREATE_NEW_PROCESS_GROUP
+
+        # When using a shell, the shell is the direct subprocess, so the variable must
+        # be set in its environment, to affect its search behavior.
+        if shell:
+            # The original may be immutable, or the caller may reuse it. Mutate a copy.
+            env = {} if env is None else dict(env)
+            env["NoDefaultCurrentDirectoryInExePath"] = "1"  # The "1" can be any value.
+
+        # When not using a shell, the current process does the search in a
+        # CreateProcessW API call, so the variable must be set in our environment. With
+        # a shell, that's unnecessary if https://github.com/python/cpython/issues/101283
+        # is patched. In Python versions where it is unpatched, in the rare case the
+        # ComSpec environment variable is unset, the search for the shell itself is
+        # unsafe. Setting NoDefaultCurrentDirectoryInExePath in all cases, as done here,
+        # is simpler and protects against that. (As above, the "1" can be any value.)
+        with patch_env("NoDefaultCurrentDirectoryInExePath", "1"):
+            return Popen(
+                command,
+                shell=shell,
+                env=env,
+                creationflags=creationflags,
+                **kwargs,
+            )
+
+    safer_popen = _safer_popen_windows
+else:
+    safer_popen = Popen
+
+
+def dashify(string: str) -> str:
+    return string.replace("_", "-")
+
+
+def slots_to_dict(self: "Git", exclude: Sequence[str] = ()) -> Dict[str, Any]:
+    return {s: getattr(self, s) for s in self.__slots__ if s not in exclude}
+
+
+def dict_to_slots_and__excluded_are_none(self: object, d: Mapping[str, Any], excluded: Sequence[str] = ()) -> None:
+    for k, v in d.items():
+        setattr(self, k, v)
+    for k in excluded:
+        setattr(self, k, None)
+
+
+## -- End Utilities -- @}
+
+
+class _AutoInterrupt:
+    """Process wrapper that terminates the wrapped process on finalization.
+
+    This kills/interrupts the stored process instance once this instance goes out of
+    scope. It is used to prevent processes piling up in case iterators stop reading.
+
+    All attributes are wired through to the contained process object.
+
+    The wait method is overridden to perform automatic status code checking and possibly
+    raise.
+    """
+
+    __slots__ = ("proc", "args", "status")
+
+    # If this is non-zero it will override any status code during _terminate, used
+    # to prevent race conditions in testing.
+    _status_code_if_terminate: int = 0
+
+    def __init__(self, proc: Union[None, subprocess.Popen], args: Any) -> None:
+        self.proc = proc
+        self.args = args
+        self.status: Union[int, None] = None
+
+    def _terminate(self) -> None:
+        """Terminate the underlying process."""
+        if self.proc is None:
+            return
+
+        proc = self.proc
+        self.proc = None
+        if proc.stdin:
+            proc.stdin.close()
+        if proc.stdout:
+            proc.stdout.close()
+        if proc.stderr:
+            proc.stderr.close()
+        # Did the process finish already so we have a return code?
+        try:
+            if proc.poll() is not None:
+                self.status = self._status_code_if_terminate or proc.poll()
+                return
+        except OSError as ex:
+            _logger.info("Ignored error after process had died: %r", ex)
+
+        # It can be that nothing really exists anymore...
+        if os is None or getattr(os, "kill", None) is None:
+            return
+
+        # Try to kill it.
+        try:
+            proc.terminate()
+            status = proc.wait()  # Ensure the process goes away.
+
+            self.status = self._status_code_if_terminate or status
+        except OSError as ex:
+            _logger.info("Ignored error after process had died: %r", ex)
+        # END exception handling
+
+    def __del__(self) -> None:
+        self._terminate()
+
+    def __getattr__(self, attr: str) -> Any:
+        return getattr(self.proc, attr)
+
+    # TODO: Bad choice to mimic `proc.wait()` but with different args.
+    def wait(self, stderr: Union[None, str, bytes] = b"") -> int:
+        """Wait for the process and return its status code.
+
+        :param stderr:
+            Previously read value of stderr, in case stderr is already closed.
+
+        :warn:
+            May deadlock if output or error pipes are used and not handled separately.
+
+        :raise git.exc.GitCommandError:
+            If the return status is not 0.
+        """
+        if stderr is None:
+            stderr_b = b""
+        stderr_b = force_bytes(data=stderr, encoding="utf-8")
+        status: Union[int, None]
+        if self.proc is not None:
+            status = self.proc.wait()
+            p_stderr = self.proc.stderr
+        else:  # Assume the underlying proc was killed earlier or never existed.
+            status = self.status
+            p_stderr = None
+
+        def read_all_from_possibly_closed_stream(stream: Union[IO[bytes], None]) -> bytes:
+            if stream:
+                try:
+                    return stderr_b + force_bytes(stream.read())
+                except (OSError, ValueError):
+                    return stderr_b or b""
+            else:
+                return stderr_b or b""
+
+        # END status handling
+
+        if status != 0:
+            errstr = read_all_from_possibly_closed_stream(p_stderr)
+            _logger.debug("AutoInterrupt wait stderr: %r" % (errstr,))
+            raise GitCommandError(remove_password_if_present(self.args), status, errstr)
+        return status
+
+
+_AutoInterrupt.__name__ = "AutoInterrupt"
+_AutoInterrupt.__qualname__ = "Git.AutoInterrupt"
+
+
+class _CatFileContentStream:
+    """Object representing a sized read-only stream returning the contents of
+    an object.
+
+    This behaves like a stream, but counts the data read and simulates an empty stream
+    once our sized content region is empty.
+
+    If not all data are read to the end of the object's lifetime, we read the rest to
+    ensure the underlying stream continues to work.
+    """
+
+    __slots__ = ("_stream", "_nbr", "_size")
+
+    def __init__(self, size: int, stream: IO[bytes]) -> None:
+        self._stream = stream
+        self._size = size
+        self._nbr = 0  # Number of bytes read.
+
+        # Special case: If the object is empty, has null bytes, get the final
+        # newline right away.
+        if size == 0:
+            stream.read(1)
+        # END handle empty streams
+
+    def read(self, size: int = -1) -> bytes:
+        bytes_left = self._size - self._nbr
+        if bytes_left == 0:
+            return b""
+        if size > -1:
+            # Ensure we don't try to read past our limit.
+            size = min(bytes_left, size)
+        else:
+            # They try to read all, make sure it's not more than what remains.
+            size = bytes_left
+        # END check early depletion
+        data = self._stream.read(size)
+        self._nbr += len(data)
+
+        # Check for depletion, read our final byte to make the stream usable by
+        # others.
+        if self._size - self._nbr == 0:
+            self._stream.read(1)  # final newline
+        # END finish reading
+        return data
+
+    def readline(self, size: int = -1) -> bytes:
+        if self._nbr == self._size:
+            return b""
+
+        # Clamp size to lowest allowed value.
+        bytes_left = self._size - self._nbr
+        if size > -1:
+            size = min(bytes_left, size)
+        else:
+            size = bytes_left
+        # END handle size
+
+        data = self._stream.readline(size)
+        self._nbr += len(data)
+
+        # Handle final byte.
+        if self._size - self._nbr == 0:
+            self._stream.read(1)
+        # END finish reading
+
+        return data
+
+    def readlines(self, size: int = -1) -> List[bytes]:
+        if self._nbr == self._size:
+            return []
+
+        # Leave all additional logic to our readline method, we just check the size.
+        out = []
+        nbr = 0
+        while True:
+            line = self.readline()
+            if not line:
+                break
+            out.append(line)
+            if size > -1:
+                nbr += len(line)
+                if nbr > size:
+                    break
+            # END handle size constraint
+        # END readline loop
+        return out
+
+    # skipcq: PYL-E0301
+    def __iter__(self) -> "Git.CatFileContentStream":
+        return self
+
+    def __next__(self) -> bytes:
+        line = self.readline()
+        if not line:
+            raise StopIteration
+
+        return line
+
+    next = __next__
+
+    def __del__(self) -> None:
+        bytes_left = self._size - self._nbr
+        if bytes_left:
+            # Read and discard - seeking is impossible within a stream.
+            # This includes any terminating newline.
+            self._stream.read(bytes_left + 1)
+        # END handle incomplete read
+
+
+_CatFileContentStream.__name__ = "CatFileContentStream"
+_CatFileContentStream.__qualname__ = "Git.CatFileContentStream"
+
+
+_USE_SHELL_DEFAULT_MESSAGE = (
+    "Git.USE_SHELL is deprecated, because only its default value of False is safe. "
+    "It will be removed in a future release."
+)
+
+_USE_SHELL_DANGER_MESSAGE = (
+    "Setting Git.USE_SHELL to True is unsafe and insecure, as the effect of special "
+    "shell syntax cannot usually be accounted for. This can result in a command "
+    "injection vulnerability and arbitrary code execution. Git.USE_SHELL is deprecated "
+    "and will be removed in a future release."
+)
+
+
+def _warn_use_shell(*, extra_danger: bool) -> None:
+    warnings.warn(
+        _USE_SHELL_DANGER_MESSAGE if extra_danger else _USE_SHELL_DEFAULT_MESSAGE,
+        DeprecationWarning,
+        stacklevel=3,
+    )
+
+
+class _GitMeta(type):
+    """Metaclass for :class:`Git`.
+
+    This helps issue :class:`DeprecationWarning` if :attr:`Git.USE_SHELL` is used.
+    """
+
+    def __getattribute(cls, name: str) -> Any:
+        if name == "USE_SHELL":
+            _warn_use_shell(extra_danger=False)
+        return super().__getattribute__(name)
+
+    def __setattr(cls, name: str, value: Any) -> Any:
+        if name == "USE_SHELL":
+            _warn_use_shell(extra_danger=value)
+        super().__setattr__(name, value)
+
+    if not TYPE_CHECKING:
+        # To preserve static checking for undefined/misspelled attributes while letting
+        # the methods' bodies be type-checked, these are defined as non-special methods,
+        # then bound to special names out of view of static type checkers. (The original
+        # names invoke name mangling (leading "__") to avoid confusion in other scopes.)
+        __getattribute__ = __getattribute
+        __setattr__ = __setattr
+
+
+GitMeta = _GitMeta
+"""Alias of :class:`Git`'s metaclass, whether it is :class:`type` or a custom metaclass.
+
+Whether the :class:`Git` class has the default :class:`type` as its metaclass or uses a
+custom metaclass is not documented and may change at any time. This statically checkable
+metaclass alias is equivalent at runtime to ``type(Git)``. This should almost never be
+used. Code that benefits from it is likely to be remain brittle even if it is used.
+
+In view of the :class:`Git` class's intended use and :class:`Git` objects' dynamic
+callable attributes representing git subcommands, it rarely makes sense to inherit from
+:class:`Git` at all. Using :class:`Git` in multiple inheritance can be especially tricky
+to do correctly. Attempting uses of :class:`Git` where its metaclass is relevant, such
+as when a sibling class has an unrelated metaclass and a shared lower bound metaclass
+might have to be introduced to solve a metaclass conflict, is not recommended.
+
+:note:
+    The correct static type of the :class:`Git` class itself, and any subclasses, is
+    ``Type[Git]``. (This can be written as ``type[Git]`` in Python 3.9 later.)
+
+    :class:`GitMeta` should never be used in any annotation where ``Type[Git]`` is
+    intended or otherwise possible to use. This alias is truly only for very rare and
+    inherently precarious situations where it is necessary to deal with the metaclass
+    explicitly.
+"""
+
+
+class Git(metaclass=_GitMeta):
+    """The Git class manages communication with the Git binary.
+
+    It provides a convenient interface to calling the Git binary, such as in::
+
+     g = Git( git_dir )
+     g.init()                   # calls 'git init' program
+     rval = g.ls_files()        # calls 'git ls-files' program
+
+    Debugging:
+
+    * Set the :envvar:`GIT_PYTHON_TRACE` environment variable to print each invocation
+      of the command to stdout.
+    * Set its value to ``full`` to see details about the returned values.
+    """
+
+    __slots__ = (
+        "_working_dir",
+        "cat_file_all",
+        "cat_file_header",
+        "_version_info",
+        "_version_info_token",
+        "_git_options",
+        "_persistent_git_options",
+        "_environment",
+    )
+
+    _excluded_ = (
+        "cat_file_all",
+        "cat_file_header",
+        "_version_info",
+        "_version_info_token",
+    )
+
+    re_unsafe_protocol = re.compile(r"(.+)::.+")
+
+    def __getstate__(self) -> Dict[str, Any]:
+        return slots_to_dict(self, exclude=self._excluded_)
+
+    def __setstate__(self, d: Dict[str, Any]) -> None:
+        dict_to_slots_and__excluded_are_none(self, d, excluded=self._excluded_)
+
+    # CONFIGURATION
+
+    git_exec_name = "git"
+    """Default git command that should work on Linux, Windows, and other systems."""
+
+    GIT_PYTHON_TRACE = os.environ.get("GIT_PYTHON_TRACE", False)
+    """Enables debugging of GitPython's git commands."""
+
+    USE_SHELL: bool = False
+    """Deprecated. If set to ``True``, a shell will be used when executing git commands.
+
+    Code that uses ``USE_SHELL = True`` or that passes ``shell=True`` to any GitPython
+    functions should be updated to use the default value of ``False`` instead. ``True``
+    is unsafe unless the effect of syntax treated specially by the shell is fully
+    considered and accounted for, which is not possible under most circumstances. As
+    detailed below, it is also no longer needed, even where it had been in the past.
+
+    It is in many if not most cases a command injection vulnerability for an application
+    to set :attr:`USE_SHELL` to ``True``. Any attacker who can cause a specially crafted
+    fragment of text to make its way into any part of any argument to any git command
+    (including paths, branch names, etc.) can cause the shell to read and write
+    arbitrary files and execute arbitrary commands. Innocent input may also accidentally
+    contain special shell syntax, leading to inadvertent malfunctions.
+
+    In addition, how a value of ``True`` interacts with some aspects of GitPython's
+    operation is not precisely specified and may change without warning, even before
+    GitPython 4.0.0 when :attr:`USE_SHELL` may be removed. This includes:
+
+    * Whether or how GitPython automatically customizes the shell environment.
+
+    * Whether, outside of Windows (where :class:`subprocess.Popen` supports lists of
+      separate arguments even when ``shell=True``), this can be used with any GitPython
+      functionality other than direct calls to the :meth:`execute` method.
+
+    * Whether any GitPython feature that runs git commands ever attempts to partially
+      sanitize data a shell may treat specially. Currently this is not done.
+
+    Prior to GitPython 2.0.8, this had a narrow purpose in suppressing console windows
+    in graphical Windows applications. In 2.0.8 and higher, it provides no benefit, as
+    GitPython solves that problem more robustly and safely by using the
+    ``CREATE_NO_WINDOW`` process creation flag on Windows.
+
+    Because Windows path search differs subtly based on whether a shell is used, in rare
+    cases changing this from ``True`` to ``False`` may keep an unusual git "executable",
+    such as a batch file, from being found. To fix this, set the command name or full
+    path in the :envvar:`GIT_PYTHON_GIT_EXECUTABLE` environment variable or pass the
+    full path to :func:`git.refresh` (or invoke the script using a ``.exe`` shim).
+
+    Further reading:
+
+    * :meth:`Git.execute` (on the ``shell`` parameter).
+    * https://github.com/gitpython-developers/GitPython/commit/0d9390866f9ce42870d3116094cd49e0019a970a
+    * https://learn.microsoft.com/en-us/windows/win32/procthread/process-creation-flags
+    * https://github.com/python/cpython/issues/91558#issuecomment-1100942950
+    * https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw
+    """
+
+    _git_exec_env_var = "GIT_PYTHON_GIT_EXECUTABLE"
+    _refresh_env_var = "GIT_PYTHON_REFRESH"
+
+    GIT_PYTHON_GIT_EXECUTABLE = None
+    """Provide the full path to the git executable. Otherwise it assumes git is in the
+    executable search path.
+
+    :note:
+        The git executable is actually found during the refresh step in the top level
+        ``__init__``. It can also be changed by explicitly calling :func:`git.refresh`.
+    """
+
+    _refresh_token = object()  # Since None would match an initial _version_info_token.
+
+    @classmethod
+    def refresh(cls, path: Union[None, PathLike] = None) -> bool:
+        """Update information about the git executable :class:`Git` objects will use.
+
+        Called by the :func:`git.refresh` function in the top level ``__init__``.
+
+        :param path:
+            Optional path to the git executable. If not absolute, it is resolved
+            immediately, relative to the current directory. (See note below.)
+
+        :note:
+            The top-level :func:`git.refresh` should be preferred because it calls this
+            method and may also update other state accordingly.
+
+        :note:
+            There are three different ways to specify the command that refreshing causes
+            to be used for git:
+
+            1. Pass no `path` argument and do not set the
+               :envvar:`GIT_PYTHON_GIT_EXECUTABLE` environment variable. The command
+               name ``git`` is used. It is looked up in a path search by the system, in
+               each command run (roughly similar to how git is found when running
+               ``git`` commands manually). This is usually the desired behavior.
+
+            2. Pass no `path` argument but set the :envvar:`GIT_PYTHON_GIT_EXECUTABLE`
+               environment variable. The command given as the value of that variable is
+               used. This may be a simple command or an arbitrary path. It is looked up
+               in each command run. Setting :envvar:`GIT_PYTHON_GIT_EXECUTABLE` to
+               ``git`` has the same effect as not setting it.
+
+            3. Pass a `path` argument. This path, if not absolute, is immediately
+               resolved, relative to the current directory. This resolution occurs at
+               the time of the refresh. When git commands are run, they are run using
+               that previously resolved path. If a `path` argument is passed, the
+               :envvar:`GIT_PYTHON_GIT_EXECUTABLE` environment variable is not
+               consulted.
+
+        :note:
+            Refreshing always sets the :attr:`Git.GIT_PYTHON_GIT_EXECUTABLE` class
+            attribute, which can be read on the :class:`Git` class or any of its
+            instances to check what command is used to run git. This attribute should
+            not be confused with the related :envvar:`GIT_PYTHON_GIT_EXECUTABLE`
+            environment variable. The class attribute is set no matter how refreshing is
+            performed.
+        """
+        # Discern which path to refresh with.
+        if path is not None:
+            new_git = os.path.expanduser(path)
+            new_git = os.path.abspath(new_git)
+        else:
+            new_git = os.environ.get(cls._git_exec_env_var, cls.git_exec_name)
+
+        # Keep track of the old and new git executable path.
+        old_git = cls.GIT_PYTHON_GIT_EXECUTABLE
+        old_refresh_token = cls._refresh_token
+        cls.GIT_PYTHON_GIT_EXECUTABLE = new_git
+        cls._refresh_token = object()
+
+        # Test if the new git executable path is valid. A GitCommandNotFound error is
+        # raised by us. A PermissionError is raised if the git executable cannot be
+        # executed for whatever reason.
+        has_git = False
+        try:
+            cls().version()
+            has_git = True
+        except (GitCommandNotFound, PermissionError):
+            pass
+
+        # Warn or raise exception if test failed.
+        if not has_git:
+            err = (
+                dedent(
+                    """\
+                Bad git executable.
+                The git executable must be specified in one of the following ways:
+                    - be included in your $PATH
+                    - be set via $%s
+                    - explicitly set via git.refresh(<full-path-to-git-executable>)
+                """
+                )
+                % cls._git_exec_env_var
+            )
+
+            # Revert to whatever the old_git was.
+            cls.GIT_PYTHON_GIT_EXECUTABLE = old_git
+            cls._refresh_token = old_refresh_token
+
+            if old_git is None:
+                # On the first refresh (when GIT_PYTHON_GIT_EXECUTABLE is None) we only
+                # are quiet, warn, or error depending on the GIT_PYTHON_REFRESH value.
+
+                # Determine what the user wants to happen during the initial refresh. We
+                # expect GIT_PYTHON_REFRESH to either be unset or be one of the
+                # following values:
+                #
+                #   0|q|quiet|s|silence|silent|n|none
+                #   1|w|warn|warning|l|log
+                #   2|r|raise|e|error|exception
+
+                mode = os.environ.get(cls._refresh_env_var, "raise").lower()
+
+                quiet = ["quiet", "q", "silence", "s", "silent", "none", "n", "0"]
+                warn = ["warn", "w", "warning", "log", "l", "1"]
+                error = ["error", "e", "exception", "raise", "r", "2"]
+
+                if mode in quiet:
+                    pass
+                elif mode in warn or mode in error:
+                    err = dedent(
+                        """\
+                        %s
+                        All git commands will error until this is rectified.
+
+                        This initial message can be silenced or aggravated in the future by setting the
+                        $%s environment variable. Use one of the following values:
+                            - %s: for no message or exception
+                            - %s: for a warning message (logging level CRITICAL, displayed by default)
+                            - %s: for a raised exception
+
+                        Example:
+                            export %s=%s
+                        """
+                    ) % (
+                        err,
+                        cls._refresh_env_var,
+                        "|".join(quiet),
+                        "|".join(warn),
+                        "|".join(error),
+                        cls._refresh_env_var,
+                        quiet[0],
+                    )
+
+                    if mode in warn:
+                        _logger.critical(err)
+                    else:
+                        raise ImportError(err)
+                else:
+                    err = dedent(
+                        """\
+                        %s environment variable has been set but it has been set with an invalid value.
+
+                        Use only the following values:
+                            - %s: for no message or exception
+                            - %s: for a warning message (logging level CRITICAL, displayed by default)
+                            - %s: for a raised exception
+                        """
+                    ) % (
+                        cls._refresh_env_var,
+                        "|".join(quiet),
+                        "|".join(warn),
+                        "|".join(error),
+                    )
+                    raise ImportError(err)
+
+                # We get here if this was the initial refresh and the refresh mode was
+                # not error. Go ahead and set the GIT_PYTHON_GIT_EXECUTABLE such that we
+                # discern the difference between the first refresh at import time
+                # and subsequent calls to git.refresh or this refresh method.
+                cls.GIT_PYTHON_GIT_EXECUTABLE = cls.git_exec_name
+            else:
+                # After the first refresh (when GIT_PYTHON_GIT_EXECUTABLE is no longer
+                # None) we raise an exception.
+                raise GitCommandNotFound(new_git, err)
+
+        return has_git
+
+    @classmethod
+    def is_cygwin(cls) -> bool:
+        return is_cygwin_git(cls.GIT_PYTHON_GIT_EXECUTABLE)
+
+    @overload
+    @classmethod
+    def polish_url(cls, url: str, is_cygwin: Literal[False] = ...) -> str: ...
+
+    @overload
+    @classmethod
+    def polish_url(cls, url: str, is_cygwin: Union[None, bool] = None) -> str: ...
+
+    @classmethod
+    def polish_url(cls, url: str, is_cygwin: Union[None, bool] = None) -> PathLike:
+        """Remove any backslashes from URLs to be written in config files.
+
+        Windows might create config files containing paths with backslashes, but git
+        stops liking them as it will escape the backslashes. Hence we undo the escaping
+        just to be sure.
+        """
+        if is_cygwin is None:
+            is_cygwin = cls.is_cygwin()
+
+        if is_cygwin:
+            url = cygpath(url)
+        else:
+            url = os.path.expandvars(url)
+            if url.startswith("~"):
+                url = os.path.expanduser(url)
+            url = url.replace("\\\\", "\\").replace("\\", "/")
+        return url
+
+    @classmethod
+    def check_unsafe_protocols(cls, url: str) -> None:
+        """Check for unsafe protocols.
+
+        Apart from the usual protocols (http, git, ssh), Git allows "remote helpers"
+        that have the form ``<transport>::<address>``. One of these helpers (``ext::``)
+        can be used to invoke any arbitrary command.
+
+        See:
+
+        - https://git-scm.com/docs/gitremote-helpers
+        - https://git-scm.com/docs/git-remote-ext
+        """
+        match = cls.re_unsafe_protocol.match(url)
+        if match:
+            protocol = match.group(1)
+            raise UnsafeProtocolError(
+                f"The `{protocol}::` protocol looks suspicious, use `allow_unsafe_protocols=True` to allow it."
+            )
+
+    @classmethod
+    def check_unsafe_options(cls, options: List[str], unsafe_options: List[str]) -> None:
+        """Check for unsafe options.
+
+        Some options that are passed to ``git <command>`` can be used to execute
+        arbitrary commands. These are blocked by default.
+        """
+        # Options can be of the form `foo`, `--foo bar`, or `--foo=bar`, so we need to
+        # check if they start with "--foo" or if they are equal to "foo".
+        bare_unsafe_options = [option.lstrip("-") for option in unsafe_options]
+        for option in options:
+            for unsafe_option, bare_option in zip(unsafe_options, bare_unsafe_options):
+                if option.startswith(unsafe_option) or option == bare_option:
+                    raise UnsafeOptionError(
+                        f"{unsafe_option} is not allowed, use `allow_unsafe_options=True` to allow it."
+                    )
+
+    AutoInterrupt: TypeAlias = _AutoInterrupt
+
+    CatFileContentStream: TypeAlias = _CatFileContentStream
+
+    def __init__(self, working_dir: Union[None, PathLike] = None) -> None:
+        """Initialize this instance with:
+
+        :param working_dir:
+            Git directory we should work in. If ``None``, we always work in the current
+            directory as returned by :func:`os.getcwd`.
+            This is meant to be the working tree directory if available, or the
+            ``.git`` directory in case of bare repositories.
+        """
+        super().__init__()
+        self._working_dir = expand_path(working_dir)
+        self._git_options: Union[List[str], Tuple[str, ...]] = ()
+        self._persistent_git_options: List[str] = []
+
+        # Extra environment variables to pass to git commands
+        self._environment: Dict[str, str] = {}
+
+        # Cached version slots
+        self._version_info: Union[Tuple[int, ...], None] = None
+        self._version_info_token: object = None
+
+        # Cached command slots
+        self.cat_file_header: Union[None, TBD] = None
+        self.cat_file_all: Union[None, TBD] = None
+
+    def __getattribute__(self, name: str) -> Any:
+        if name == "USE_SHELL":
+            _warn_use_shell(extra_danger=False)
+        return super().__getattribute__(name)
+
+    def __getattr__(self, name: str) -> Any:
+        """A convenience method as it allows to call the command as if it was an object.
+
+        :return:
+            Callable object that will execute call :meth:`_call_process` with your
+            arguments.
+        """
+        if name.startswith("_"):
+            return super().__getattribute__(name)
+        return lambda *args, **kwargs: self._call_process(name, *args, **kwargs)
+
+    def set_persistent_git_options(self, **kwargs: Any) -> None:
+        """Specify command line options to the git executable for subsequent
+        subcommand calls.
+
+        :param kwargs:
+            A dict of keyword arguments.
+            These arguments are passed as in :meth:`_call_process`, but will be passed
+            to the git command rather than the subcommand.
+        """
+
+        self._persistent_git_options = self.transform_kwargs(split_single_char_options=True, **kwargs)
+
+    @property
+    def working_dir(self) -> Union[None, PathLike]:
+        """:return: Git directory we are working on"""
+        return self._working_dir
+
+    @property
+    def version_info(self) -> Tuple[int, ...]:
+        """
+        :return: Tuple with integers representing the major, minor and additional
+            version numbers as parsed from :manpage:`git-version(1)`. Up to four fields
+            are used.
+
+            This value is generated on demand and is cached.
+        """
+        # Refreshing is global, but version_info caching is per-instance.
+        refresh_token = self._refresh_token  # Copy token in case of concurrent refresh.
+
+        # Use the cached version if obtained after the most recent refresh.
+        if self._version_info_token is refresh_token:
+            assert self._version_info is not None, "Bug: corrupted token-check state"
+            return self._version_info
+
+        # Run "git version" and parse it.
+        process_version = self._call_process("version")
+        version_string = process_version.split(" ")[2]
+        version_fields = version_string.split(".")[:4]
+        leading_numeric_fields = itertools.takewhile(str.isdigit, version_fields)
+        self._version_info = tuple(map(int, leading_numeric_fields))
+
+        # This value will be considered valid until the next refresh.
+        self._version_info_token = refresh_token
+        return self._version_info
+
+    @overload
+    def execute(
+        self,
+        command: Union[str, Sequence[Any]],
+        *,
+        as_process: Literal[True],
+    ) -> "AutoInterrupt": ...
+
+    @overload
+    def execute(
+        self,
+        command: Union[str, Sequence[Any]],
+        *,
+        as_process: Literal[False] = False,
+        stdout_as_string: Literal[True],
+    ) -> Union[str, Tuple[int, str, str]]: ...
+
+    @overload
+    def execute(
+        self,
+        command: Union[str, Sequence[Any]],
+        *,
+        as_process: Literal[False] = False,
+        stdout_as_string: Literal[False] = False,
+    ) -> Union[bytes, Tuple[int, bytes, str]]: ...
+
+    @overload
+    def execute(
+        self,
+        command: Union[str, Sequence[Any]],
+        *,
+        with_extended_output: Literal[False],
+        as_process: Literal[False],
+        stdout_as_string: Literal[True],
+    ) -> str: ...
+
+    @overload
+    def execute(
+        self,
+        command: Union[str, Sequence[Any]],
+        *,
+        with_extended_output: Literal[False],
+        as_process: Literal[False],
+        stdout_as_string: Literal[False],
+    ) -> bytes: ...
+
+    def execute(
+        self,
+        command: Union[str, Sequence[Any]],
+        istream: Union[None, BinaryIO] = None,
+        with_extended_output: bool = False,
+        with_exceptions: bool = True,
+        as_process: bool = False,
+        output_stream: Union[None, BinaryIO] = None,
+        stdout_as_string: bool = True,
+        kill_after_timeout: Union[None, float] = None,
+        with_stdout: bool = True,
+        universal_newlines: bool = False,
+        shell: Union[None, bool] = None,
+        env: Union[None, Mapping[str, str]] = None,
+        max_chunk_size: int = io.DEFAULT_BUFFER_SIZE,
+        strip_newline_in_stdout: bool = True,
+        **subprocess_kwargs: Any,
+    ) -> Union[str, bytes, Tuple[int, Union[str, bytes], str], AutoInterrupt]:
+        R"""Handle executing the command, and consume and return the returned
+        information (stdout).
+
+        :param command:
+            The command argument list to execute.
+            It should be a sequence of program arguments, or a string. The
+            program to execute is the first item in the args sequence or string.
+
+        :param istream:
+            Standard input filehandle passed to :class:`subprocess.Popen`.
+
+        :param with_extended_output:
+            Whether to return a (status, stdout, stderr) tuple.
+
+        :param with_exceptions:
+            Whether to raise an exception when git returns a non-zero status.
+
+        :param as_process:
+            Whether to return the created process instance directly from which
+            streams can be read on demand. This will render `with_extended_output`
+            and `with_exceptions` ineffective - the caller will have to deal with
+            the details. It is important to note that the process will be placed
+            into an :class:`AutoInterrupt` wrapper that will interrupt the process
+            once it goes out of scope. If you use the command in iterators, you
+            should pass the whole process instance instead of a single stream.
+
+        :param output_stream:
+            If set to a file-like object, data produced by the git command will be
+            copied to the given stream instead of being returned as a string.
+            This feature only has any effect if `as_process` is ``False``.
+
+        :param stdout_as_string:
+            If ``False``, the command's standard output will be bytes. Otherwise, it
+            will be decoded into a string using the default encoding (usually UTF-8).
+            The latter can fail, if the output contains binary data.
+
+        :param kill_after_timeout:
+            Specifies a timeout in seconds for the git command, after which the process
+            should be killed. This will have no effect if `as_process` is set to
+            ``True``. It is set to ``None`` by default and will let the process run
+            until the timeout is explicitly specified. Uses of this feature should be
+            carefully considered, due to the following limitations:
+
+            1. This feature is not supported at all on Windows.
+            2. Effectiveness may vary by operating system. ``ps --ppid`` is used to
+               enumerate child processes, which is available on most GNU/Linux systems
+               but not most others.
+            3. Deeper descendants do not receive signals, though they may sometimes
+               terminate as a consequence of their parent processes being killed.
+            4. `kill_after_timeout` uses ``SIGKILL``, which can have negative side
+               effects on a repository. For example, stale locks in case of
+               :manpage:`git-gc(1)` could render the repository incapable of accepting
+               changes until the lock is manually removed.
+
+        :param with_stdout:
+            If ``True``, default ``True``, we open stdout on the created process.
+
+        :param universal_newlines:
+            If ``True``, pipes will be opened as text, and lines are split at all known
+            line endings.
+
+        :param shell:
+            Whether to invoke commands through a shell
+            (see :class:`Popen(..., shell=True) <subprocess.Popen>`).
+            If this is not ``None``, it overrides :attr:`USE_SHELL`.
+
+            Passing ``shell=True`` to this or any other GitPython function should be
+            avoided, as it is unsafe under most circumstances. This is because it is
+            typically not feasible to fully consider and account for the effect of shell
+            expansions, especially when passing ``shell=True`` to other methods that
+            forward it to :meth:`Git.execute`. Passing ``shell=True`` is also no longer
+            needed (nor useful) to work around any known operating system specific
+            issues.
+
+        :param env:
+            A dictionary of environment variables to be passed to
+            :class:`subprocess.Popen`.
+
+        :param max_chunk_size:
+            Maximum number of bytes in one chunk of data passed to the `output_stream`
+            in one invocation of its ``write()`` method. If the given number is not
+            positive then the default value is used.
+
+        :param strip_newline_in_stdout:
+            Whether to strip the trailing ``\n`` of the command stdout.
+
+        :param subprocess_kwargs:
+            Keyword arguments to be passed to :class:`subprocess.Popen`. Please note
+            that some of the valid kwargs are already set by this method; the ones you
+            specify may not be the same ones.
+
+        :return:
+            * str(output), if `extended_output` is ``False`` (Default)
+            * tuple(int(status), str(stdout), str(stderr)),
+              if `extended_output` is ``True``
+
+            If `output_stream` is ``True``, the stdout value will be your output stream:
+
+            * output_stream, if `extended_output` is ``False``
+            * tuple(int(status), output_stream, str(stderr)),
+              if `extended_output` is ``True``
+
+            Note that git is executed with ``LC_MESSAGES="C"`` to ensure consistent
+            output regardless of system language.
+
+        :raise git.exc.GitCommandError:
+
+        :note:
+            If you add additional keyword arguments to the signature of this method, you
+            must update the ``execute_kwargs`` variable housed in this module.
+        """
+        # Remove password for the command if present.
+        redacted_command = remove_password_if_present(command)
+        if self.GIT_PYTHON_TRACE and (self.GIT_PYTHON_TRACE != "full" or as_process):
+            _logger.info(" ".join(redacted_command))
+
+        # Allow the user to have the command executed in their working dir.
+        try:
+            cwd = self._working_dir or os.getcwd()  # type: Union[None, str]
+            if not os.access(str(cwd), os.X_OK):
+                cwd = None
+        except FileNotFoundError:
+            cwd = None
+
+        # Start the process.
+        inline_env = env
+        env = os.environ.copy()
+        # Attempt to force all output to plain ASCII English, which is what some parsing
+        # code may expect.
+        # According to https://askubuntu.com/a/311796, we are setting LANGUAGE as well
+        # just to be sure.
+        env["LANGUAGE"] = "C"
+        env["LC_ALL"] = "C"
+        env.update(self._environment)
+        if inline_env is not None:
+            env.update(inline_env)
+
+        if sys.platform == "win32":
+            if kill_after_timeout is not None:
+                raise GitCommandError(
+                    redacted_command,
+                    '"kill_after_timeout" feature is not supported on Windows.',
+                )
+            cmd_not_found_exception = OSError
+        else:
+            cmd_not_found_exception = FileNotFoundError
+        # END handle
+
+        stdout_sink = PIPE if with_stdout else getattr(subprocess, "DEVNULL", None) or open(os.devnull, "wb")
+        if shell is None:
+            # Get the value of USE_SHELL with no deprecation warning. Do this without
+            # warnings.catch_warnings, to avoid a race condition with application code
+            # configuring warnings. The value could be looked up in type(self).__dict__
+            # or Git.__dict__, but those can break under some circumstances. This works
+            # the same as self.USE_SHELL in more situations; see Git.__getattribute__.
+            shell = super().__getattribute__("USE_SHELL")
+        _logger.debug(
+            "Popen(%s, cwd=%s, stdin=%s, shell=%s, universal_newlines=%s)",
+            redacted_command,
+            cwd,
+            "<valid stream>" if istream else "None",
+            shell,
+            universal_newlines,
+        )
+        try:
+            proc = safer_popen(
+                command,
+                env=env,
+                cwd=cwd,
+                bufsize=-1,
+                stdin=(istream or DEVNULL),
+                stderr=PIPE,
+                stdout=stdout_sink,
+                shell=shell,
+                universal_newlines=universal_newlines,
+                encoding=defenc if universal_newlines else None,
+                **subprocess_kwargs,
+            )
+        except cmd_not_found_exception as err:
+            raise GitCommandNotFound(redacted_command, err) from err
+        else:
+            # Replace with a typeguard for Popen[bytes]?
+            proc.stdout = cast(BinaryIO, proc.stdout)
+            proc.stderr = cast(BinaryIO, proc.stderr)
+
+        if as_process:
+            return self.AutoInterrupt(proc, command)
+
+        if sys.platform != "win32" and kill_after_timeout is not None:
+            # Help mypy figure out this is not None even when used inside communicate().
+            timeout = kill_after_timeout
+
+            def kill_process(pid: int) -> None:
+                """Callback to kill a process.
+
+                This callback implementation would be ineffective and unsafe on Windows.
+                """
+                p = Popen(["ps", "--ppid", str(pid)], stdout=PIPE)
+                child_pids = []
+                if p.stdout is not None:
+                    for line in p.stdout:
+                        if len(line.split()) > 0:
+                            local_pid = (line.split())[0]
+                            if local_pid.isdigit():
+                                child_pids.append(int(local_pid))
+                try:
+                    os.kill(pid, signal.SIGKILL)
+                    for child_pid in child_pids:
+                        try:
+                            os.kill(child_pid, signal.SIGKILL)
+                        except OSError:
+                            pass
+                    # Tell the main routine that the process was killed.
+                    kill_check.set()
+                except OSError:
+                    # It is possible that the process gets completed in the duration
+                    # after timeout happens and before we try to kill the process.
+                    pass
+                return
+
+            def communicate() -> Tuple[AnyStr, AnyStr]:
+                watchdog.start()
+                out, err = proc.communicate()
+                watchdog.cancel()
+                if kill_check.is_set():
+                    err = 'Timeout: the command "%s" did not complete in %d secs.' % (
+                        " ".join(redacted_command),
+                        timeout,
+                    )
+                    if not universal_newlines:
+                        err = err.encode(defenc)
+                return out, err
+
+            # END helpers
+
+            kill_check = threading.Event()
+            watchdog = threading.Timer(timeout, kill_process, args=(proc.pid,))
+        else:
+            communicate = proc.communicate
+
+        # Wait for the process to return.
+        status = 0
+        stdout_value: Union[str, bytes] = b""
+        stderr_value: Union[str, bytes] = b""
+        newline = "\n" if universal_newlines else b"\n"
+        try:
+            if output_stream is None:
+                stdout_value, stderr_value = communicate()
+                # Strip trailing "\n".
+                if stdout_value.endswith(newline) and strip_newline_in_stdout:  # type: ignore[arg-type]
+                    stdout_value = stdout_value[:-1]
+                if stderr_value.endswith(newline):  # type: ignore[arg-type]
+                    stderr_value = stderr_value[:-1]
+
+                status = proc.returncode
+            else:
+                max_chunk_size = max_chunk_size if max_chunk_size and max_chunk_size > 0 else io.DEFAULT_BUFFER_SIZE
+                stream_copy(proc.stdout, output_stream, max_chunk_size)
+                stdout_value = proc.stdout.read()
+                stderr_value = proc.stderr.read()
+                # Strip trailing "\n".
+                if stderr_value.endswith(newline):  # type: ignore[arg-type]
+                    stderr_value = stderr_value[:-1]
+                status = proc.wait()
+            # END stdout handling
+        finally:
+            proc.stdout.close()
+            proc.stderr.close()
+
+        if self.GIT_PYTHON_TRACE == "full":
+            cmdstr = " ".join(redacted_command)
+
+            def as_text(stdout_value: Union[bytes, str]) -> str:
+                return not output_stream and safe_decode(stdout_value) or "<OUTPUT_STREAM>"
+
+            # END as_text
+
+            if stderr_value:
+                _logger.info(
+                    "%s -> %d; stdout: '%s'; stderr: '%s'",
+                    cmdstr,
+                    status,
+                    as_text(stdout_value),
+                    safe_decode(stderr_value),
+                )
+            elif stdout_value:
+                _logger.info("%s -> %d; stdout: '%s'", cmdstr, status, as_text(stdout_value))
+            else:
+                _logger.info("%s -> %d", cmdstr, status)
+        # END handle debug printing
+
+        if with_exceptions and status != 0:
+            raise GitCommandError(redacted_command, status, stderr_value, stdout_value)
+
+        if isinstance(stdout_value, bytes) and stdout_as_string:  # Could also be output_stream.
+            stdout_value = safe_decode(stdout_value)
+
+        # Allow access to the command's status code.
+        if with_extended_output:
+            return (status, stdout_value, safe_decode(stderr_value))
+        else:
+            return stdout_value
+
+    def environment(self) -> Dict[str, str]:
+        return self._environment
+
+    def update_environment(self, **kwargs: Any) -> Dict[str, Union[str, None]]:
+        """Set environment variables for future git invocations. Return all changed
+        values in a format that can be passed back into this function to revert the
+        changes.
+
+        Examples::
+
+            old_env = self.update_environment(PWD='/tmp')
+            self.update_environment(**old_env)
+
+        :param kwargs:
+            Environment variables to use for git processes.
+
+        :return:
+            Dict that maps environment variables to their old values
+        """
+        old_env = {}
+        for key, value in kwargs.items():
+            # Set value if it is None.
+            if value is not None:
+                old_env[key] = self._environment.get(key)
+                self._environment[key] = value
+            # Remove key from environment if its value is None.
+            elif key in self._environment:
+                old_env[key] = self._environment[key]
+                del self._environment[key]
+        return old_env
+
+    @contextlib.contextmanager
+    def custom_environment(self, **kwargs: Any) -> Iterator[None]:
+        """A context manager around the above :meth:`update_environment` method to
+        restore the environment back to its previous state after operation.
+
+        Examples::
+
+            with self.custom_environment(GIT_SSH='/bin/ssh_wrapper'):
+                repo.remotes.origin.fetch()
+
+        :param kwargs:
+            See :meth:`update_environment`.
+        """
+        old_env = self.update_environment(**kwargs)
+        try:
+            yield
+        finally:
+            self.update_environment(**old_env)
+
+    def transform_kwarg(self, name: str, value: Any, split_single_char_options: bool) -> List[str]:
+        if len(name) == 1:
+            if value is True:
+                return ["-%s" % name]
+            elif value not in (False, None):
+                if split_single_char_options:
+                    return ["-%s" % name, "%s" % value]
+                else:
+                    return ["-%s%s" % (name, value)]
+        else:
+            if value is True:
+                return ["--%s" % dashify(name)]
+            elif value is not False and value is not None:
+                return ["--%s=%s" % (dashify(name), value)]
+        return []
+
+    def transform_kwargs(self, split_single_char_options: bool = True, **kwargs: Any) -> List[str]:
+        """Transform Python-style kwargs into git command line options."""
+        args = []
+        for k, v in kwargs.items():
+            if isinstance(v, (list, tuple)):
+                for value in v:
+                    args += self.transform_kwarg(k, value, split_single_char_options)
+            else:
+                args += self.transform_kwarg(k, v, split_single_char_options)
+        return args
+
+    @classmethod
+    def _unpack_args(cls, arg_list: Sequence[str]) -> List[str]:
+        outlist = []
+        if isinstance(arg_list, (list, tuple)):
+            for arg in arg_list:
+                outlist.extend(cls._unpack_args(arg))
+        else:
+            outlist.append(str(arg_list))
+
+        return outlist
+
+    def __call__(self, **kwargs: Any) -> "Git":
+        """Specify command line options to the git executable for a subcommand call.
+
+        :param kwargs:
+            A dict of keyword arguments.
+            These arguments are passed as in :meth:`_call_process`, but will be passed
+            to the git command rather than the subcommand.
+
+        Examples::
+
+            git(work_tree='/tmp').difftool()
+        """
+        self._git_options = self.transform_kwargs(split_single_char_options=True, **kwargs)
+        return self
+
+    @overload
+    def _call_process(
+        self, method: str, *args: None, **kwargs: None
+    ) -> str: ...  # If no args were given, execute the call with all defaults.
+
+    @overload
+    def _call_process(
+        self,
+        method: str,
+        istream: int,
+        as_process: Literal[True],
+        *args: Any,
+        **kwargs: Any,
+    ) -> "Git.AutoInterrupt": ...
+
+    @overload
+    def _call_process(
+        self, method: str, *args: Any, **kwargs: Any
+    ) -> Union[str, bytes, Tuple[int, Union[str, bytes], str], "Git.AutoInterrupt"]: ...
+
+    def _call_process(
+        self, method: str, *args: Any, **kwargs: Any
+    ) -> Union[str, bytes, Tuple[int, Union[str, bytes], str], "Git.AutoInterrupt"]:
+        """Run the given git command with the specified arguments and return the result
+        as a string.
+
+        :param method:
+            The command. Contained ``_`` characters will be converted to hyphens, such
+            as in ``ls_files`` to call ``ls-files``.
+
+        :param args:
+            The list of arguments. If ``None`` is included, it will be pruned.
+            This allows your commands to call git more conveniently, as ``None`` is
+            realized as non-existent.
+
+        :param kwargs:
+            Contains key-values for the following:
+
+            - The :meth:`execute()` kwds, as listed in ``execute_kwargs``.
+            - "Command options" to be converted by :meth:`transform_kwargs`.
+            - The ``insert_kwargs_after`` key which its value must match one of
+              ``*args``.
+
+            It also contains any command options, to be appended after the matched arg.
+
+        Examples::
+
+            git.rev_list('master', max_count=10, header=True)
+
+        turns into::
+
+            git rev-list max-count 10 --header master
+
+        :return:
+            Same as :meth:`execute`. If no args are given, used :meth:`execute`'s
+            default (especially ``as_process = False``, ``stdout_as_string = True``) and
+            return :class:`str`.
+        """
+        # Handle optional arguments prior to calling transform_kwargs.
+        # Otherwise these'll end up in args, which is bad.
+        exec_kwargs = {k: v for k, v in kwargs.items() if k in execute_kwargs}
+        opts_kwargs = {k: v for k, v in kwargs.items() if k not in execute_kwargs}
+
+        insert_after_this_arg = opts_kwargs.pop("insert_kwargs_after", None)
+
+        # Prepare the argument list.
+
+        opt_args = self.transform_kwargs(**opts_kwargs)
+        ext_args = self._unpack_args([a for a in args if a is not None])
+
+        if insert_after_this_arg is None:
+            args_list = opt_args + ext_args
+        else:
+            try:
+                index = ext_args.index(insert_after_this_arg)
+            except ValueError as err:
+                raise ValueError(
+                    "Couldn't find argument '%s' in args %s to insert cmd options after"
+                    % (insert_after_this_arg, str(ext_args))
+                ) from err
+            # END handle error
+            args_list = ext_args[: index + 1] + opt_args + ext_args[index + 1 :]
+        # END handle opts_kwargs
+
+        call = [self.GIT_PYTHON_GIT_EXECUTABLE]
+
+        # Add persistent git options.
+        call.extend(self._persistent_git_options)
+
+        # Add the git options, then reset to empty to avoid side effects.
+        call.extend(self._git_options)
+        self._git_options = ()
+
+        call.append(dashify(method))
+        call.extend(args_list)
+
+        return self.execute(call, **exec_kwargs)
+
+    def _parse_object_header(self, header_line: str) -> Tuple[str, str, int]:
+        """
+        :param header_line:
+            A line of the form::
+
+                <hex_sha> type_string size_as_int
+
+        :return:
+            (hex_sha, type_string, size_as_int)
+
+        :raise ValueError:
+            If the header contains indication for an error due to incorrect input sha.
+        """
+        tokens = header_line.split()
+        if len(tokens) != 3:
+            if not tokens:
+                err_msg = (
+                    f"SHA is empty, possible dubious ownership in the repository "
+                    f"""at {self._working_dir}.\n            If this is unintended run:\n\n         """
+                    f"""             "git config --global --add safe.directory {self._working_dir}" """
+                )
+                raise ValueError(err_msg)
+            else:
+                raise ValueError("SHA %s could not be resolved, git returned: %r" % (tokens[0], header_line.strip()))
+            # END handle actual return value
+        # END error handling
+
+        if len(tokens[0]) != 40:
+            raise ValueError("Failed to parse header: %r" % header_line)
+        return (tokens[0], tokens[1], int(tokens[2]))
+
+    def _prepare_ref(self, ref: AnyStr) -> bytes:
+        # Required for command to separate refs on stdin, as bytes.
+        if isinstance(ref, bytes):
+            # Assume 40 bytes hexsha - bin-to-ascii for some reason returns bytes, not text.
+            refstr: str = ref.decode("ascii")
+        elif not isinstance(ref, str):
+            refstr = str(ref)  # Could be ref-object.
+        else:
+            refstr = ref
+
+        if not refstr.endswith("\n"):
+            refstr += "\n"
+        return refstr.encode(defenc)
+
+    def _get_persistent_cmd(self, attr_name: str, cmd_name: str, *args: Any, **kwargs: Any) -> "Git.AutoInterrupt":
+        cur_val = getattr(self, attr_name)
+        if cur_val is not None:
+            return cur_val
+
+        options = {"istream": PIPE, "as_process": True}
+        options.update(kwargs)
+
+        cmd = self._call_process(cmd_name, *args, **options)
+        setattr(self, attr_name, cmd)
+        cmd = cast("Git.AutoInterrupt", cmd)
+        return cmd
+
+    def __get_object_header(self, cmd: "Git.AutoInterrupt", ref: AnyStr) -> Tuple[str, str, int]:
+        if cmd.stdin and cmd.stdout:
+            cmd.stdin.write(self._prepare_ref(ref))
+            cmd.stdin.flush()
+            return self._parse_object_header(cmd.stdout.readline())
+        else:
+            raise ValueError("cmd stdin was empty")
+
+    def get_object_header(self, ref: str) -> Tuple[str, str, int]:
+        """Use this method to quickly examine the type and size of the object behind the
+        given ref.
+
+        :note:
+            The method will only suffer from the costs of command invocation once and
+            reuses the command in subsequent calls.
+
+        :return:
+            (hexsha, type_string, size_as_int)
+        """
+        cmd = self._get_persistent_cmd("cat_file_header", "cat_file", batch_check=True)
+        return self.__get_object_header(cmd, ref)
+
+    def get_object_data(self, ref: str) -> Tuple[str, str, int, bytes]:
+        """Similar to :meth:`get_object_header`, but returns object data as well.
+
+        :return:
+            (hexsha, type_string, size_as_int, data_string)
+
+        :note:
+            Not threadsafe.
+        """
+        hexsha, typename, size, stream = self.stream_object_data(ref)
+        data = stream.read(size)
+        del stream
+        return (hexsha, typename, size, data)
+
+    def stream_object_data(self, ref: str) -> Tuple[str, str, int, "Git.CatFileContentStream"]:
+        """Similar to :meth:`get_object_data`, but returns the data as a stream.
+
+        :return:
+            (hexsha, type_string, size_as_int, stream)
+
+        :note:
+            This method is not threadsafe. You need one independent :class:`Git`
+            instance per thread to be safe!
+        """
+        cmd = self._get_persistent_cmd("cat_file_all", "cat_file", batch=True)
+        hexsha, typename, size = self.__get_object_header(cmd, ref)
+        cmd_stdout = cmd.stdout if cmd.stdout is not None else io.BytesIO()
+        return (hexsha, typename, size, self.CatFileContentStream(size, cmd_stdout))
+
+    def clear_cache(self) -> "Git":
+        """Clear all kinds of internal caches to release resources.
+
+        Currently persistent commands will be interrupted.
+
+        :return:
+            self
+        """
+        for cmd in (self.cat_file_all, self.cat_file_header):
+            if cmd:
+                cmd.__del__()
+
+        self.cat_file_all = None
+        self.cat_file_header = None
+        return self

.venv/lib/python3.11/site-packages/git/compat.py

@@ -0,0 +1,165 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Utilities to help provide compatibility with Python 3.
+
+This module exists for historical reasons. Code outside GitPython may make use of public
+members of this module, but is unlikely to benefit from doing so. GitPython continues to
+use some of these utilities, in some cases for compatibility across different platforms.
+"""
+
+import locale
+import os
+import sys
+import warnings
+
+from gitdb.utils.encoding import force_bytes, force_text  # noqa: F401
+
+# typing --------------------------------------------------------------------
+
+from typing import (
+    Any,  # noqa: F401
+    AnyStr,
+    Dict,  # noqa: F401
+    IO,  # noqa: F401
+    List,
+    Optional,
+    TYPE_CHECKING,
+    Tuple,  # noqa: F401
+    Type,  # noqa: F401
+    Union,
+    overload,
+)
+
+# ---------------------------------------------------------------------------
+
+
+_deprecated_platform_aliases = {
+    "is_win": os.name == "nt",
+    "is_posix": os.name == "posix",
+    "is_darwin": sys.platform == "darwin",
+}
+
+
+def _getattr(name: str) -> Any:
+    try:
+        value = _deprecated_platform_aliases[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+
+    warnings.warn(
+        f"{__name__}.{name} and other is_<platform> aliases are deprecated. "
+        "Write the desired os.name or sys.platform check explicitly instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return value
+
+
+if not TYPE_CHECKING:  # Preserve static checking for undefined/misspelled attributes.
+    __getattr__ = _getattr
+
+
+def __dir__() -> List[str]:
+    return [*globals(), *_deprecated_platform_aliases]
+
+
+is_win: bool
+"""Deprecated alias for ``os.name == "nt"`` to check for native Windows.
+
+This is deprecated because it is clearer to write out :attr:`os.name` or
+:attr:`sys.platform` checks explicitly, especially in cases where it matters which is
+used.
+
+:note:
+    ``is_win`` is ``False`` on Cygwin, but is often wrongly assumed ``True``. To detect
+    Cygwin, use ``sys.platform == "cygwin"``.
+"""
+
+is_posix: bool
+"""Deprecated alias for ``os.name == "posix"`` to check for Unix-like ("POSIX") systems.
+
+This is deprecated because it clearer to write out :attr:`os.name` or
+:attr:`sys.platform` checks explicitly, especially in cases where it matters which is
+used.
+
+:note:
+    For POSIX systems, more detailed information is available in :attr:`sys.platform`,
+    while :attr:`os.name` is always ``"posix"`` on such systems, including macOS
+    (Darwin).
+"""
+
+is_darwin: bool
+"""Deprecated alias for ``sys.platform == "darwin"`` to check for macOS (Darwin).
+
+This is deprecated because it clearer to write out :attr:`os.name` or
+:attr:`sys.platform` checks explicitly.
+
+:note:
+    For macOS (Darwin), ``os.name == "posix"`` as in other Unix-like systems, while
+    ``sys.platform == "darwin"``.
+"""
+
+defenc = sys.getfilesystemencoding()
+"""The encoding used to convert between Unicode and bytes filenames."""
+
+
+@overload
+def safe_decode(s: None) -> None: ...
+
+
+@overload
+def safe_decode(s: AnyStr) -> str: ...
+
+
+def safe_decode(s: Union[AnyStr, None]) -> Optional[str]:
+    """Safely decode a binary string to Unicode."""
+    if isinstance(s, str):
+        return s
+    elif isinstance(s, bytes):
+        return s.decode(defenc, "surrogateescape")
+    elif s is None:
+        return None
+    else:
+        raise TypeError("Expected bytes or text, but got %r" % (s,))
+
+
+@overload
+def safe_encode(s: None) -> None: ...
+
+
+@overload
+def safe_encode(s: AnyStr) -> bytes: ...
+
+
+def safe_encode(s: Optional[AnyStr]) -> Optional[bytes]:
+    """Safely encode a binary string to Unicode."""
+    if isinstance(s, str):
+        return s.encode(defenc)
+    elif isinstance(s, bytes):
+        return s
+    elif s is None:
+        return None
+    else:
+        raise TypeError("Expected bytes or text, but got %r" % (s,))
+
+
+@overload
+def win_encode(s: None) -> None: ...
+
+
+@overload
+def win_encode(s: AnyStr) -> bytes: ...
+
+
+def win_encode(s: Optional[AnyStr]) -> Optional[bytes]:
+    """Encode Unicode strings for process arguments on Windows."""
+    if isinstance(s, str):
+        return s.encode(locale.getpreferredencoding(False))
+    elif isinstance(s, bytes):
+        return s
+    elif s is not None:
+        raise TypeError("Expected bytes or text, but got %r" % (s,))
+    return None

.venv/lib/python3.11/site-packages/git/config.py

@@ -0,0 +1,951 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Parser for reading and writing configuration files."""
+
+__all__ = ["GitConfigParser", "SectionConstraint"]
+
+import abc
+import configparser as cp
+import fnmatch
+from functools import wraps
+import inspect
+from io import BufferedReader, IOBase
+import logging
+import os
+import os.path as osp
+import re
+import sys
+
+from git.compat import defenc, force_text
+from git.util import LockFile
+
+# typing-------------------------------------------------------
+
+from typing import (
+    Any,
+    Callable,
+    Generic,
+    IO,
+    List,
+    Dict,
+    Sequence,
+    TYPE_CHECKING,
+    Tuple,
+    TypeVar,
+    Union,
+    cast,
+)
+
+from git.types import Lit_config_levels, ConfigLevels_Tup, PathLike, assert_never, _T
+
+if TYPE_CHECKING:
+    from io import BytesIO
+
+    from git.repo.base import Repo
+
+T_ConfigParser = TypeVar("T_ConfigParser", bound="GitConfigParser")
+T_OMD_value = TypeVar("T_OMD_value", str, bytes, int, float, bool)
+
+if sys.version_info[:3] < (3, 7, 2):
+    # typing.Ordereddict not added until Python 3.7.2.
+    from collections import OrderedDict
+
+    OrderedDict_OMD = OrderedDict
+else:
+    from typing import OrderedDict
+
+    OrderedDict_OMD = OrderedDict[str, List[T_OMD_value]]  # type: ignore[assignment, misc]
+
+# -------------------------------------------------------------
+
+_logger = logging.getLogger(__name__)
+
+CONFIG_LEVELS: ConfigLevels_Tup = ("system", "user", "global", "repository")
+"""The configuration level of a configuration file."""
+
+CONDITIONAL_INCLUDE_REGEXP = re.compile(r"(?<=includeIf )\"(gitdir|gitdir/i|onbranch):(.+)\"")
+"""Section pattern to detect conditional includes.
+
+See: https://git-scm.com/docs/git-config#_conditional_includes
+"""
+
+
+class MetaParserBuilder(abc.ABCMeta):  # noqa: B024
+    """Utility class wrapping base-class methods into decorators that assure read-only
+    properties."""
+
+    def __new__(cls, name: str, bases: Tuple, clsdict: Dict[str, Any]) -> "MetaParserBuilder":
+        """Equip all base-class methods with a needs_values decorator, and all non-const
+        methods with a :func:`set_dirty_and_flush_changes` decorator in addition to
+        that.
+        """
+        kmm = "_mutating_methods_"
+        if kmm in clsdict:
+            mutating_methods = clsdict[kmm]
+            for base in bases:
+                methods = (t for t in inspect.getmembers(base, inspect.isroutine) if not t[0].startswith("_"))
+                for method_name, method in methods:
+                    if method_name in clsdict:
+                        continue
+                    method_with_values = needs_values(method)
+                    if method_name in mutating_methods:
+                        method_with_values = set_dirty_and_flush_changes(method_with_values)
+                    # END mutating methods handling
+
+                    clsdict[method_name] = method_with_values
+                # END for each name/method pair
+            # END for each base
+        # END if mutating methods configuration is set
+
+        new_type = super().__new__(cls, name, bases, clsdict)
+        return new_type
+
+
+def needs_values(func: Callable[..., _T]) -> Callable[..., _T]:
+    """Return a method for ensuring we read values (on demand) before we try to access
+    them."""
+
+    @wraps(func)
+    def assure_data_present(self: "GitConfigParser", *args: Any, **kwargs: Any) -> _T:
+        self.read()
+        return func(self, *args, **kwargs)
+
+    # END wrapper method
+    return assure_data_present
+
+
+def set_dirty_and_flush_changes(non_const_func: Callable[..., _T]) -> Callable[..., _T]:
+    """Return a method that checks whether given non constant function may be called.
+
+    If so, the instance will be set dirty. Additionally, we flush the changes right to
+    disk.
+    """
+
+    def flush_changes(self: "GitConfigParser", *args: Any, **kwargs: Any) -> _T:
+        rval = non_const_func(self, *args, **kwargs)
+        self._dirty = True
+        self.write()
+        return rval
+
+    # END wrapper method
+    flush_changes.__name__ = non_const_func.__name__
+    return flush_changes
+
+
+class SectionConstraint(Generic[T_ConfigParser]):
+    """Constrains a ConfigParser to only option commands which are constrained to
+    always use the section we have been initialized with.
+
+    It supports all ConfigParser methods that operate on an option.
+
+    :note:
+        If used as a context manager, will release the wrapped ConfigParser.
+    """
+
+    __slots__ = ("_config", "_section_name")
+
+    _valid_attrs_ = (
+        "get_value",
+        "set_value",
+        "get",
+        "set",
+        "getint",
+        "getfloat",
+        "getboolean",
+        "has_option",
+        "remove_section",
+        "remove_option",
+        "options",
+    )
+
+    def __init__(self, config: T_ConfigParser, section: str) -> None:
+        self._config = config
+        self._section_name = section
+
+    def __del__(self) -> None:
+        # Yes, for some reason, we have to call it explicitly for it to work in PY3 !
+        # Apparently __del__ doesn't get call anymore if refcount becomes 0
+        # Ridiculous ... .
+        self._config.release()
+
+    def __getattr__(self, attr: str) -> Any:
+        if attr in self._valid_attrs_:
+            return lambda *args, **kwargs: self._call_config(attr, *args, **kwargs)
+        return super().__getattribute__(attr)
+
+    def _call_config(self, method: str, *args: Any, **kwargs: Any) -> Any:
+        """Call the configuration at the given method which must take a section name as
+        first argument."""
+        return getattr(self._config, method)(self._section_name, *args, **kwargs)
+
+    @property
+    def config(self) -> T_ConfigParser:
+        """return: ConfigParser instance we constrain"""
+        return self._config
+
+    def release(self) -> None:
+        """Equivalent to :meth:`GitConfigParser.release`, which is called on our
+        underlying parser instance."""
+        return self._config.release()
+
+    def __enter__(self) -> "SectionConstraint[T_ConfigParser]":
+        self._config.__enter__()
+        return self
+
+    def __exit__(self, exception_type: str, exception_value: str, traceback: str) -> None:
+        self._config.__exit__(exception_type, exception_value, traceback)
+
+
+class _OMD(OrderedDict_OMD):
+    """Ordered multi-dict."""
+
+    def __setitem__(self, key: str, value: _T) -> None:
+        super().__setitem__(key, [value])
+
+    def add(self, key: str, value: Any) -> None:
+        if key not in self:
+            super().__setitem__(key, [value])
+            return
+
+        super().__getitem__(key).append(value)
+
+    def setall(self, key: str, values: List[_T]) -> None:
+        super().__setitem__(key, values)
+
+    def __getitem__(self, key: str) -> Any:
+        return super().__getitem__(key)[-1]
+
+    def getlast(self, key: str) -> Any:
+        return super().__getitem__(key)[-1]
+
+    def setlast(self, key: str, value: Any) -> None:
+        if key not in self:
+            super().__setitem__(key, [value])
+            return
+
+        prior = super().__getitem__(key)
+        prior[-1] = value
+
+    def get(self, key: str, default: Union[_T, None] = None) -> Union[_T, None]:
+        return super().get(key, [default])[-1]
+
+    def getall(self, key: str) -> List[_T]:
+        return super().__getitem__(key)
+
+    def items(self) -> List[Tuple[str, _T]]:  # type: ignore[override]
+        """List of (key, last value for key)."""
+        return [(k, self[k]) for k in self]
+
+    def items_all(self) -> List[Tuple[str, List[_T]]]:
+        """List of (key, list of values for key)."""
+        return [(k, self.getall(k)) for k in self]
+
+
+def get_config_path(config_level: Lit_config_levels) -> str:
+    # We do not support an absolute path of the gitconfig on Windows.
+    # Use the global config instead.
+    if sys.platform == "win32" and config_level == "system":
+        config_level = "global"
+
+    if config_level == "system":
+        return "/etc/gitconfig"
+    elif config_level == "user":
+        config_home = os.environ.get("XDG_CONFIG_HOME") or osp.join(os.environ.get("HOME", "~"), ".config")
+        return osp.normpath(osp.expanduser(osp.join(config_home, "git", "config")))
+    elif config_level == "global":
+        return osp.normpath(osp.expanduser("~/.gitconfig"))
+    elif config_level == "repository":
+        raise ValueError("No repo to get repository configuration from. Use Repo._get_config_path")
+    else:
+        # Should not reach here. Will raise ValueError if does. Static typing will warn
+        # about missing elifs.
+        assert_never(  # type: ignore[unreachable]
+            config_level,
+            ValueError(f"Invalid configuration level: {config_level!r}"),
+        )
+
+
+class GitConfigParser(cp.RawConfigParser, metaclass=MetaParserBuilder):
+    """Implements specifics required to read git style configuration files.
+
+    This variation behaves much like the :manpage:`git-config(1)` command, such that the
+    configuration will be read on demand based on the filepath given during
+    initialization.
+
+    The changes will automatically be written once the instance goes out of scope, but
+    can be triggered manually as well.
+
+    The configuration file will be locked if you intend to change values preventing
+    other instances to write concurrently.
+
+    :note:
+        The config is case-sensitive even when queried, hence section and option names
+        must match perfectly.
+
+    :note:
+        If used as a context manager, this will release the locked file.
+    """
+
+    # { Configuration
+    t_lock = LockFile
+    """The lock type determines the type of lock to use in new configuration readers.
+
+    They must be compatible to the :class:`~git.util.LockFile` interface.
+    A suitable alternative would be the :class:`~git.util.BlockingLockFile`.
+    """
+
+    re_comment = re.compile(r"^\s*[#;]")
+    # } END configuration
+
+    optvalueonly_source = r"\s*(?P<option>[^:=\s][^:=]*)"
+
+    OPTVALUEONLY = re.compile(optvalueonly_source)
+
+    OPTCRE = re.compile(optvalueonly_source + r"\s*(?P<vi>[:=])\s*" + r"(?P<value>.*)$")
+
+    del optvalueonly_source
+
+    _mutating_methods_ = ("add_section", "remove_section", "remove_option", "set")
+    """Names of :class:`~configparser.RawConfigParser` methods able to change the
+    instance."""
+
+    def __init__(
+        self,
+        file_or_files: Union[None, PathLike, "BytesIO", Sequence[Union[PathLike, "BytesIO"]]] = None,
+        read_only: bool = True,
+        merge_includes: bool = True,
+        config_level: Union[Lit_config_levels, None] = None,
+        repo: Union["Repo", None] = None,
+    ) -> None:
+        """Initialize a configuration reader to read the given `file_or_files` and to
+        possibly allow changes to it by setting `read_only` False.
+
+        :param file_or_files:
+            A file path or file object, or a sequence of possibly more than one of them.
+
+        :param read_only:
+            If ``True``, the ConfigParser may only read the data, but not change it.
+            If ``False``, only a single file path or file object may be given. We will
+            write back the changes when they happen, or when the ConfigParser is
+            released. This will not happen if other configuration files have been
+            included.
+
+        :param merge_includes:
+            If ``True``, we will read files mentioned in ``[include]`` sections and
+            merge their contents into ours. This makes it impossible to write back an
+            individual configuration file. Thus, if you want to modify a single
+            configuration file, turn this off to leave the original dataset unaltered
+            when reading it.
+
+        :param repo:
+            Reference to repository to use if ``[includeIf]`` sections are found in
+            configuration files.
+        """
+        cp.RawConfigParser.__init__(self, dict_type=_OMD)
+        self._dict: Callable[..., _OMD]
+        self._defaults: _OMD
+        self._sections: _OMD
+
+        # Used in Python 3. Needs to stay in sync with sections for underlying
+        # implementation to work.
+        if not hasattr(self, "_proxies"):
+            self._proxies = self._dict()
+
+        if file_or_files is not None:
+            self._file_or_files: Union[PathLike, "BytesIO", Sequence[Union[PathLike, "BytesIO"]]] = file_or_files
+        else:
+            if config_level is None:
+                if read_only:
+                    self._file_or_files = [
+                        get_config_path(cast(Lit_config_levels, f)) for f in CONFIG_LEVELS if f != "repository"
+                    ]
+                else:
+                    raise ValueError("No configuration level or configuration files specified")
+            else:
+                self._file_or_files = [get_config_path(config_level)]
+
+        self._read_only = read_only
+        self._dirty = False
+        self._is_initialized = False
+        self._merge_includes = merge_includes
+        self._repo = repo
+        self._lock: Union["LockFile", None] = None
+        self._acquire_lock()
+
+    def _acquire_lock(self) -> None:
+        if not self._read_only:
+            if not self._lock:
+                if isinstance(self._file_or_files, (str, os.PathLike)):
+                    file_or_files = self._file_or_files
+                elif isinstance(self._file_or_files, (tuple, list, Sequence)):
+                    raise ValueError(
+                        "Write-ConfigParsers can operate on a single file only, multiple files have been passed"
+                    )
+                else:
+                    file_or_files = self._file_or_files.name
+
+                # END get filename from handle/stream
+                # Initialize lock base - we want to write.
+                self._lock = self.t_lock(file_or_files)
+            # END lock check
+
+            self._lock._obtain_lock()
+        # END read-only check
+
+    def __del__(self) -> None:
+        """Write pending changes if required and release locks."""
+        # NOTE: Only consistent in Python 2.
+        self.release()
+
+    def __enter__(self) -> "GitConfigParser":
+        self._acquire_lock()
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.release()
+
+    def release(self) -> None:
+        """Flush changes and release the configuration write lock. This instance must
+        not be used anymore afterwards.
+
+        In Python 3, it's required to explicitly release locks and flush changes, as
+        ``__del__`` is not called deterministically anymore.
+        """
+        # Checking for the lock here makes sure we do not raise during write()
+        # in case an invalid parser was created who could not get a lock.
+        if self.read_only or (self._lock and not self._lock._has_lock()):
+            return
+
+        try:
+            self.write()
+        except IOError:
+            _logger.error("Exception during destruction of GitConfigParser", exc_info=True)
+        except ReferenceError:
+            # This happens in Python 3... and usually means that some state cannot be
+            # written as the sections dict cannot be iterated. This usually happens when
+            # the interpreter is shutting down. Can it be fixed?
+            pass
+        finally:
+            if self._lock is not None:
+                self._lock._release_lock()
+
+    def optionxform(self, optionstr: str) -> str:
+        """Do not transform options in any way when writing."""
+        return optionstr
+
+    def _read(self, fp: Union[BufferedReader, IO[bytes]], fpname: str) -> None:
+        """Originally a direct copy of the Python 2.4 version of
+        :meth:`RawConfigParser._read <configparser.RawConfigParser._read>`, to ensure it
+        uses ordered dicts.
+
+        The ordering bug was fixed in Python 2.4, and dict itself keeps ordering since
+        Python 3.7. This has some other changes, especially that it ignores initial
+        whitespace, since git uses tabs. (Big comments are removed to be more compact.)
+        """
+        cursect = None  # None, or a dictionary.
+        optname = None
+        lineno = 0
+        is_multi_line = False
+        e = None  # None, or an exception.
+
+        def string_decode(v: str) -> str:
+            if v and v.endswith("\\"):
+                v = v[:-1]
+            # END cut trailing escapes to prevent decode error
+
+            return v.encode(defenc).decode("unicode_escape")
+
+        # END string_decode
+
+        while True:
+            # We assume to read binary!
+            line = fp.readline().decode(defenc)
+            if not line:
+                break
+            lineno = lineno + 1
+            # Comment or blank line?
+            if line.strip() == "" or self.re_comment.match(line):
+                continue
+            if line.split(None, 1)[0].lower() == "rem" and line[0] in "rR":
+                # No leading whitespace.
+                continue
+
+            # Is it a section header?
+            mo = self.SECTCRE.match(line.strip())
+            if not is_multi_line and mo:
+                sectname: str = mo.group("header").strip()
+                if sectname in self._sections:
+                    cursect = self._sections[sectname]
+                elif sectname == cp.DEFAULTSECT:
+                    cursect = self._defaults
+                else:
+                    cursect = self._dict((("__name__", sectname),))
+                    self._sections[sectname] = cursect
+                    self._proxies[sectname] = None
+                # So sections can't start with a continuation line.
+                optname = None
+            # No section header in the file?
+            elif cursect is None:
+                raise cp.MissingSectionHeaderError(fpname, lineno, line)
+            # An option line?
+            elif not is_multi_line:
+                mo = self.OPTCRE.match(line)
+                if mo:
+                    # We might just have handled the last line, which could contain a quotation we want to remove.
+                    optname, vi, optval = mo.group("option", "vi", "value")
+                    optname = self.optionxform(optname.rstrip())
+
+                    if vi in ("=", ":") and ";" in optval and not optval.strip().startswith('"'):
+                        pos = optval.find(";")
+                        if pos != -1 and optval[pos - 1].isspace():
+                            optval = optval[:pos]
+                    optval = optval.strip()
+
+                    if len(optval) < 2 or optval[0] != '"':
+                        # Does not open quoting.
+                        pass
+                    elif optval[-1] != '"':
+                        # Opens quoting and does not close: appears to start multi-line quoting.
+                        is_multi_line = True
+                        optval = string_decode(optval[1:])
+                    elif optval.find("\\", 1, -1) == -1 and optval.find('"', 1, -1) == -1:
+                        # Opens and closes quoting. Single line, and all we need is quote removal.
+                        optval = optval[1:-1]
+                    # TODO: Handle other quoted content, especially well-formed backslash escapes.
+
+                    # Preserves multiple values for duplicate optnames.
+                    cursect.add(optname, optval)
+                else:
+                    # Check if it's an option with no value - it's just ignored by git.
+                    if not self.OPTVALUEONLY.match(line):
+                        if not e:
+                            e = cp.ParsingError(fpname)
+                        e.append(lineno, repr(line))
+                    continue
+            else:
+                line = line.rstrip()
+                if line.endswith('"'):
+                    is_multi_line = False
+                    line = line[:-1]
+                # END handle quotations
+                optval = cursect.getlast(optname)
+                cursect.setlast(optname, optval + string_decode(line))
+            # END parse section or option
+        # END while reading
+
+        # If any parsing errors occurred, raise an exception.
+        if e:
+            raise e
+
+    def _has_includes(self) -> Union[bool, int]:
+        return self._merge_includes and len(self._included_paths())
+
+    def _included_paths(self) -> List[Tuple[str, str]]:
+        """List all paths that must be included to configuration.
+
+        :return:
+            The list of paths, where each path is a tuple of (option, value).
+        """
+        paths = []
+
+        for section in self.sections():
+            if section == "include":
+                paths += self.items(section)
+
+            match = CONDITIONAL_INCLUDE_REGEXP.search(section)
+            if match is None or self._repo is None:
+                continue
+
+            keyword = match.group(1)
+            value = match.group(2).strip()
+
+            if keyword in ["gitdir", "gitdir/i"]:
+                value = osp.expanduser(value)
+
+                if not any(value.startswith(s) for s in ["./", "/"]):
+                    value = "**/" + value
+                if value.endswith("/"):
+                    value += "**"
+
+                # Ensure that glob is always case insensitive if required.
+                if keyword.endswith("/i"):
+                    value = re.sub(
+                        r"[a-zA-Z]",
+                        lambda m: "[{}{}]".format(m.group().lower(), m.group().upper()),
+                        value,
+                    )
+                if self._repo.git_dir:
+                    if fnmatch.fnmatchcase(str(self._repo.git_dir), value):
+                        paths += self.items(section)
+
+            elif keyword == "onbranch":
+                try:
+                    branch_name = self._repo.active_branch.name
+                except TypeError:
+                    # Ignore section if active branch cannot be retrieved.
+                    continue
+
+                if fnmatch.fnmatchcase(branch_name, value):
+                    paths += self.items(section)
+
+        return paths
+
+    def read(self) -> None:  # type: ignore[override]
+        """Read the data stored in the files we have been initialized with.
+
+        This will ignore files that cannot be read, possibly leaving an empty
+        configuration.
+
+        :raise IOError:
+            If a file cannot be handled.
+        """
+        if self._is_initialized:
+            return
+        self._is_initialized = True
+
+        files_to_read: List[Union[PathLike, IO]] = [""]
+        if isinstance(self._file_or_files, (str, os.PathLike)):
+            # For str or Path, as str is a type of Sequence.
+            files_to_read = [self._file_or_files]
+        elif not isinstance(self._file_or_files, (tuple, list, Sequence)):
+            # Could merge with above isinstance once runtime type known.
+            files_to_read = [self._file_or_files]
+        else:  # For lists or tuples.
+            files_to_read = list(self._file_or_files)
+        # END ensure we have a copy of the paths to handle
+
+        seen = set(files_to_read)
+        num_read_include_files = 0
+        while files_to_read:
+            file_path = files_to_read.pop(0)
+            file_ok = False
+
+            if hasattr(file_path, "seek"):
+                # Must be a file-object.
+                # TODO: Replace cast with assert to narrow type, once sure.
+                file_path = cast(IO[bytes], file_path)
+                self._read(file_path, file_path.name)
+            else:
+                # Assume a path if it is not a file-object.
+                file_path = cast(PathLike, file_path)
+                try:
+                    with open(file_path, "rb") as fp:
+                        file_ok = True
+                        self._read(fp, fp.name)
+                except IOError:
+                    continue
+
+            # Read includes and append those that we didn't handle yet. We expect all
+            # paths to be normalized and absolute (and will ensure that is the case).
+            if self._has_includes():
+                for _, include_path in self._included_paths():
+                    if include_path.startswith("~"):
+                        include_path = osp.expanduser(include_path)
+                    if not osp.isabs(include_path):
+                        if not file_ok:
+                            continue
+                        # END ignore relative paths if we don't know the configuration file path
+                        file_path = cast(PathLike, file_path)
+                        assert osp.isabs(file_path), "Need absolute paths to be sure our cycle checks will work"
+                        include_path = osp.join(osp.dirname(file_path), include_path)
+                    # END make include path absolute
+                    include_path = osp.normpath(include_path)
+                    if include_path in seen or not os.access(include_path, os.R_OK):
+                        continue
+                    seen.add(include_path)
+                    # Insert included file to the top to be considered first.
+                    files_to_read.insert(0, include_path)
+                    num_read_include_files += 1
+                # END each include path in configuration file
+            # END handle includes
+        # END for each file object to read
+
+        # If there was no file included, we can safely write back (potentially) the
+        # configuration file without altering its meaning.
+        if num_read_include_files == 0:
+            self._merge_includes = False
+
+    def _write(self, fp: IO) -> None:
+        """Write an .ini-format representation of the configuration state in
+        git compatible format."""
+
+        def write_section(name: str, section_dict: _OMD) -> None:
+            fp.write(("[%s]\n" % name).encode(defenc))
+
+            values: Sequence[str]  # Runtime only gets str in tests, but should be whatever _OMD stores.
+            v: str
+            for key, values in section_dict.items_all():
+                if key == "__name__":
+                    continue
+
+                for v in values:
+                    fp.write(("\t%s = %s\n" % (key, self._value_to_string(v).replace("\n", "\n\t"))).encode(defenc))
+                # END if key is not __name__
+
+        # END section writing
+
+        if self._defaults:
+            write_section(cp.DEFAULTSECT, self._defaults)
+        value: _OMD
+
+        for name, value in self._sections.items():
+            write_section(name, value)
+
+    def items(self, section_name: str) -> List[Tuple[str, str]]:  # type: ignore[override]
+        """:return: list((option, value), ...) pairs of all items in the given section"""
+        return [(k, v) for k, v in super().items(section_name) if k != "__name__"]
+
+    def items_all(self, section_name: str) -> List[Tuple[str, List[str]]]:
+        """:return: list((option, [values...]), ...) pairs of all items in the given section"""
+        rv = _OMD(self._defaults)
+
+        for k, vs in self._sections[section_name].items_all():
+            if k == "__name__":
+                continue
+
+            if k in rv and rv.getall(k) == vs:
+                continue
+
+            for v in vs:
+                rv.add(k, v)
+
+        return rv.items_all()
+
+    @needs_values
+    def write(self) -> None:
+        """Write changes to our file, if there are changes at all.
+
+        :raise IOError:
+            If this is a read-only writer instance or if we could not obtain a file
+            lock.
+        """
+        self._assure_writable("write")
+        if not self._dirty:
+            return
+
+        if isinstance(self._file_or_files, (list, tuple)):
+            raise AssertionError(
+                "Cannot write back if there is not exactly a single file to write to, have %i files"
+                % len(self._file_or_files)
+            )
+        # END assert multiple files
+
+        if self._has_includes():
+            _logger.debug(
+                "Skipping write-back of configuration file as include files were merged in."
+                + "Set merge_includes=False to prevent this."
+            )
+            return
+        # END stop if we have include files
+
+        fp = self._file_or_files
+
+        # We have a physical file on disk, so get a lock.
+        is_file_lock = isinstance(fp, (str, os.PathLike, IOBase))  # TODO: Use PathLike (having dropped 3.5).
+        if is_file_lock and self._lock is not None:  # Else raise error?
+            self._lock._obtain_lock()
+
+        if not hasattr(fp, "seek"):
+            fp = cast(PathLike, fp)
+            with open(fp, "wb") as fp_open:
+                self._write(fp_open)
+        else:
+            fp = cast("BytesIO", fp)
+            fp.seek(0)
+            # Make sure we do not overwrite into an existing file.
+            if hasattr(fp, "truncate"):
+                fp.truncate()
+            self._write(fp)
+
+    def _assure_writable(self, method_name: str) -> None:
+        if self.read_only:
+            raise IOError("Cannot execute non-constant method %s.%s" % (self, method_name))
+
+    def add_section(self, section: str) -> None:
+        """Assures added options will stay in order."""
+        return super().add_section(section)
+
+    @property
+    def read_only(self) -> bool:
+        """:return: ``True`` if this instance may change the configuration file"""
+        return self._read_only
+
+    # FIXME: Figure out if default or return type can really include bool.
+    def get_value(
+        self,
+        section: str,
+        option: str,
+        default: Union[int, float, str, bool, None] = None,
+    ) -> Union[int, float, str, bool]:
+        """Get an option's value.
+
+        If multiple values are specified for this option in the section, the last one
+        specified is returned.
+
+        :param default:
+            If not ``None``, the given default value will be returned in case the option
+            did not exist.
+
+        :return:
+            A properly typed value, either int, float or string
+
+        :raise TypeError:
+            In case the value could not be understood.
+            Otherwise the exceptions known to the ConfigParser will be raised.
+        """
+        try:
+            valuestr = self.get(section, option)
+        except Exception:
+            if default is not None:
+                return default
+            raise
+
+        return self._string_to_value(valuestr)
+
+    def get_values(
+        self,
+        section: str,
+        option: str,
+        default: Union[int, float, str, bool, None] = None,
+    ) -> List[Union[int, float, str, bool]]:
+        """Get an option's values.
+
+        If multiple values are specified for this option in the section, all are
+        returned.
+
+        :param default:
+            If not ``None``, a list containing the given default value will be returned
+            in case the option did not exist.
+
+        :return:
+            A list of properly typed values, either int, float or string
+
+        :raise TypeError:
+            In case the value could not be understood.
+            Otherwise the exceptions known to the ConfigParser will be raised.
+        """
+        try:
+            self.sections()
+            lst = self._sections[section].getall(option)
+        except Exception:
+            if default is not None:
+                return [default]
+            raise
+
+        return [self._string_to_value(valuestr) for valuestr in lst]
+
+    def _string_to_value(self, valuestr: str) -> Union[int, float, str, bool]:
+        types = (int, float)
+        for numtype in types:
+            try:
+                val = numtype(valuestr)
+                # truncated value ?
+                if val != float(valuestr):
+                    continue
+                return val
+            except (ValueError, TypeError):
+                continue
+        # END for each numeric type
+
+        # Try boolean values as git uses them.
+        vl = valuestr.lower()
+        if vl == "false":
+            return False
+        if vl == "true":
+            return True
+
+        if not isinstance(valuestr, str):
+            raise TypeError(
+                "Invalid value type: only int, long, float and str are allowed",
+                valuestr,
+            )
+
+        return valuestr
+
+    def _value_to_string(self, value: Union[str, bytes, int, float, bool]) -> str:
+        if isinstance(value, (int, float, bool)):
+            return str(value)
+        return force_text(value)
+
+    @needs_values
+    @set_dirty_and_flush_changes
+    def set_value(self, section: str, option: str, value: Union[str, bytes, int, float, bool]) -> "GitConfigParser":
+        """Set the given option in section to the given value.
+
+        This will create the section if required, and will not throw as opposed to the
+        default ConfigParser ``set`` method.
+
+        :param section:
+            Name of the section in which the option resides or should reside.
+
+        :param option:
+            Name of the options whose value to set.
+
+        :param value:
+            Value to set the option to. It must be a string or convertible to a string.
+
+        :return:
+            This instance
+        """
+        if not self.has_section(section):
+            self.add_section(section)
+        self.set(section, option, self._value_to_string(value))
+        return self
+
+    @needs_values
+    @set_dirty_and_flush_changes
+    def add_value(self, section: str, option: str, value: Union[str, bytes, int, float, bool]) -> "GitConfigParser":
+        """Add a value for the given option in section.
+
+        This will create the section if required, and will not throw as opposed to the
+        default ConfigParser ``set`` method. The value becomes the new value of the
+        option as returned by :meth:`get_value`, and appends to the list of values
+        returned by :meth:`get_values`.
+
+        :param section:
+            Name of the section in which the option resides or should reside.
+
+        :param option:
+            Name of the option.
+
+        :param value:
+            Value to add to option. It must be a string or convertible to a string.
+
+        :return:
+            This instance
+        """
+        if not self.has_section(section):
+            self.add_section(section)
+        self._sections[section].add(option, self._value_to_string(value))
+        return self
+
+    def rename_section(self, section: str, new_name: str) -> "GitConfigParser":
+        """Rename the given section to `new_name`.
+
+        :raise ValueError:
+            If:
+
+            * `section` doesn't exist.
+            * A section with `new_name` does already exist.
+
+        :return:
+            This instance
+        """
+        if not self.has_section(section):
+            raise ValueError("Source section '%s' doesn't exist" % section)
+        if self.has_section(new_name):
+            raise ValueError("Destination section '%s' already exists" % new_name)
+
+        super().add_section(new_name)
+        new_section = self._sections[new_name]
+        for k, vs in self.items_all(section):
+            new_section.setall(k, vs)
+        # END for each value to copy
+
+        # This call writes back the changes, which is why we don't have the respective
+        # decorator.
+        self.remove_section(section)
+        return self

.venv/lib/python3.11/site-packages/git/db.py

@@ -0,0 +1,71 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Module with our own gitdb implementation - it uses the git command."""
+
+__all__ = ["GitCmdObjectDB", "GitDB"]
+
+from gitdb.base import OInfo, OStream
+from gitdb.db import GitDB, LooseObjectDB
+from gitdb.exc import BadObject
+
+from git.util import bin_to_hex, hex_to_bin
+from git.exc import GitCommandError
+
+# typing-------------------------------------------------
+
+from typing import TYPE_CHECKING
+
+from git.types import PathLike
+
+if TYPE_CHECKING:
+    from git.cmd import Git
+
+# --------------------------------------------------------
+
+
+class GitCmdObjectDB(LooseObjectDB):
+    """A database representing the default git object store, which includes loose
+    objects, pack files and an alternates file.
+
+    It will create objects only in the loose object database.
+    """
+
+    def __init__(self, root_path: PathLike, git: "Git") -> None:
+        """Initialize this instance with the root and a git command."""
+        super().__init__(root_path)
+        self._git = git
+
+    def info(self, binsha: bytes) -> OInfo:
+        """Get a git object header (using git itself)."""
+        hexsha, typename, size = self._git.get_object_header(bin_to_hex(binsha))
+        return OInfo(hex_to_bin(hexsha), typename, size)
+
+    def stream(self, binsha: bytes) -> OStream:
+        """Get git object data as a stream supporting ``read()`` (using git itself)."""
+        hexsha, typename, size, stream = self._git.stream_object_data(bin_to_hex(binsha))
+        return OStream(hex_to_bin(hexsha), typename, size, stream)
+
+    # { Interface
+
+    def partial_to_complete_sha_hex(self, partial_hexsha: str) -> bytes:
+        """
+        :return:
+            Full binary 20 byte sha from the given partial hexsha
+
+        :raise gitdb.exc.AmbiguousObjectName:
+
+        :raise gitdb.exc.BadObject:
+
+        :note:
+            Currently we only raise :exc:`~gitdb.exc.BadObject` as git does not
+            communicate ambiguous objects separately.
+        """
+        try:
+            hexsha, _typename, _size = self._git.get_object_header(partial_hexsha)
+            return hex_to_bin(hexsha)
+        except (GitCommandError, ValueError) as e:
+            raise BadObject(partial_hexsha) from e
+        # END handle exceptions
+
+    # } END interface

.venv/lib/python3.11/site-packages/git/diff.py

@@ -0,0 +1,775 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+__all__ = ["DiffConstants", "NULL_TREE", "INDEX", "Diffable", "DiffIndex", "Diff"]
+
+import enum
+import re
+import warnings
+
+from git.cmd import handle_process_output
+from git.compat import defenc
+from git.objects.blob import Blob
+from git.objects.util import mode_str_to_int
+from git.util import finalize_process, hex_to_bin
+
+# typing ------------------------------------------------------------------
+
+from typing import (
+    Any,
+    Iterator,
+    List,
+    Match,
+    Optional,
+    Tuple,
+    TYPE_CHECKING,
+    TypeVar,
+    Union,
+    cast,
+)
+from git.types import Literal, PathLike
+
+if TYPE_CHECKING:
+    from subprocess import Popen
+
+    from git.cmd import Git
+    from git.objects.base import IndexObject
+    from git.objects.commit import Commit
+    from git.objects.tree import Tree
+    from git.repo.base import Repo
+
+Lit_change_type = Literal["A", "D", "C", "M", "R", "T", "U"]
+
+# ------------------------------------------------------------------------
+
+
+@enum.unique
+class DiffConstants(enum.Enum):
+    """Special objects for :meth:`Diffable.diff`.
+
+    See the :meth:`Diffable.diff` method's ``other`` parameter, which accepts various
+    values including these.
+
+    :note:
+        These constants are also available as attributes of the :mod:`git.diff` module,
+        the :class:`Diffable` class and its subclasses and instances, and the top-level
+        :mod:`git` module.
+    """
+
+    NULL_TREE = enum.auto()
+    """Stand-in indicating you want to compare against the empty tree in diffs.
+
+    Also accessible as :const:`git.NULL_TREE`, :const:`git.diff.NULL_TREE`, and
+    :const:`Diffable.NULL_TREE`.
+    """
+
+    INDEX = enum.auto()
+    """Stand-in indicating you want to diff against the index.
+
+    Also accessible as :const:`git.INDEX`, :const:`git.diff.INDEX`, and
+    :const:`Diffable.INDEX`, as well as :const:`Diffable.Index`. The latter has been
+    kept for backward compatibility and made an alias of this, so it may still be used.
+    """
+
+
+NULL_TREE: Literal[DiffConstants.NULL_TREE] = DiffConstants.NULL_TREE
+"""Stand-in indicating you want to compare against the empty tree in diffs.
+
+See :meth:`Diffable.diff`, which accepts this as a value of its ``other`` parameter.
+
+This is an alias of :const:`DiffConstants.NULL_TREE`, which may also be accessed as
+:const:`git.NULL_TREE` and :const:`Diffable.NULL_TREE`.
+"""
+
+INDEX: Literal[DiffConstants.INDEX] = DiffConstants.INDEX
+"""Stand-in indicating you want to diff against the index.
+
+See :meth:`Diffable.diff`, which accepts this as a value of its ``other`` parameter.
+
+This is an alias of :const:`DiffConstants.INDEX`, which may also be accessed as
+:const:`git.INDEX` and :const:`Diffable.INDEX`, as well as :const:`Diffable.Index`.
+"""
+
+_octal_byte_re = re.compile(rb"\\([0-9]{3})")
+
+
+def _octal_repl(matchobj: Match) -> bytes:
+    value = matchobj.group(1)
+    value = int(value, 8)
+    value = bytes(bytearray((value,)))
+    return value
+
+
+def decode_path(path: bytes, has_ab_prefix: bool = True) -> Optional[bytes]:
+    if path == b"/dev/null":
+        return None
+
+    if path.startswith(b'"') and path.endswith(b'"'):
+        path = path[1:-1].replace(b"\\n", b"\n").replace(b"\\t", b"\t").replace(b'\\"', b'"').replace(b"\\\\", b"\\")
+
+    path = _octal_byte_re.sub(_octal_repl, path)
+
+    if has_ab_prefix:
+        assert path.startswith(b"a/") or path.startswith(b"b/")
+        path = path[2:]
+
+    return path
+
+
+class Diffable:
+    """Common interface for all objects that can be diffed against another object of
+    compatible type.
+
+    :note:
+        Subclasses require a :attr:`repo` member, as it is the case for
+        :class:`~git.objects.base.Object` instances. For practical reasons we do not
+        derive from :class:`~git.objects.base.Object`.
+    """
+
+    __slots__ = ()
+
+    repo: "Repo"
+    """Repository to operate on. Must be provided by subclass or sibling class."""
+
+    NULL_TREE = NULL_TREE
+    """Stand-in indicating you want to compare against the empty tree in diffs.
+
+    See the :meth:`diff` method, which accepts this as a value of its ``other``
+    parameter.
+
+    This is the same as :const:`DiffConstants.NULL_TREE`, and may also be accessed as
+    :const:`git.NULL_TREE` and :const:`git.diff.NULL_TREE`.
+    """
+
+    INDEX = INDEX
+    """Stand-in indicating you want to diff against the index.
+
+    See the :meth:`diff` method, which accepts this as a value of its ``other``
+    parameter.
+
+    This is the same as :const:`DiffConstants.INDEX`, and may also be accessed as
+    :const:`git.INDEX` and :const:`git.diff.INDEX`, as well as :class:`Diffable.INDEX`,
+    which is kept for backward compatibility (it is now defined an alias of this).
+    """
+
+    Index = INDEX
+    """Stand-in indicating you want to diff against the index
+    (same as :const:`~Diffable.INDEX`).
+
+    This is an alias of :const:`~Diffable.INDEX`, for backward compatibility. See
+    :const:`~Diffable.INDEX` and :meth:`diff` for details.
+
+    :note:
+        Although always meant for use as an opaque constant, this was formerly defined
+        as a class. Its usage is unchanged, but static type annotations that attempt
+        to permit only this object must be changed to avoid new mypy errors. This was
+        previously not possible to do, though ``Type[Diffable.Index]`` approximated it.
+        It is now possible to do precisely, using ``Literal[DiffConstants.INDEX]``.
+    """
+
+    def _process_diff_args(
+        self,
+        args: List[Union[PathLike, "Diffable"]],
+    ) -> List[Union[PathLike, "Diffable"]]:
+        """
+        :return:
+            Possibly altered version of the given args list.
+            This method is called right before git command execution.
+            Subclasses can use it to alter the behaviour of the superclass.
+        """
+        return args
+
+    def diff(
+        self,
+        other: Union[DiffConstants, "Tree", "Commit", str, None] = INDEX,
+        paths: Union[PathLike, List[PathLike], Tuple[PathLike, ...], None] = None,
+        create_patch: bool = False,
+        **kwargs: Any,
+    ) -> "DiffIndex[Diff]":
+        """Create diffs between two items being trees, trees and index or an index and
+        the working tree. Detects renames automatically.
+
+        :param other:
+            This the item to compare us with.
+
+            * If ``None``, we will be compared to the working tree.
+
+            * If a :class:`~git.types.Tree_ish` or string, it will be compared against
+              the respective tree.
+
+            * If :const:`INDEX`, it will be compared against the index.
+
+            * If :const:`NULL_TREE`, it will compare against the empty tree.
+
+            This parameter defaults to :const:`INDEX` (rather than ``None``) so that the
+            method will not by default fail on bare repositories.
+
+        :param paths:
+            This a list of paths or a single path to limit the diff to. It will only
+            include at least one of the given path or paths.
+
+        :param create_patch:
+            If ``True``, the returned :class:`Diff` contains a detailed patch that if
+            applied makes the self to other. Patches are somewhat costly as blobs have
+            to be read and diffed.
+
+        :param kwargs:
+            Additional arguments passed to :manpage:`git-diff(1)`, such as ``R=True`` to
+            swap both sides of the diff.
+
+        :return:
+            A :class:`DiffIndex` representing the computed diff.
+
+        :note:
+            On a bare repository, `other` needs to be provided as :const:`INDEX`, or as
+            an instance of :class:`~git.objects.tree.Tree` or
+            :class:`~git.objects.commit.Commit`, or a git command error will occur.
+        """
+        args: List[Union[PathLike, Diffable]] = []
+        args.append("--abbrev=40")  # We need full shas.
+        args.append("--full-index")  # Get full index paths, not only filenames.
+
+        # Remove default '-M' arg (check for renames) if user is overriding it.
+        if not any(x in kwargs for x in ("find_renames", "no_renames", "M")):
+            args.append("-M")
+
+        if create_patch:
+            args.append("-p")
+            args.append("--no-ext-diff")
+        else:
+            args.append("--raw")
+            args.append("-z")
+
+        # Ensure we never see colored output.
+        # Fixes: https://github.com/gitpython-developers/GitPython/issues/172
+        args.append("--no-color")
+
+        if paths is not None and not isinstance(paths, (tuple, list)):
+            paths = [paths]
+
+        diff_cmd = self.repo.git.diff
+        if other is INDEX:
+            args.insert(0, "--cached")
+        elif other is NULL_TREE:
+            args.insert(0, "-r")  # Recursive diff-tree.
+            args.insert(0, "--root")
+            diff_cmd = self.repo.git.diff_tree
+        elif other is not None:
+            args.insert(0, "-r")  # Recursive diff-tree.
+            args.insert(0, other)
+            diff_cmd = self.repo.git.diff_tree
+
+        args.insert(0, self)
+
+        # paths is a list or tuple here, or None.
+        if paths:
+            args.append("--")
+            args.extend(paths)
+        # END paths handling
+
+        kwargs["as_process"] = True
+        proc = diff_cmd(*self._process_diff_args(args), **kwargs)
+
+        diff_method = Diff._index_from_patch_format if create_patch else Diff._index_from_raw_format
+        index = diff_method(self.repo, proc)
+
+        proc.wait()
+        return index
+
+
+T_Diff = TypeVar("T_Diff", bound="Diff")
+
+
+class DiffIndex(List[T_Diff]):
+    R"""An index for diffs, allowing a list of :class:`Diff`\s to be queried by the diff
+    properties.
+
+    The class improves the diff handling convenience.
+    """
+
+    change_type = ("A", "C", "D", "R", "M", "T")
+    """Change type invariant identifying possible ways a blob can have changed:
+
+    * ``A`` = Added
+    * ``D`` = Deleted
+    * ``R`` = Renamed
+    * ``M`` = Modified
+    * ``T`` = Changed in the type
+    """
+
+    def iter_change_type(self, change_type: Lit_change_type) -> Iterator[T_Diff]:
+        """
+        :return:
+            Iterator yielding :class:`Diff` instances that match the given `change_type`
+
+        :param change_type:
+            Member of :attr:`DiffIndex.change_type`, namely:
+
+            * 'A' for added paths
+            * 'D' for deleted paths
+            * 'R' for renamed paths
+            * 'M' for paths with modified data
+            * 'T' for changed in the type paths
+        """
+        if change_type not in self.change_type:
+            raise ValueError("Invalid change type: %s" % change_type)
+
+        for diffidx in self:
+            if diffidx.change_type == change_type:
+                yield diffidx
+            elif change_type == "A" and diffidx.new_file:
+                yield diffidx
+            elif change_type == "D" and diffidx.deleted_file:
+                yield diffidx
+            elif change_type == "C" and diffidx.copied_file:
+                yield diffidx
+            elif change_type == "R" and diffidx.renamed_file:
+                yield diffidx
+            elif change_type == "M" and diffidx.a_blob and diffidx.b_blob and diffidx.a_blob != diffidx.b_blob:
+                yield diffidx
+        # END for each diff
+
+
+class Diff:
+    """A Diff contains diff information between two Trees.
+
+    It contains two sides a and b of the diff. Members are prefixed with "a" and "b"
+    respectively to indicate that.
+
+    Diffs keep information about the changed blob objects, the file mode, renames,
+    deletions and new files.
+
+    There are a few cases where ``None`` has to be expected as member variable value:
+
+    New File::
+
+        a_mode is None
+        a_blob is None
+        a_path is None
+
+    Deleted File::
+
+        b_mode is None
+        b_blob is None
+        b_path is None
+
+    Working Tree Blobs:
+
+        When comparing to working trees, the working tree blob will have a null hexsha
+        as a corresponding object does not yet exist. The mode will be null as well. The
+        path will be available, though.
+
+        If it is listed in a diff, the working tree version of the file must differ from
+        the version in the index or tree, and hence has been modified.
+    """
+
+    # Precompiled regex.
+    re_header = re.compile(
+        rb"""
+                                ^diff[ ]--git
+                                    [ ](?P<a_path_fallback>"?[ab]/.+?"?)[ ](?P<b_path_fallback>"?[ab]/.+?"?)\n
+                                (?:^old[ ]mode[ ](?P<old_mode>\d+)\n
+                                   ^new[ ]mode[ ](?P<new_mode>\d+)(?:\n|$))?
+                                (?:^similarity[ ]index[ ]\d+%\n
+                                   ^rename[ ]from[ ](?P<rename_from>.*)\n
+                                   ^rename[ ]to[ ](?P<rename_to>.*)(?:\n|$))?
+                                (?:^new[ ]file[ ]mode[ ](?P<new_file_mode>.+)(?:\n|$))?
+                                (?:^deleted[ ]file[ ]mode[ ](?P<deleted_file_mode>.+)(?:\n|$))?
+                                (?:^similarity[ ]index[ ]\d+%\n
+                                   ^copy[ ]from[ ].*\n
+                                   ^copy[ ]to[ ](?P<copied_file_name>.*)(?:\n|$))?
+                                (?:^index[ ](?P<a_blob_id>[0-9A-Fa-f]+)
+                                    \.\.(?P<b_blob_id>[0-9A-Fa-f]+)[ ]?(?P<b_mode>.+)?(?:\n|$))?
+                                (?:^---[ ](?P<a_path>[^\t\n\r\f\v]*)[\t\r\f\v]*(?:\n|$))?
+                                (?:^\+\+\+[ ](?P<b_path>[^\t\n\r\f\v]*)[\t\r\f\v]*(?:\n|$))?
+                            """,
+        re.VERBOSE | re.MULTILINE,
+    )
+
+    # These can be used for comparisons.
+    NULL_HEX_SHA = "0" * 40
+    NULL_BIN_SHA = b"\0" * 20
+
+    __slots__ = (
+        "a_blob",
+        "b_blob",
+        "a_mode",
+        "b_mode",
+        "a_rawpath",
+        "b_rawpath",
+        "new_file",
+        "deleted_file",
+        "copied_file",
+        "raw_rename_from",
+        "raw_rename_to",
+        "diff",
+        "change_type",
+        "score",
+    )
+
+    def __init__(
+        self,
+        repo: "Repo",
+        a_rawpath: Optional[bytes],
+        b_rawpath: Optional[bytes],
+        a_blob_id: Union[str, bytes, None],
+        b_blob_id: Union[str, bytes, None],
+        a_mode: Union[bytes, str, None],
+        b_mode: Union[bytes, str, None],
+        new_file: bool,
+        deleted_file: bool,
+        copied_file: bool,
+        raw_rename_from: Optional[bytes],
+        raw_rename_to: Optional[bytes],
+        diff: Union[str, bytes, None],
+        change_type: Optional[Lit_change_type],
+        score: Optional[int],
+    ) -> None:
+        assert a_rawpath is None or isinstance(a_rawpath, bytes)
+        assert b_rawpath is None or isinstance(b_rawpath, bytes)
+        self.a_rawpath = a_rawpath
+        self.b_rawpath = b_rawpath
+
+        self.a_mode = mode_str_to_int(a_mode) if a_mode else None
+        self.b_mode = mode_str_to_int(b_mode) if b_mode else None
+
+        # Determine whether this diff references a submodule. If it does then
+        # we need to overwrite "repo" to the corresponding submodule's repo instead.
+        if repo and a_rawpath:
+            for submodule in repo.submodules:
+                if submodule.path == a_rawpath.decode(defenc, "replace"):
+                    if submodule.module_exists():
+                        repo = submodule.module()
+                    break
+
+        self.a_blob: Union["IndexObject", None]
+        if a_blob_id is None or a_blob_id == self.NULL_HEX_SHA:
+            self.a_blob = None
+        else:
+            self.a_blob = Blob(repo, hex_to_bin(a_blob_id), mode=self.a_mode, path=self.a_path)
+
+        self.b_blob: Union["IndexObject", None]
+        if b_blob_id is None or b_blob_id == self.NULL_HEX_SHA:
+            self.b_blob = None
+        else:
+            self.b_blob = Blob(repo, hex_to_bin(b_blob_id), mode=self.b_mode, path=self.b_path)
+
+        self.new_file: bool = new_file
+        self.deleted_file: bool = deleted_file
+        self.copied_file: bool = copied_file
+
+        # Be clear and use None instead of empty strings.
+        assert raw_rename_from is None or isinstance(raw_rename_from, bytes)
+        assert raw_rename_to is None or isinstance(raw_rename_to, bytes)
+        self.raw_rename_from = raw_rename_from or None
+        self.raw_rename_to = raw_rename_to or None
+
+        self.diff = diff
+        self.change_type: Union[Lit_change_type, None] = change_type
+        self.score = score
+
+    def __eq__(self, other: object) -> bool:
+        for name in self.__slots__:
+            if getattr(self, name) != getattr(other, name):
+                return False
+        # END for each name
+        return True
+
+    def __ne__(self, other: object) -> bool:
+        return not (self == other)
+
+    def __hash__(self) -> int:
+        return hash(tuple(getattr(self, n) for n in self.__slots__))
+
+    def __str__(self) -> str:
+        h = "%s"
+        if self.a_blob:
+            h %= self.a_blob.path
+        elif self.b_blob:
+            h %= self.b_blob.path
+
+        msg = ""
+        line = None
+        line_length = 0
+        for b, n in zip((self.a_blob, self.b_blob), ("lhs", "rhs")):
+            if b:
+                line = "\n%s: %o | %s" % (n, b.mode, b.hexsha)
+            else:
+                line = "\n%s: None" % n
+            # END if blob is not None
+            line_length = max(len(line), line_length)
+            msg += line
+        # END for each blob
+
+        # Add headline.
+        h += "\n" + "=" * line_length
+
+        if self.deleted_file:
+            msg += "\nfile deleted in rhs"
+        if self.new_file:
+            msg += "\nfile added in rhs"
+        if self.copied_file:
+            msg += "\nfile %r copied from %r" % (self.b_path, self.a_path)
+        if self.rename_from:
+            msg += "\nfile renamed from %r" % self.rename_from
+        if self.rename_to:
+            msg += "\nfile renamed to %r" % self.rename_to
+        if self.diff:
+            msg += "\n---"
+            try:
+                msg += self.diff.decode(defenc) if isinstance(self.diff, bytes) else self.diff
+            except UnicodeDecodeError:
+                msg += "OMITTED BINARY DATA"
+            # END handle encoding
+            msg += "\n---"
+        # END diff info
+
+        return h + msg
+
+    @property
+    def a_path(self) -> Optional[str]:
+        return self.a_rawpath.decode(defenc, "replace") if self.a_rawpath else None
+
+    @property
+    def b_path(self) -> Optional[str]:
+        return self.b_rawpath.decode(defenc, "replace") if self.b_rawpath else None
+
+    @property
+    def rename_from(self) -> Optional[str]:
+        return self.raw_rename_from.decode(defenc, "replace") if self.raw_rename_from else None
+
+    @property
+    def rename_to(self) -> Optional[str]:
+        return self.raw_rename_to.decode(defenc, "replace") if self.raw_rename_to else None
+
+    @property
+    def renamed(self) -> bool:
+        """Deprecated, use :attr:`renamed_file` instead.
+
+        :return:
+            ``True`` if the blob of our diff has been renamed
+
+        :note:
+            This property is deprecated.
+            Please use the :attr:`renamed_file` property instead.
+        """
+        warnings.warn(
+            "Diff.renamed is deprecated, use Diff.renamed_file instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.renamed_file
+
+    @property
+    def renamed_file(self) -> bool:
+        """:return: ``True`` if the blob of our diff has been renamed"""
+        return self.rename_from != self.rename_to
+
+    @classmethod
+    def _pick_best_path(cls, path_match: bytes, rename_match: bytes, path_fallback_match: bytes) -> Optional[bytes]:
+        if path_match:
+            return decode_path(path_match)
+
+        if rename_match:
+            return decode_path(rename_match, has_ab_prefix=False)
+
+        if path_fallback_match:
+            return decode_path(path_fallback_match)
+
+        return None
+
+    @classmethod
+    def _index_from_patch_format(cls, repo: "Repo", proc: Union["Popen", "Git.AutoInterrupt"]) -> DiffIndex["Diff"]:
+        """Create a new :class:`DiffIndex` from the given process output which must be
+        in patch format.
+
+        :param repo:
+            The repository we are operating on.
+
+        :param proc:
+            :manpage:`git-diff(1)` process to read from
+            (supports :class:`Git.AutoInterrupt <git.cmd.Git.AutoInterrupt>` wrapper).
+
+        :return:
+            :class:`DiffIndex`
+        """
+
+        # FIXME: Here SLURPING raw, need to re-phrase header-regexes linewise.
+        text_list: List[bytes] = []
+        handle_process_output(proc, text_list.append, None, finalize_process, decode_streams=False)
+
+        # For now, we have to bake the stream.
+        text = b"".join(text_list)
+        index: "DiffIndex" = DiffIndex()
+        previous_header: Union[Match[bytes], None] = None
+        header: Union[Match[bytes], None] = None
+        a_path, b_path = None, None  # For mypy.
+        a_mode, b_mode = None, None  # For mypy.
+        for _header in cls.re_header.finditer(text):
+            (
+                a_path_fallback,
+                b_path_fallback,
+                old_mode,
+                new_mode,
+                rename_from,
+                rename_to,
+                new_file_mode,
+                deleted_file_mode,
+                copied_file_name,
+                a_blob_id,
+                b_blob_id,
+                b_mode,
+                a_path,
+                b_path,
+            ) = _header.groups()
+
+            new_file, deleted_file, copied_file = (
+                bool(new_file_mode),
+                bool(deleted_file_mode),
+                bool(copied_file_name),
+            )
+
+            a_path = cls._pick_best_path(a_path, rename_from, a_path_fallback)
+            b_path = cls._pick_best_path(b_path, rename_to, b_path_fallback)
+
+            # Our only means to find the actual text is to see what has not been matched
+            # by our regex, and then retro-actively assign it to our index.
+            if previous_header is not None:
+                index[-1].diff = text[previous_header.end() : _header.start()]
+            # END assign actual diff
+
+            # Make sure the mode is set if the path is set. Otherwise the resulting blob
+            # is invalid. We just use the one mode we should have parsed.
+            a_mode = old_mode or deleted_file_mode or (a_path and (b_mode or new_mode or new_file_mode))
+            b_mode = b_mode or new_mode or new_file_mode or (b_path and a_mode)
+            index.append(
+                Diff(
+                    repo,
+                    a_path,
+                    b_path,
+                    a_blob_id and a_blob_id.decode(defenc),
+                    b_blob_id and b_blob_id.decode(defenc),
+                    a_mode and a_mode.decode(defenc),
+                    b_mode and b_mode.decode(defenc),
+                    new_file,
+                    deleted_file,
+                    copied_file,
+                    rename_from,
+                    rename_to,
+                    None,
+                    None,
+                    None,
+                )
+            )
+
+            previous_header = _header
+            header = _header
+        # END for each header we parse
+        if index and header:
+            index[-1].diff = text[header.end() :]
+        # END assign last diff
+
+        return index
+
+    @staticmethod
+    def _handle_diff_line(lines_bytes: bytes, repo: "Repo", index: DiffIndex["Diff"]) -> None:
+        lines = lines_bytes.decode(defenc)
+
+        # Discard everything before the first colon, and the colon itself.
+        _, _, lines = lines.partition(":")
+
+        for line in lines.split("\x00:"):
+            if not line:
+                # The line data is empty, skip.
+                continue
+            meta, _, path = line.partition("\x00")
+            path = path.rstrip("\x00")
+            a_blob_id: Optional[str]
+            b_blob_id: Optional[str]
+            old_mode, new_mode, a_blob_id, b_blob_id, _change_type = meta.split(None, 4)
+            # Change type can be R100
+            # R: status letter
+            # 100: score (in case of copy and rename)
+            change_type: Lit_change_type = cast(Lit_change_type, _change_type[0])
+            score_str = "".join(_change_type[1:])
+            score = int(score_str) if score_str.isdigit() else None
+            path = path.strip("\n")
+            a_path = path.encode(defenc)
+            b_path = path.encode(defenc)
+            deleted_file = False
+            new_file = False
+            copied_file = False
+            rename_from = None
+            rename_to = None
+
+            # NOTE: We cannot conclude from the existence of a blob to change type,
+            # as diffs with the working do not have blobs yet.
+            if change_type == "D":
+                b_blob_id = None  # Optional[str]
+                deleted_file = True
+            elif change_type == "A":
+                a_blob_id = None
+                new_file = True
+            elif change_type == "C":
+                copied_file = True
+                a_path_str, b_path_str = path.split("\x00", 1)
+                a_path = a_path_str.encode(defenc)
+                b_path = b_path_str.encode(defenc)
+            elif change_type == "R":
+                a_path_str, b_path_str = path.split("\x00", 1)
+                a_path = a_path_str.encode(defenc)
+                b_path = b_path_str.encode(defenc)
+                rename_from, rename_to = a_path, b_path
+            elif change_type == "T":
+                # Nothing to do.
+                pass
+            # END add/remove handling
+
+            diff = Diff(
+                repo,
+                a_path,
+                b_path,
+                a_blob_id,
+                b_blob_id,
+                old_mode,
+                new_mode,
+                new_file,
+                deleted_file,
+                copied_file,
+                rename_from,
+                rename_to,
+                "",
+                change_type,
+                score,
+            )
+            index.append(diff)
+
+    @classmethod
+    def _index_from_raw_format(cls, repo: "Repo", proc: "Popen") -> "DiffIndex[Diff]":
+        """Create a new :class:`DiffIndex` from the given process output which must be
+        in raw format.
+
+        :param repo:
+            The repository we are operating on.
+
+        :param proc:
+            Process to read output from.
+
+        :return:
+            :class:`DiffIndex`
+        """
+        # handles
+        # :100644 100644 687099101... 37c5e30c8... M    .gitignore
+
+        index: "DiffIndex" = DiffIndex()
+        handle_process_output(
+            proc,
+            lambda byt: cls._handle_diff_line(byt, repo, index),
+            None,
+            finalize_process,
+            decode_streams=False,
+        )
+
+        return index

.venv/lib/python3.11/site-packages/git/exc.py

@@ -0,0 +1,228 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Exceptions thrown throughout the git package."""
+
+__all__ = [
+    # Defined in gitdb.exc:
+    "AmbiguousObjectName",
+    "BadName",
+    "BadObject",
+    "BadObjectType",
+    "InvalidDBRoot",
+    "ODBError",
+    "ParseError",
+    "UnsupportedOperation",
+    # Introduced in this module:
+    "GitError",
+    "InvalidGitRepositoryError",
+    "WorkTreeRepositoryUnsupported",
+    "NoSuchPathError",
+    "UnsafeProtocolError",
+    "UnsafeOptionError",
+    "CommandError",
+    "GitCommandNotFound",
+    "GitCommandError",
+    "CheckoutError",
+    "CacheError",
+    "UnmergedEntriesError",
+    "HookExecutionError",
+    "RepositoryDirtyError",
+]
+
+from gitdb.exc import (
+    AmbiguousObjectName,
+    BadName,
+    BadObject,
+    BadObjectType,
+    InvalidDBRoot,
+    ODBError,
+    ParseError,
+    UnsupportedOperation,
+)
+
+from git.compat import safe_decode
+from git.util import remove_password_if_present
+
+# typing ----------------------------------------------------
+
+from typing import List, Sequence, Tuple, TYPE_CHECKING, Union
+
+from git.types import PathLike
+
+if TYPE_CHECKING:
+    from git.repo.base import Repo
+
+# ------------------------------------------------------------------
+
+
+class GitError(Exception):
+    """Base class for all package exceptions."""
+
+
+class InvalidGitRepositoryError(GitError):
+    """Thrown if the given repository appears to have an invalid format."""
+
+
+class WorkTreeRepositoryUnsupported(InvalidGitRepositoryError):
+    """Thrown to indicate we can't handle work tree repositories."""
+
+
+class NoSuchPathError(GitError, OSError):
+    """Thrown if a path could not be access by the system."""
+
+
+class UnsafeProtocolError(GitError):
+    """Thrown if unsafe protocols are passed without being explicitly allowed."""
+
+
+class UnsafeOptionError(GitError):
+    """Thrown if unsafe options are passed without being explicitly allowed."""
+
+
+class CommandError(GitError):
+    """Base class for exceptions thrown at every stage of :class:`~subprocess.Popen`
+    execution.
+
+    :param command:
+        A non-empty list of argv comprising the command-line.
+    """
+
+    _msg = "Cmd('%s') failed%s"
+    """Format string with 2 ``%s`` for ``<cmdline>`` and the rest.
+
+    For example: ``"'%s' failed%s"``
+
+    Subclasses may override this attribute, provided it is still in this form.
+    """
+
+    def __init__(
+        self,
+        command: Union[List[str], Tuple[str, ...], str],
+        status: Union[str, int, None, Exception] = None,
+        stderr: Union[bytes, str, None] = None,
+        stdout: Union[bytes, str, None] = None,
+    ) -> None:
+        if not isinstance(command, (tuple, list)):
+            command = command.split()
+        self.command = remove_password_if_present(command)
+        self.status = status
+        if status:
+            if isinstance(status, Exception):
+                status = "%s('%s')" % (type(status).__name__, safe_decode(str(status)))
+            else:
+                try:
+                    status = "exit code(%s)" % int(status)
+                except (ValueError, TypeError):
+                    s = safe_decode(str(status))
+                    status = "'%s'" % s if isinstance(status, str) else s
+
+        self._cmd = safe_decode(self.command[0])
+        self._cmdline = " ".join(safe_decode(i) for i in self.command)
+        self._cause = status and " due to: %s" % status or "!"
+        stdout_decode = safe_decode(stdout)
+        stderr_decode = safe_decode(stderr)
+        self.stdout = stdout_decode and "\n  stdout: '%s'" % stdout_decode or ""
+        self.stderr = stderr_decode and "\n  stderr: '%s'" % stderr_decode or ""
+
+    def __str__(self) -> str:
+        return (self._msg + "\n  cmdline: %s%s%s") % (
+            self._cmd,
+            self._cause,
+            self._cmdline,
+            self.stdout,
+            self.stderr,
+        )
+
+
+class GitCommandNotFound(CommandError):
+    """Thrown if we cannot find the ``git`` executable in the :envvar:`PATH` or at the
+    path given by the :envvar:`GIT_PYTHON_GIT_EXECUTABLE` environment variable."""
+
+    def __init__(self, command: Union[List[str], Tuple[str], str], cause: Union[str, Exception]) -> None:
+        super().__init__(command, cause)
+        self._msg = "Cmd('%s') not found%s"
+
+
+class GitCommandError(CommandError):
+    """Thrown if execution of the git command fails with non-zero status code."""
+
+    def __init__(
+        self,
+        command: Union[List[str], Tuple[str, ...], str],
+        status: Union[str, int, None, Exception] = None,
+        stderr: Union[bytes, str, None] = None,
+        stdout: Union[bytes, str, None] = None,
+    ) -> None:
+        super().__init__(command, status, stderr, stdout)
+
+
+class CheckoutError(GitError):
+    """Thrown if a file could not be checked out from the index as it contained
+    changes.
+
+    The :attr:`failed_files` attribute contains a list of relative paths that failed to
+    be checked out as they contained changes that did not exist in the index.
+
+    The :attr:`failed_reasons` attribute contains a string informing about the actual
+    cause of the issue.
+
+    The :attr:`valid_files` attribute contains a list of relative paths to files that
+    were checked out successfully and hence match the version stored in the index.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        failed_files: Sequence[PathLike],
+        valid_files: Sequence[PathLike],
+        failed_reasons: List[str],
+    ) -> None:
+        Exception.__init__(self, message)
+        self.failed_files = failed_files
+        self.failed_reasons = failed_reasons
+        self.valid_files = valid_files
+
+    def __str__(self) -> str:
+        return Exception.__str__(self) + ":%s" % self.failed_files
+
+
+class CacheError(GitError):
+    """Base for all errors related to the git index, which is called "cache"
+    internally."""
+
+
+class UnmergedEntriesError(CacheError):
+    """Thrown if an operation cannot proceed as there are still unmerged
+    entries in the cache."""
+
+
+class HookExecutionError(CommandError):
+    """Thrown if a hook exits with a non-zero exit code.
+
+    This provides access to the exit code and the string returned via standard output.
+    """
+
+    def __init__(
+        self,
+        command: Union[List[str], Tuple[str, ...], str],
+        status: Union[str, int, None, Exception],
+        stderr: Union[bytes, str, None] = None,
+        stdout: Union[bytes, str, None] = None,
+    ) -> None:
+        super().__init__(command, status, stderr, stdout)
+        self._msg = "Hook('%s') failed%s"
+
+
+class RepositoryDirtyError(GitError):
+    """Thrown whenever an operation on a repository fails as it has uncommitted changes
+    that would be overwritten."""
+
+    def __init__(self, repo: "Repo", message: str) -> None:
+        self.repo = repo
+        self.message = message
+
+    def __str__(self) -> str:
+        return "Operation cannot be performed on %r: %s" % (self.repo, self.message)

.venv/lib/python3.11/site-packages/git/index/__init__.py

@@ -0,0 +1,16 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Initialize the index package."""
+
+__all__ = [
+    "BaseIndexEntry",
+    "BlobFilter",
+    "CheckoutError",
+    "IndexEntry",
+    "IndexFile",
+    "StageType",
+]
+
+from .base import CheckoutError, IndexFile
+from .typ import BaseIndexEntry, BlobFilter, IndexEntry, StageType

.venv/lib/python3.11/site-packages/git/index/base.py

@@ -0,0 +1,1532 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Module containing :class:`IndexFile`, an Index implementation facilitating all kinds
+of index manipulations such as querying and merging."""
+
+__all__ = ["IndexFile", "CheckoutError", "StageType"]
+
+import contextlib
+import datetime
+import glob
+from io import BytesIO
+import os
+import os.path as osp
+from stat import S_ISLNK
+import subprocess
+import sys
+import tempfile
+
+from gitdb.base import IStream
+from gitdb.db import MemoryDB
+
+from git.compat import defenc, force_bytes
+import git.diff as git_diff
+from git.exc import CheckoutError, GitCommandError, GitError, InvalidGitRepositoryError
+from git.objects import Blob, Commit, Object, Submodule, Tree
+from git.objects.util import Serializable
+from git.util import (
+    Actor,
+    LazyMixin,
+    LockedFD,
+    join_path_native,
+    file_contents_ro,
+    to_native_path_linux,
+    unbare_repo,
+    to_bin_sha,
+)
+
+from .fun import (
+    S_IFGITLINK,
+    aggressive_tree_merge,
+    entry_key,
+    read_cache,
+    run_commit_hook,
+    stat_mode_to_index_mode,
+    write_cache,
+    write_tree_from_cache,
+)
+from .typ import BaseIndexEntry, IndexEntry, StageType
+from .util import TemporaryFileSwap, post_clear_cache, default_index, git_working_dir
+
+# typing -----------------------------------------------------------------------------
+
+from typing import (
+    Any,
+    BinaryIO,
+    Callable,
+    Dict,
+    Generator,
+    IO,
+    Iterable,
+    Iterator,
+    List,
+    NoReturn,
+    Sequence,
+    TYPE_CHECKING,
+    Tuple,
+    Union,
+)
+
+from git.types import Literal, PathLike
+
+if TYPE_CHECKING:
+    from subprocess import Popen
+
+    from git.refs.reference import Reference
+    from git.repo import Repo
+
+
+Treeish = Union[Tree, Commit, str, bytes]
+
+# ------------------------------------------------------------------------------------
+
+
+@contextlib.contextmanager
+def _named_temporary_file_for_subprocess(directory: PathLike) -> Generator[str, None, None]:
+    """Create a named temporary file git subprocesses can open, deleting it afterward.
+
+    :param directory:
+        The directory in which the file is created.
+
+    :return:
+        A context manager object that creates the file and provides its name on entry,
+        and deletes it on exit.
+    """
+    if sys.platform == "win32":
+        fd, name = tempfile.mkstemp(dir=directory)
+        os.close(fd)
+        try:
+            yield name
+        finally:
+            os.remove(name)
+    else:
+        with tempfile.NamedTemporaryFile(dir=directory) as ctx:
+            yield ctx.name
+
+
+class IndexFile(LazyMixin, git_diff.Diffable, Serializable):
+    """An Index that can be manipulated using a native implementation in order to save
+    git command function calls wherever possible.
+
+    This provides custom merging facilities allowing to merge without actually changing
+    your index or your working tree. This way you can perform your own test merges based
+    on the index only without having to deal with the working copy. This is useful in
+    case of partial working trees.
+
+    Entries:
+
+        The index contains an entries dict whose keys are tuples of type
+        :class:`~git.index.typ.IndexEntry` to facilitate access.
+
+        You may read the entries dict or manipulate it using IndexEntry instance, i.e.::
+
+            index.entries[index.entry_key(index_entry_instance)] = index_entry_instance
+
+    Make sure you use :meth:`index.write() <write>` once you are done manipulating the
+    index directly before operating on it using the git command.
+    """
+
+    __slots__ = ("repo", "version", "entries", "_extension_data", "_file_path")
+
+    _VERSION = 2
+    """The latest version we support."""
+
+    S_IFGITLINK = S_IFGITLINK
+    """Flags for a submodule."""
+
+    def __init__(self, repo: "Repo", file_path: Union[PathLike, None] = None) -> None:
+        """Initialize this Index instance, optionally from the given `file_path`.
+
+        If no `file_path` is given, we will be created from the current index file.
+
+        If a stream is not given, the stream will be initialized from the current
+        repository's index on demand.
+        """
+        self.repo = repo
+        self.version = self._VERSION
+        self._extension_data = b""
+        self._file_path: PathLike = file_path or self._index_path()
+
+    def _set_cache_(self, attr: str) -> None:
+        if attr == "entries":
+            try:
+                fd = os.open(self._file_path, os.O_RDONLY)
+            except OSError:
+                # In new repositories, there may be no index, which means we are empty.
+                self.entries: Dict[Tuple[PathLike, StageType], IndexEntry] = {}
+                return
+            # END exception handling
+
+            try:
+                stream = file_contents_ro(fd, stream=True, allow_mmap=True)
+            finally:
+                os.close(fd)
+
+            self._deserialize(stream)
+        else:
+            super()._set_cache_(attr)
+
+    def _index_path(self) -> PathLike:
+        if self.repo.git_dir:
+            return join_path_native(self.repo.git_dir, "index")
+        else:
+            raise GitCommandError("No git directory given to join index path")
+
+    @property
+    def path(self) -> PathLike:
+        """:return: Path to the index file we are representing"""
+        return self._file_path
+
+    def _delete_entries_cache(self) -> None:
+        """Safely clear the entries cache so it can be recreated."""
+        try:
+            del self.entries
+        except AttributeError:
+            # It failed in Python 2.6.5 with AttributeError.
+            # FIXME: Look into whether we can just remove this except clause now.
+            pass
+        # END exception handling
+
+    # { Serializable Interface
+
+    def _deserialize(self, stream: IO) -> "IndexFile":
+        """Initialize this instance with index values read from the given stream."""
+        self.version, self.entries, self._extension_data, _conten_sha = read_cache(stream)
+        return self
+
+    def _entries_sorted(self) -> List[IndexEntry]:
+        """:return: List of entries, in a sorted fashion, first by path, then by stage"""
+        return sorted(self.entries.values(), key=lambda e: (e.path, e.stage))
+
+    def _serialize(self, stream: IO, ignore_extension_data: bool = False) -> "IndexFile":
+        entries = self._entries_sorted()
+        extension_data = self._extension_data  # type: Union[None, bytes]
+        if ignore_extension_data:
+            extension_data = None
+        write_cache(entries, stream, extension_data)
+        return self
+
+    # } END serializable interface
+
+    def write(
+        self,
+        file_path: Union[None, PathLike] = None,
+        ignore_extension_data: bool = False,
+    ) -> None:
+        """Write the current state to our file path or to the given one.
+
+        :param file_path:
+            If ``None``, we will write to our stored file path from which we have been
+            initialized. Otherwise we write to the given file path. Please note that
+            this will change the `file_path` of this index to the one you gave.
+
+        :param ignore_extension_data:
+            If ``True``, the TREE type extension data read in the index will not be
+            written to disk. NOTE that no extension data is actually written. Use this
+            if you have altered the index and would like to use
+            :manpage:`git-write-tree(1)` afterwards to create a tree representing your
+            written changes. If this data is present in the written index,
+            :manpage:`git-write-tree(1)` will instead write the stored/cached tree.
+            Alternatively, use :meth:`write_tree` to handle this case automatically.
+        """
+        # Make sure we have our entries read before getting a write lock.
+        # Otherwise it would be done when streaming.
+        # This can happen if one doesn't change the index, but writes it right away.
+        self.entries  # noqa: B018
+        lfd = LockedFD(file_path or self._file_path)
+        stream = lfd.open(write=True, stream=True)
+
+        try:
+            self._serialize(stream, ignore_extension_data)
+        except BaseException:
+            lfd.rollback()
+            raise
+
+        lfd.commit()
+
+        # Make sure we represent what we have written.
+        if file_path is not None:
+            self._file_path = file_path
+
+    @post_clear_cache
+    @default_index
+    def merge_tree(self, rhs: Treeish, base: Union[None, Treeish] = None) -> "IndexFile":
+        """Merge the given `rhs` treeish into the current index, possibly taking
+        a common base treeish into account.
+
+        As opposed to the :func:`from_tree` method, this allows you to use an already
+        existing tree as the left side of the merge.
+
+        :param rhs:
+            Treeish reference pointing to the 'other' side of the merge.
+
+        :param base:
+            Optional treeish reference pointing to the common base of `rhs` and this
+            index which equals lhs.
+
+        :return:
+            self (containing the merge and possibly unmerged entries in case of
+            conflicts)
+
+        :raise git.exc.GitCommandError:
+            If there is a merge conflict. The error will be raised at the first
+            conflicting path. If you want to have proper merge resolution to be done by
+            yourself, you have to commit the changed index (or make a valid tree from
+            it) and retry with a three-way :meth:`index.from_tree <from_tree>` call.
+        """
+        # -i : ignore working tree status
+        # --aggressive : handle more merge cases
+        # -m : do an actual merge
+        args: List[Union[Treeish, str]] = ["--aggressive", "-i", "-m"]
+        if base is not None:
+            args.append(base)
+        args.append(rhs)
+
+        self.repo.git.read_tree(args)
+        return self
+
+    @classmethod
+    def new(cls, repo: "Repo", *tree_sha: Union[str, Tree]) -> "IndexFile":
+        """Merge the given treeish revisions into a new index which is returned.
+
+        This method behaves like ``git-read-tree --aggressive`` when doing the merge.
+
+        :param repo:
+            The repository treeish are located in.
+
+        :param tree_sha:
+            20 byte or 40 byte tree sha or tree objects.
+
+        :return:
+            New :class:`IndexFile` instance. Its path will be undefined.
+            If you intend to write such a merged Index, supply an alternate
+            ``file_path`` to its :meth:`write` method.
+        """
+        tree_sha_bytes: List[bytes] = [to_bin_sha(str(t)) for t in tree_sha]
+        base_entries = aggressive_tree_merge(repo.odb, tree_sha_bytes)
+
+        inst = cls(repo)
+        # Convert to entries dict.
+        entries: Dict[Tuple[PathLike, int], IndexEntry] = dict(
+            zip(
+                ((e.path, e.stage) for e in base_entries),
+                (IndexEntry.from_base(e) for e in base_entries),
+            )
+        )
+
+        inst.entries = entries
+        return inst
+
+    @classmethod
+    def from_tree(cls, repo: "Repo", *treeish: Treeish, **kwargs: Any) -> "IndexFile":
+        R"""Merge the given treeish revisions into a new index which is returned.
+        The original index will remain unaltered.
+
+        :param repo:
+            The repository treeish are located in.
+
+        :param treeish:
+            One, two or three :class:`~git.objects.tree.Tree` objects,
+            :class:`~git.objects.commit.Commit`\s or 40 byte hexshas.
+
+            The result changes according to the amount of trees:
+
+            1. If 1 Tree is given, it will just be read into a new index.
+            2. If 2 Trees are given, they will be merged into a new index using a two
+               way merge algorithm. Tree 1 is the 'current' tree, tree 2 is the 'other'
+               one. It behaves like a fast-forward.
+            3. If 3 Trees are given, a 3-way merge will be performed with the first tree
+               being the common ancestor of tree 2 and tree 3. Tree 2 is the 'current'
+               tree, tree 3 is the 'other' one.
+
+        :param kwargs:
+            Additional arguments passed to :manpage:`git-read-tree(1)`.
+
+        :return:
+            New :class:`IndexFile` instance. It will point to a temporary index location
+            which does not exist anymore. If you intend to write such a merged Index,
+            supply an alternate ``file_path`` to its :meth:`write` method.
+
+        :note:
+            In the three-way merge case, ``--aggressive`` will be specified to
+            automatically resolve more cases in a commonly correct manner. Specify
+            ``trivial=True`` as a keyword argument to override that.
+
+            As the underlying :manpage:`git-read-tree(1)` command takes into account the
+            current index, it will be temporarily moved out of the way to prevent any
+            unexpected interference.
+        """
+        if len(treeish) == 0 or len(treeish) > 3:
+            raise ValueError("Please specify between 1 and 3 treeish, got %i" % len(treeish))
+
+        arg_list: List[Union[Treeish, str]] = []
+        # Ignore that the working tree and index possibly are out of date.
+        if len(treeish) > 1:
+            # Drop unmerged entries when reading our index and merging.
+            arg_list.append("--reset")
+            # Handle non-trivial cases the way a real merge does.
+            arg_list.append("--aggressive")
+        # END merge handling
+
+        # Create the temporary file in the .git directory to be sure renaming
+        # works - /tmp/ directories could be on another device.
+        with _named_temporary_file_for_subprocess(repo.git_dir) as tmp_index:
+            arg_list.append("--index-output=%s" % tmp_index)
+            arg_list.extend(treeish)
+
+            # Move the current index out of the way - otherwise the merge may fail as it
+            # considers existing entries. Moving it essentially clears the index.
+            # Unfortunately there is no 'soft' way to do it.
+            # The TemporaryFileSwap ensures the original file gets put back.
+            with TemporaryFileSwap(join_path_native(repo.git_dir, "index")):
+                repo.git.read_tree(*arg_list, **kwargs)
+                index = cls(repo, tmp_index)
+                index.entries  # noqa: B018 # Force it to read the file as we will delete the temp-file.
+                return index
+            # END index merge handling
+
+    # UTILITIES
+
+    @unbare_repo
+    def _iter_expand_paths(self: "IndexFile", paths: Sequence[PathLike]) -> Iterator[PathLike]:
+        """Expand the directories in list of paths to the corresponding paths
+        accordingly.
+
+        :note:
+            git will add items multiple times even if a glob overlapped with manually
+            specified paths or if paths where specified multiple times - we respect that
+            and do not prune.
+        """
+
+        def raise_exc(e: Exception) -> NoReturn:
+            raise e
+
+        r = str(self.repo.working_tree_dir)
+        rs = r + os.sep
+        for path in paths:
+            abs_path = str(path)
+            if not osp.isabs(abs_path):
+                abs_path = osp.join(r, path)
+            # END make absolute path
+
+            try:
+                st = os.lstat(abs_path)  # Handles non-symlinks as well.
+            except OSError:
+                # The lstat call may fail as the path may contain globs as well.
+                pass
+            else:
+                if S_ISLNK(st.st_mode):
+                    yield abs_path.replace(rs, "")
+                    continue
+            # END check symlink
+
+            # If the path is not already pointing to an existing file, resolve globs if possible.
+            if not os.path.exists(abs_path) and ("?" in abs_path or "*" in abs_path or "[" in abs_path):
+                resolved_paths = glob.glob(abs_path)
+                # not abs_path in resolved_paths:
+                #   A glob() resolving to the same path we are feeding it with is a
+                #   glob() that failed to resolve. If we continued calling ourselves
+                #   we'd endlessly recurse. If the condition below evaluates to true
+                #   then we are likely dealing with a file whose name contains wildcard
+                #   characters.
+                if abs_path not in resolved_paths:
+                    for f in self._iter_expand_paths(glob.glob(abs_path)):
+                        yield str(f).replace(rs, "")
+                    continue
+            # END glob handling
+            try:
+                for root, _dirs, files in os.walk(abs_path, onerror=raise_exc):
+                    for rela_file in files:
+                        # Add relative paths only.
+                        yield osp.join(root.replace(rs, ""), rela_file)
+                    # END for each file in subdir
+                # END for each subdirectory
+            except OSError:
+                # It was a file or something that could not be iterated.
+                yield abs_path.replace(rs, "")
+            # END path exception handling
+        # END for each path
+
+    def _write_path_to_stdin(
+        self,
+        proc: "Popen",
+        filepath: PathLike,
+        item: PathLike,
+        fmakeexc: Callable[..., GitError],
+        fprogress: Callable[[PathLike, bool, PathLike], None],
+        read_from_stdout: bool = True,
+    ) -> Union[None, str]:
+        """Write path to ``proc.stdin`` and make sure it processes the item, including
+        progress.
+
+        :return:
+            stdout string
+
+        :param read_from_stdout:
+            If ``True``, ``proc.stdout`` will be read after the item was sent to stdin.
+            In that case, it will return ``None``.
+
+        :note:
+            There is a bug in :manpage:`git-update-index(1)` that prevents it from
+            sending reports just in time. This is why we have a version that tries to
+            read stdout and one which doesn't. In fact, the stdout is not important as
+            the piped-in files are processed anyway and just in time.
+
+        :note:
+            Newlines are essential here, git's behaviour is somewhat inconsistent on
+            this depending on the version, hence we try our best to deal with newlines
+            carefully. Usually the last newline will not be sent, instead we will close
+            stdin to break the pipe.
+        """
+        fprogress(filepath, False, item)
+        rval: Union[None, str] = None
+
+        if proc.stdin is not None:
+            try:
+                proc.stdin.write(("%s\n" % filepath).encode(defenc))
+            except IOError as e:
+                # Pipe broke, usually because some error happened.
+                raise fmakeexc() from e
+            # END write exception handling
+            proc.stdin.flush()
+
+        if read_from_stdout and proc.stdout is not None:
+            rval = proc.stdout.readline().strip()
+        fprogress(filepath, True, item)
+        return rval
+
+    def iter_blobs(
+        self, predicate: Callable[[Tuple[StageType, Blob]], bool] = lambda t: True
+    ) -> Iterator[Tuple[StageType, Blob]]:
+        """
+        :return:
+            Iterator yielding tuples of :class:`~git.objects.blob.Blob` objects and
+            stages, tuple(stage, Blob).
+
+        :param predicate:
+            Function(t) returning ``True`` if tuple(stage, Blob) should be yielded by
+            the iterator. A default filter, the :class:`~git.index.typ.BlobFilter`, allows you
+            to yield blobs only if they match a given list of paths.
+        """
+        for entry in self.entries.values():
+            blob = entry.to_blob(self.repo)
+            blob.size = entry.size
+            output = (entry.stage, blob)
+            if predicate(output):
+                yield output
+        # END for each entry
+
+    def unmerged_blobs(self) -> Dict[PathLike, List[Tuple[StageType, Blob]]]:
+        """
+        :return:
+            Dict(path : list(tuple(stage, Blob, ...))), being a dictionary associating a
+            path in the index with a list containing sorted stage/blob pairs.
+
+        :note:
+            Blobs that have been removed in one side simply do not exist in the given
+            stage. That is, a file removed on the 'other' branch whose entries are at
+            stage 3 will not have a stage 3 entry.
+        """
+
+        def is_unmerged_blob(t: Tuple[StageType, Blob]) -> bool:
+            return t[0] != 0
+
+        path_map: Dict[PathLike, List[Tuple[StageType, Blob]]] = {}
+        for stage, blob in self.iter_blobs(is_unmerged_blob):
+            path_map.setdefault(blob.path, []).append((stage, blob))
+        # END for each unmerged blob
+        for line in path_map.values():
+            line.sort()
+
+        return path_map
+
+    @classmethod
+    def entry_key(cls, *entry: Union[BaseIndexEntry, PathLike, StageType]) -> Tuple[PathLike, StageType]:
+        return entry_key(*entry)
+
+    def resolve_blobs(self, iter_blobs: Iterator[Blob]) -> "IndexFile":
+        """Resolve the blobs given in blob iterator.
+
+        This will effectively remove the index entries of the respective path at all
+        non-null stages and add the given blob as new stage null blob.
+
+        For each path there may only be one blob, otherwise a :exc:`ValueError` will be
+        raised claiming the path is already at stage 0.
+
+        :raise ValueError:
+            If one of the blobs already existed at stage 0.
+
+        :return:
+            self
+
+        :note:
+            You will have to write the index manually once you are done, i.e.
+            ``index.resolve_blobs(blobs).write()``.
+        """
+        for blob in iter_blobs:
+            stage_null_key = (blob.path, 0)
+            if stage_null_key in self.entries:
+                raise ValueError("Path %r already exists at stage 0" % str(blob.path))
+            # END assert blob is not stage 0 already
+
+            # Delete all possible stages.
+            for stage in (1, 2, 3):
+                try:
+                    del self.entries[(blob.path, stage)]
+                except KeyError:
+                    pass
+                # END ignore key errors
+            # END for each possible stage
+
+            self.entries[stage_null_key] = IndexEntry.from_blob(blob)
+        # END for each blob
+
+        return self
+
+    def update(self) -> "IndexFile":
+        """Reread the contents of our index file, discarding all cached information
+        we might have.
+
+        :note:
+            This is a possibly dangerous operations as it will discard your changes to
+            :attr:`index.entries <entries>`.
+
+        :return:
+            self
+        """
+        self._delete_entries_cache()
+        # Allows to lazily reread on demand.
+        return self
+
+    def write_tree(self) -> Tree:
+        """Write this index to a corresponding :class:`~git.objects.tree.Tree` object
+        into the repository's object database and return it.
+
+        :return:
+            :class:`~git.objects.tree.Tree` object representing this index.
+
+        :note:
+            The tree will be written even if one or more objects the tree refers to does
+            not yet exist in the object database. This could happen if you added entries
+            to the index directly.
+
+        :raise ValueError:
+            If there are no entries in the cache.
+
+        :raise git.exc.UnmergedEntriesError:
+        """
+        # We obtain no lock as we just flush our contents to disk as tree.
+        # If we are a new index, the entries access will load our data accordingly.
+        mdb = MemoryDB()
+        entries = self._entries_sorted()
+        binsha, tree_items = write_tree_from_cache(entries, mdb, slice(0, len(entries)))
+
+        # Copy changed trees only.
+        mdb.stream_copy(mdb.sha_iter(), self.repo.odb)
+
+        # Note: Additional deserialization could be saved if write_tree_from_cache would
+        # return sorted tree entries.
+        root_tree = Tree(self.repo, binsha, path="")
+        root_tree._cache = tree_items
+        return root_tree
+
+    def _process_diff_args(
+        self,
+        args: List[Union[PathLike, "git_diff.Diffable"]],
+    ) -> List[Union[PathLike, "git_diff.Diffable"]]:
+        try:
+            args.pop(args.index(self))
+        except IndexError:
+            pass
+        # END remove self
+        return args
+
+    def _to_relative_path(self, path: PathLike) -> PathLike:
+        """
+        :return:
+            Version of path relative to our git directory or raise :exc:`ValueError` if
+            it is not within our git directory.
+
+        :raise ValueError:
+        """
+        if not osp.isabs(path):
+            return path
+        if self.repo.bare:
+            raise InvalidGitRepositoryError("require non-bare repository")
+        if not osp.normpath(str(path)).startswith(str(self.repo.working_tree_dir)):
+            raise ValueError("Absolute path %r is not in git repository at %r" % (path, self.repo.working_tree_dir))
+        result = os.path.relpath(path, self.repo.working_tree_dir)
+        if str(path).endswith(os.sep) and not result.endswith(os.sep):
+            result += os.sep
+        return result
+
+    def _preprocess_add_items(
+        self, items: Union[PathLike, Sequence[Union[PathLike, Blob, BaseIndexEntry, "Submodule"]]]
+    ) -> Tuple[List[PathLike], List[BaseIndexEntry]]:
+        """Split the items into two lists of path strings and BaseEntries."""
+        paths = []
+        entries = []
+        # if it is a string put in list
+        if isinstance(items, (str, os.PathLike)):
+            items = [items]
+
+        for item in items:
+            if isinstance(item, (str, os.PathLike)):
+                paths.append(self._to_relative_path(item))
+            elif isinstance(item, (Blob, Submodule)):
+                entries.append(BaseIndexEntry.from_blob(item))
+            elif isinstance(item, BaseIndexEntry):
+                entries.append(item)
+            else:
+                raise TypeError("Invalid Type: %r" % item)
+        # END for each item
+        return paths, entries
+
+    def _store_path(self, filepath: PathLike, fprogress: Callable) -> BaseIndexEntry:
+        """Store file at filepath in the database and return the base index entry.
+
+        :note:
+            This needs the :func:`~git.index.util.git_working_dir` decorator active!
+            This must be ensured in the calling code.
+        """
+        st = os.lstat(filepath)  # Handles non-symlinks as well.
+
+        if S_ISLNK(st.st_mode):
+            # In PY3, readlink is a string, but we need bytes.
+            # In PY2, it was just OS encoded bytes, we assumed UTF-8.
+            def open_stream() -> BinaryIO:
+                return BytesIO(force_bytes(os.readlink(filepath), encoding=defenc))
+        else:
+
+            def open_stream() -> BinaryIO:
+                return open(filepath, "rb")
+
+        with open_stream() as stream:
+            fprogress(filepath, False, filepath)
+            istream = self.repo.odb.store(IStream(Blob.type, st.st_size, stream))
+            fprogress(filepath, True, filepath)
+        return BaseIndexEntry(
+            (
+                stat_mode_to_index_mode(st.st_mode),
+                istream.binsha,
+                0,
+                to_native_path_linux(filepath),
+            )
+        )
+
+    @unbare_repo
+    @git_working_dir
+    def _entries_for_paths(
+        self,
+        paths: List[str],
+        path_rewriter: Union[Callable, None],
+        fprogress: Callable,
+        entries: List[BaseIndexEntry],
+    ) -> List[BaseIndexEntry]:
+        entries_added: List[BaseIndexEntry] = []
+        if path_rewriter:
+            for path in paths:
+                if osp.isabs(path):
+                    abspath = path
+                    gitrelative_path = path[len(str(self.repo.working_tree_dir)) + 1 :]
+                else:
+                    gitrelative_path = path
+                    if self.repo.working_tree_dir:
+                        abspath = osp.join(self.repo.working_tree_dir, gitrelative_path)
+                # END obtain relative and absolute paths
+
+                blob = Blob(
+                    self.repo,
+                    Blob.NULL_BIN_SHA,
+                    stat_mode_to_index_mode(os.stat(abspath).st_mode),
+                    to_native_path_linux(gitrelative_path),
+                )
+                # TODO: variable undefined
+                entries.append(BaseIndexEntry.from_blob(blob))
+            # END for each path
+            del paths[:]
+        # END rewrite paths
+
+        # HANDLE PATHS
+        assert len(entries_added) == 0
+        for filepath in self._iter_expand_paths(paths):
+            entries_added.append(self._store_path(filepath, fprogress))
+        # END for each filepath
+        # END path handling
+        return entries_added
+
+    def add(
+        self,
+        items: Union[PathLike, Sequence[Union[PathLike, Blob, BaseIndexEntry, "Submodule"]]],
+        force: bool = True,
+        fprogress: Callable = lambda *args: None,
+        path_rewriter: Union[Callable[..., PathLike], None] = None,
+        write: bool = True,
+        write_extension_data: bool = False,
+    ) -> List[BaseIndexEntry]:
+        R"""Add files from the working tree, specific blobs, or
+        :class:`~git.index.typ.BaseIndexEntry`\s to the index.
+
+        :param items:
+            Multiple types of items are supported, types can be mixed within one call.
+            Different types imply a different handling. File paths may generally be
+            relative or absolute.
+
+            - path string
+
+                Strings denote a relative or absolute path into the repository pointing
+                to an existing file, e.g., ``CHANGES``, ``lib/myfile.ext``,
+                ``/home/gitrepo/lib/myfile.ext``.
+
+                Absolute paths must start with working tree directory of this index's
+                repository to be considered valid. For example, if it was initialized
+                with a non-normalized path, like ``/root/repo/../repo``, absolute paths
+                to be added must start with ``/root/repo/../repo``.
+
+                Paths provided like this must exist. When added, they will be written
+                into the object database.
+
+                PathStrings may contain globs, such as ``lib/__init__*``. Or they can be
+                directories like ``lib``, which will add all the files within the
+                directory and subdirectories.
+
+                This equals a straight :manpage:`git-add(1)`.
+
+                They are added at stage 0.
+
+            - :class:`~git.objects.blob.Blob` or
+              :class:`~git.objects.submodule.base.Submodule` object
+
+                Blobs are added as they are assuming a valid mode is set.
+
+                The file they refer to may or may not exist in the file system, but must
+                be a path relative to our repository.
+
+                If their sha is null (40*0), their path must exist in the file system
+                relative to the git repository as an object will be created from the
+                data at the path.
+
+                The handling now very much equals the way string paths are processed,
+                except that the mode you have set will be kept. This allows you to
+                create symlinks by settings the mode respectively and writing the target
+                of the symlink directly into the file. This equals a default Linux
+                symlink which is not dereferenced automatically, except that it can be
+                created on filesystems not supporting it as well.
+
+                Please note that globs or directories are not allowed in
+                :class:`~git.objects.blob.Blob` objects.
+
+                They are added at stage 0.
+
+            - :class:`~git.index.typ.BaseIndexEntry` or type
+
+                Handling equals the one of :class:`~git.objects.blob.Blob` objects, but
+                the stage may be explicitly set. Please note that Index Entries require
+                binary sha's.
+
+        :param force:
+            **CURRENTLY INEFFECTIVE**
+            If ``True``, otherwise ignored or excluded files will be added anyway. As
+            opposed to the :manpage:`git-add(1)` command, we enable this flag by default
+            as the API user usually wants the item to be added even though they might be
+            excluded.
+
+        :param fprogress:
+            Function with signature ``f(path, done=False, item=item)`` called for each
+            path to be added, one time once it is about to be added where ``done=False``
+            and once after it was added where ``done=True``.
+
+            ``item`` is set to the actual item we handle, either a path or a
+            :class:`~git.index.typ.BaseIndexEntry`.
+
+            Please note that the processed path is not guaranteed to be present in the
+            index already as the index is currently being processed.
+
+        :param path_rewriter:
+            Function, with signature ``(string) func(BaseIndexEntry)``, returning a path
+            for each passed entry which is the path to be actually recorded for the
+            object created from :attr:`entry.path <git.index.typ.BaseIndexEntry.path>`.
+            This allows you to write an index which is not identical to the layout of
+            the actual files on your hard-disk. If not ``None`` and `items` contain
+            plain paths, these paths will be converted to Entries beforehand and passed
+            to the path_rewriter. Please note that ``entry.path`` is relative to the git
+            repository.
+
+        :param write:
+            If ``True``, the index will be written once it was altered. Otherwise the
+            changes only exist in memory and are not available to git commands.
+
+        :param write_extension_data:
+            If ``True``, extension data will be written back to the index. This can lead
+            to issues in case it is containing the 'TREE' extension, which will cause
+            the :manpage:`git-commit(1)` command to write an old tree, instead of a new
+            one representing the now changed index.
+
+            This doesn't matter if you use :meth:`IndexFile.commit`, which ignores the
+            'TREE' extension altogether. You should set it to ``True`` if you intend to
+            use :meth:`IndexFile.commit` exclusively while maintaining support for
+            third-party extensions. Besides that, you can usually safely ignore the
+            built-in extensions when using GitPython on repositories that are not
+            handled manually at all.
+
+            All current built-in extensions are listed here:
+            https://git-scm.com/docs/index-format
+
+        :return:
+            List of :class:`~git.index.typ.BaseIndexEntry`\s representing the entries
+            just actually added.
+
+        :raise OSError:
+            If a supplied path did not exist. Please note that
+            :class:`~git.index.typ.BaseIndexEntry` objects that do not have a null sha
+            will be added even if their paths do not exist.
+        """
+        # Sort the entries into strings and Entries.
+        # Blobs are converted to entries automatically.
+        # Paths can be git-added. For everything else we use git-update-index.
+        paths, entries = self._preprocess_add_items(items)
+        entries_added: List[BaseIndexEntry] = []
+        # This code needs a working tree, so we try not to run it unless required.
+        # That way, we are OK on a bare repository as well.
+        # If there are no paths, the rewriter has nothing to do either.
+        if paths:
+            entries_added.extend(self._entries_for_paths(paths, path_rewriter, fprogress, entries))
+
+        # HANDLE ENTRIES
+        if entries:
+            null_mode_entries = [e for e in entries if e.mode == 0]
+            if null_mode_entries:
+                raise ValueError(
+                    "At least one Entry has a null-mode - please use index.remove to remove files for clarity"
+                )
+            # END null mode should be remove
+
+            # HANDLE ENTRY OBJECT CREATION
+            # Create objects if required, otherwise go with the existing shas.
+            null_entries_indices = [i for i, e in enumerate(entries) if e.binsha == Object.NULL_BIN_SHA]
+            if null_entries_indices:
+
+                @git_working_dir
+                def handle_null_entries(self: "IndexFile") -> None:
+                    for ei in null_entries_indices:
+                        null_entry = entries[ei]
+                        new_entry = self._store_path(null_entry.path, fprogress)
+
+                        # Update null entry.
+                        entries[ei] = BaseIndexEntry(
+                            (
+                                null_entry.mode,
+                                new_entry.binsha,
+                                null_entry.stage,
+                                null_entry.path,
+                            )
+                        )
+                    # END for each entry index
+
+                # END closure
+
+                handle_null_entries(self)
+            # END null_entry handling
+
+            # REWRITE PATHS
+            # If we have to rewrite the entries, do so now, after we have generated all
+            # object sha's.
+            if path_rewriter:
+                for i, e in enumerate(entries):
+                    entries[i] = BaseIndexEntry((e.mode, e.binsha, e.stage, path_rewriter(e)))
+                # END for each entry
+            # END handle path rewriting
+
+            # Just go through the remaining entries and provide progress info.
+            for i, entry in enumerate(entries):
+                progress_sent = i in null_entries_indices
+                if not progress_sent:
+                    fprogress(entry.path, False, entry)
+                    fprogress(entry.path, True, entry)
+                # END handle progress
+            # END for each entry
+            entries_added.extend(entries)
+        # END if there are base entries
+
+        # FINALIZE
+        # Add the new entries to this instance.
+        for entry in entries_added:
+            self.entries[(entry.path, 0)] = IndexEntry.from_base(entry)
+
+        if write:
+            self.write(ignore_extension_data=not write_extension_data)
+        # END handle write
+
+        return entries_added
+
+    def _items_to_rela_paths(
+        self,
+        items: Union[PathLike, Sequence[Union[PathLike, BaseIndexEntry, Blob, Submodule]]],
+    ) -> List[PathLike]:
+        """Returns a list of repo-relative paths from the given items which
+        may be absolute or relative paths, entries or blobs."""
+        paths = []
+        # If string, put in list.
+        if isinstance(items, (str, os.PathLike)):
+            items = [items]
+
+        for item in items:
+            if isinstance(item, (BaseIndexEntry, (Blob, Submodule))):
+                paths.append(self._to_relative_path(item.path))
+            elif isinstance(item, (str, os.PathLike)):
+                paths.append(self._to_relative_path(item))
+            else:
+                raise TypeError("Invalid item type: %r" % item)
+        # END for each item
+        return paths
+
+    @post_clear_cache
+    @default_index
+    def remove(
+        self,
+        items: Union[PathLike, Sequence[Union[PathLike, Blob, BaseIndexEntry, "Submodule"]]],
+        working_tree: bool = False,
+        **kwargs: Any,
+    ) -> List[str]:
+        R"""Remove the given items from the index and optionally from the working tree
+        as well.
+
+        :param items:
+            Multiple types of items are supported which may be be freely mixed.
+
+            - path string
+
+                Remove the given path at all stages. If it is a directory, you must
+                specify the ``r=True`` keyword argument to remove all file entries below
+                it. If absolute paths are given, they will be converted to a path
+                relative to the git repository directory containing the working tree
+
+                The path string may include globs, such as ``*.c``.
+
+            - :class:`~git.objects.blob.Blob` object
+
+                Only the path portion is used in this case.
+
+            - :class:`~git.index.typ.BaseIndexEntry` or compatible type
+
+                The only relevant information here is the path. The stage is ignored.
+
+        :param working_tree:
+            If ``True``, the entry will also be removed from the working tree,
+            physically removing the respective file. This may fail if there are
+            uncommitted changes in it.
+
+        :param kwargs:
+            Additional keyword arguments to be passed to :manpage:`git-rm(1)`, such as
+            ``r`` to allow recursive removal.
+
+        :return:
+            List(path_string, ...) list of repository relative paths that have been
+            removed effectively.
+
+            This is interesting to know in case you have provided a directory or globs.
+            Paths are relative to the repository.
+        """
+        args = []
+        if not working_tree:
+            args.append("--cached")
+        args.append("--")
+
+        # Preprocess paths.
+        paths = self._items_to_rela_paths(items)
+        removed_paths = self.repo.git.rm(args, paths, **kwargs).splitlines()
+
+        # Process output to gain proper paths.
+        # rm 'path'
+        return [p[4:-1] for p in removed_paths]
+
+    @post_clear_cache
+    @default_index
+    def move(
+        self,
+        items: Union[PathLike, Sequence[Union[PathLike, Blob, BaseIndexEntry, "Submodule"]]],
+        skip_errors: bool = False,
+        **kwargs: Any,
+    ) -> List[Tuple[str, str]]:
+        """Rename/move the items, whereas the last item is considered the destination of
+        the move operation.
+
+        If the destination is a file, the first item (of two) must be a file as well.
+
+        If the destination is a directory, it may be preceded by one or more directories
+        or files.
+
+        The working tree will be affected in non-bare repositories.
+
+        :param items:
+            Multiple types of items are supported, please see the :meth:`remove` method
+            for reference.
+
+        :param skip_errors:
+            If ``True``, errors such as ones resulting from missing source files will be
+            skipped.
+
+        :param kwargs:
+            Additional arguments you would like to pass to :manpage:`git-mv(1)`, such as
+            ``dry_run`` or ``force``.
+
+        :return:
+            List(tuple(source_path_string, destination_path_string), ...)
+
+            A list of pairs, containing the source file moved as well as its actual
+            destination. Relative to the repository root.
+
+        :raise ValueError:
+            If only one item was given.
+
+        :raise git.exc.GitCommandError:
+            If git could not handle your request.
+        """
+        args = []
+        if skip_errors:
+            args.append("-k")
+
+        paths = self._items_to_rela_paths(items)
+        if len(paths) < 2:
+            raise ValueError("Please provide at least one source and one destination of the move operation")
+
+        was_dry_run = kwargs.pop("dry_run", kwargs.pop("n", None))
+        kwargs["dry_run"] = True
+
+        # First execute rename in dry run so the command tells us what it actually does
+        # (for later output).
+        out = []
+        mvlines = self.repo.git.mv(args, paths, **kwargs).splitlines()
+
+        # Parse result - first 0:n/2 lines are 'checking ', the remaining ones are the
+        # 'renaming' ones which we parse.
+        for ln in range(int(len(mvlines) / 2), len(mvlines)):
+            tokens = mvlines[ln].split(" to ")
+            assert len(tokens) == 2, "Too many tokens in %s" % mvlines[ln]
+
+            # [0] = Renaming x
+            # [1] = y
+            out.append((tokens[0][9:], tokens[1]))
+        # END for each line to parse
+
+        # Either prepare for the real run, or output the dry-run result.
+        if was_dry_run:
+            return out
+        # END handle dry run
+
+        # Now apply the actual operation.
+        kwargs.pop("dry_run")
+        self.repo.git.mv(args, paths, **kwargs)
+
+        return out
+
+    def commit(
+        self,
+        message: str,
+        parent_commits: Union[List[Commit], None] = None,
+        head: bool = True,
+        author: Union[None, Actor] = None,
+        committer: Union[None, Actor] = None,
+        author_date: Union[datetime.datetime, str, None] = None,
+        commit_date: Union[datetime.datetime, str, None] = None,
+        skip_hooks: bool = False,
+    ) -> Commit:
+        """Commit the current default index file, creating a
+        :class:`~git.objects.commit.Commit` object.
+
+        For more information on the arguments, see
+        :meth:`Commit.create_from_tree <git.objects.commit.Commit.create_from_tree>`.
+
+        :note:
+            If you have manually altered the :attr:`entries` member of this instance,
+            don't forget to :meth:`write` your changes to disk beforehand.
+
+        :note:
+            Passing ``skip_hooks=True`` is the equivalent of using ``-n`` or
+            ``--no-verify`` on the command line.
+
+        :return:
+            :class:`~git.objects.commit.Commit` object representing the new commit
+        """
+        if not skip_hooks:
+            run_commit_hook("pre-commit", self)
+
+            self._write_commit_editmsg(message)
+            run_commit_hook("commit-msg", self, self._commit_editmsg_filepath())
+            message = self._read_commit_editmsg()
+            self._remove_commit_editmsg()
+        tree = self.write_tree()
+        rval = Commit.create_from_tree(
+            self.repo,
+            tree,
+            message,
+            parent_commits,
+            head,
+            author=author,
+            committer=committer,
+            author_date=author_date,
+            commit_date=commit_date,
+        )
+        if not skip_hooks:
+            run_commit_hook("post-commit", self)
+        return rval
+
+    def _write_commit_editmsg(self, message: str) -> None:
+        with open(self._commit_editmsg_filepath(), "wb") as commit_editmsg_file:
+            commit_editmsg_file.write(message.encode(defenc))
+
+    def _remove_commit_editmsg(self) -> None:
+        os.remove(self._commit_editmsg_filepath())
+
+    def _read_commit_editmsg(self) -> str:
+        with open(self._commit_editmsg_filepath(), "rb") as commit_editmsg_file:
+            return commit_editmsg_file.read().decode(defenc)
+
+    def _commit_editmsg_filepath(self) -> str:
+        return osp.join(self.repo.common_dir, "COMMIT_EDITMSG")
+
+    def _flush_stdin_and_wait(cls, proc: "Popen[bytes]", ignore_stdout: bool = False) -> bytes:
+        stdin_IO = proc.stdin
+        if stdin_IO:
+            stdin_IO.flush()
+            stdin_IO.close()
+
+        stdout = b""
+        if not ignore_stdout and proc.stdout:
+            stdout = proc.stdout.read()
+
+        if proc.stdout:
+            proc.stdout.close()
+            proc.wait()
+        return stdout
+
+    @default_index
+    def checkout(
+        self,
+        paths: Union[None, Iterable[PathLike]] = None,
+        force: bool = False,
+        fprogress: Callable = lambda *args: None,
+        **kwargs: Any,
+    ) -> Union[None, Iterator[PathLike], Sequence[PathLike]]:
+        """Check out the given paths or all files from the version known to the index
+        into the working tree.
+
+        :note:
+            Be sure you have written pending changes using the :meth:`write` method in
+            case you have altered the entries dictionary directly.
+
+        :param paths:
+            If ``None``, all paths in the index will be checked out.
+            Otherwise an iterable of relative or absolute paths or a single path
+            pointing to files or directories in the index is expected.
+
+        :param force:
+            If ``True``, existing files will be overwritten even if they contain local
+            modifications.
+            If ``False``, these will trigger a :exc:`~git.exc.CheckoutError`.
+
+        :param fprogress:
+            See :meth:`IndexFile.add` for signature and explanation.
+
+            The provided progress information will contain ``None`` as path and item if
+            no explicit paths are given. Otherwise progress information will be send
+            prior and after a file has been checked out.
+
+        :param kwargs:
+            Additional arguments to be passed to :manpage:`git-checkout-index(1)`.
+
+        :return:
+            Iterable yielding paths to files which have been checked out and are
+            guaranteed to match the version stored in the index.
+
+        :raise git.exc.CheckoutError:
+            * If at least one file failed to be checked out. This is a summary, hence it
+              will checkout as many files as it can anyway.
+            * If one of files or directories do not exist in the index (as opposed to
+              the original git command, which ignores them).
+
+        :raise git.exc.GitCommandError:
+            If error lines could not be parsed - this truly is an exceptional state.
+
+        :note:
+            The checkout is limited to checking out the files in the index. Files which
+            are not in the index anymore and exist in the working tree will not be
+            deleted. This behaviour is fundamentally different to ``head.checkout``,
+            i.e. if you want :manpage:`git-checkout(1)`-like behaviour, use
+            ``head.checkout`` instead of ``index.checkout``.
+        """
+        args = ["--index"]
+        if force:
+            args.append("--force")
+
+        failed_files = []
+        failed_reasons = []
+        unknown_lines = []
+
+        def handle_stderr(proc: "Popen[bytes]", iter_checked_out_files: Iterable[PathLike]) -> None:
+            stderr_IO = proc.stderr
+            if not stderr_IO:
+                return  # Return early if stderr empty.
+
+            stderr_bytes = stderr_IO.read()
+            # line contents:
+            stderr = stderr_bytes.decode(defenc)
+            # git-checkout-index: this already exists
+            endings = (
+                " already exists",
+                " is not in the cache",
+                " does not exist at stage",
+                " is unmerged",
+            )
+            for line in stderr.splitlines():
+                if not line.startswith("git checkout-index: ") and not line.startswith("git-checkout-index: "):
+                    is_a_dir = " is a directory"
+                    unlink_issue = "unable to unlink old '"
+                    already_exists_issue = " already exists, no checkout"  # created by entry.c:checkout_entry(...)
+                    if line.endswith(is_a_dir):
+                        failed_files.append(line[: -len(is_a_dir)])
+                        failed_reasons.append(is_a_dir)
+                    elif line.startswith(unlink_issue):
+                        failed_files.append(line[len(unlink_issue) : line.rfind("'")])
+                        failed_reasons.append(unlink_issue)
+                    elif line.endswith(already_exists_issue):
+                        failed_files.append(line[: -len(already_exists_issue)])
+                        failed_reasons.append(already_exists_issue)
+                    else:
+                        unknown_lines.append(line)
+                    continue
+                # END special lines parsing
+
+                for e in endings:
+                    if line.endswith(e):
+                        failed_files.append(line[20 : -len(e)])
+                        failed_reasons.append(e)
+                        break
+                    # END if ending matches
+                # END for each possible ending
+            # END for each line
+            if unknown_lines:
+                raise GitCommandError(("git-checkout-index",), 128, stderr)
+            if failed_files:
+                valid_files = list(set(iter_checked_out_files) - set(failed_files))
+                raise CheckoutError(
+                    "Some files could not be checked out from the index due to local modifications",
+                    failed_files,
+                    valid_files,
+                    failed_reasons,
+                )
+
+        # END stderr handler
+
+        if paths is None:
+            args.append("--all")
+            kwargs["as_process"] = 1
+            fprogress(None, False, None)
+            proc = self.repo.git.checkout_index(*args, **kwargs)
+            proc.wait()
+            fprogress(None, True, None)
+            rval_iter = (e.path for e in self.entries.values())
+            handle_stderr(proc, rval_iter)
+            return rval_iter
+        else:
+            if isinstance(paths, str):
+                paths = [paths]
+
+            # Make sure we have our entries loaded before we start checkout_index, which
+            # will hold a lock on it. We try to get the lock as well during our entries
+            # initialization.
+            self.entries  # noqa: B018
+
+            args.append("--stdin")
+            kwargs["as_process"] = True
+            kwargs["istream"] = subprocess.PIPE
+            proc = self.repo.git.checkout_index(args, **kwargs)
+
+            # FIXME: Reading from GIL!
+            def make_exc() -> GitCommandError:
+                return GitCommandError(("git-checkout-index", *args), 128, proc.stderr.read())
+
+            checked_out_files: List[PathLike] = []
+
+            for path in paths:
+                co_path = to_native_path_linux(self._to_relative_path(path))
+                # If the item is not in the index, it could be a directory.
+                path_is_directory = False
+
+                try:
+                    self.entries[(co_path, 0)]
+                except KeyError:
+                    folder = str(co_path)
+                    if not folder.endswith("/"):
+                        folder += "/"
+                    for entry in self.entries.values():
+                        if str(entry.path).startswith(folder):
+                            p = entry.path
+                            self._write_path_to_stdin(proc, p, p, make_exc, fprogress, read_from_stdout=False)
+                            checked_out_files.append(p)
+                            path_is_directory = True
+                        # END if entry is in directory
+                    # END for each entry
+                # END path exception handlnig
+
+                if not path_is_directory:
+                    self._write_path_to_stdin(proc, co_path, path, make_exc, fprogress, read_from_stdout=False)
+                    checked_out_files.append(co_path)
+                # END path is a file
+            # END for each path
+            try:
+                self._flush_stdin_and_wait(proc, ignore_stdout=True)
+            except GitCommandError:
+                # Without parsing stdout we don't know what failed.
+                raise CheckoutError(  # noqa: B904
+                    "Some files could not be checked out from the index, probably because they didn't exist.",
+                    failed_files,
+                    [],
+                    failed_reasons,
+                )
+
+            handle_stderr(proc, checked_out_files)
+            return checked_out_files
+        # END paths handling
+
+    @default_index
+    def reset(
+        self,
+        commit: Union[Commit, "Reference", str] = "HEAD",
+        working_tree: bool = False,
+        paths: Union[None, Iterable[PathLike]] = None,
+        head: bool = False,
+        **kwargs: Any,
+    ) -> "IndexFile":
+        """Reset the index to reflect the tree at the given commit. This will not adjust
+        our HEAD reference by default, as opposed to
+        :meth:`HEAD.reset <git.refs.head.HEAD.reset>`.
+
+        :param commit:
+            Revision, :class:`~git.refs.reference.Reference` or
+            :class:`~git.objects.commit.Commit` specifying the commit we should
+            represent.
+
+            If you want to specify a tree only, use :meth:`IndexFile.from_tree` and
+            overwrite the default index.
+
+        :param working_tree:
+            If ``True``, the files in the working tree will reflect the changed index.
+            If ``False``, the working tree will not be touched.
+            Please note that changes to the working copy will be discarded without
+            warning!
+
+        :param head:
+            If ``True``, the head will be set to the given commit. This is ``False`` by
+            default, but if ``True``, this method behaves like
+            :meth:`HEAD.reset <git.refs.head.HEAD.reset>`.
+
+        :param paths:
+            If given as an iterable of absolute or repository-relative paths, only these
+            will be reset to their state at the given commit-ish.
+            The paths need to exist at the commit, otherwise an exception will be
+            raised.
+
+        :param kwargs:
+            Additional keyword arguments passed to :manpage:`git-reset(1)`.
+
+        :note:
+            :meth:`IndexFile.reset`, as opposed to
+            :meth:`HEAD.reset <git.refs.head.HEAD.reset>`, will not delete any files in
+            order to maintain a consistent working tree. Instead, it will just check out
+            the files according to their state in the index.
+            If you want :manpage:`git-reset(1)`-like behaviour, use
+            :meth:`HEAD.reset <git.refs.head.HEAD.reset>` instead.
+
+        :return:
+            self
+        """
+        # What we actually want to do is to merge the tree into our existing index,
+        # which is what git-read-tree does.
+        new_inst = type(self).from_tree(self.repo, commit)
+        if not paths:
+            self.entries = new_inst.entries
+        else:
+            nie = new_inst.entries
+            for path in paths:
+                path = self._to_relative_path(path)
+                try:
+                    key = entry_key(path, 0)
+                    self.entries[key] = nie[key]
+                except KeyError:
+                    # If key is not in theirs, it mustn't be in ours.
+                    try:
+                        del self.entries[key]
+                    except KeyError:
+                        pass
+                    # END handle deletion keyerror
+                # END handle keyerror
+            # END for each path
+        # END handle paths
+        self.write()
+
+        if working_tree:
+            self.checkout(paths=paths, force=True)
+        # END handle working tree
+
+        if head:
+            self.repo.head.set_commit(self.repo.commit(commit), logmsg="%s: Updating HEAD" % commit)
+        # END handle head change
+
+        return self
+
+    # FIXME: This is documented to accept the same parameters as Diffable.diff, but this
+    # does not handle NULL_TREE for `other`. (The suppressed mypy error is about this.)
+    def diff(
+        self,
+        other: Union[  # type: ignore[override]
+            Literal[git_diff.DiffConstants.INDEX],
+            "Tree",
+            "Commit",
+            str,
+            None,
+        ] = git_diff.INDEX,
+        paths: Union[PathLike, List[PathLike], Tuple[PathLike, ...], None] = None,
+        create_patch: bool = False,
+        **kwargs: Any,
+    ) -> git_diff.DiffIndex[git_diff.Diff]:
+        """Diff this index against the working copy or a :class:`~git.objects.tree.Tree`
+        or :class:`~git.objects.commit.Commit` object.
+
+        For documentation of the parameters and return values, see
+        :meth:`Diffable.diff <git.diff.Diffable.diff>`.
+
+        :note:
+            Will only work with indices that represent the default git index as they
+            have not been initialized with a stream.
+        """
+        # Only run if we are the default repository index.
+        if self._file_path != self._index_path():
+            raise AssertionError("Cannot call %r on indices that do not represent the default git index" % self.diff())
+        # Index against index is always empty.
+        if other is self.INDEX:
+            return git_diff.DiffIndex()
+
+        # Index against anything but None is a reverse diff with the respective item.
+        # Handle existing -R flags properly.
+        # Transform strings to the object so that we can call diff on it.
+        if isinstance(other, str):
+            other = self.repo.rev_parse(other)
+        # END object conversion
+
+        if isinstance(other, Object):  # For Tree or Commit.
+            # Invert the existing R flag.
+            cur_val = kwargs.get("R", False)
+            kwargs["R"] = not cur_val
+            return other.diff(self.INDEX, paths, create_patch, **kwargs)
+        # END diff against other item handling
+
+        # If other is not None here, something is wrong.
+        if other is not None:
+            raise ValueError("other must be None, Diffable.INDEX, a Tree or Commit, was %r" % other)
+
+        # Diff against working copy - can be handled by superclass natively.
+        return super().diff(other, paths, create_patch, **kwargs)

.venv/lib/python3.11/site-packages/git/index/fun.py

@@ -0,0 +1,465 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Standalone functions to accompany the index implementation and make it more
+versatile."""
+
+__all__ = [
+    "write_cache",
+    "read_cache",
+    "write_tree_from_cache",
+    "entry_key",
+    "stat_mode_to_index_mode",
+    "S_IFGITLINK",
+    "run_commit_hook",
+    "hook_path",
+]
+
+from io import BytesIO
+import os
+import os.path as osp
+from pathlib import Path
+from stat import S_IFDIR, S_IFLNK, S_IFMT, S_IFREG, S_ISDIR, S_ISLNK, S_IXUSR
+import subprocess
+import sys
+
+from gitdb.base import IStream
+from gitdb.typ import str_tree_type
+
+from git.cmd import handle_process_output, safer_popen
+from git.compat import defenc, force_bytes, force_text, safe_decode
+from git.exc import HookExecutionError, UnmergedEntriesError
+from git.objects.fun import (
+    traverse_tree_recursive,
+    traverse_trees_recursive,
+    tree_to_stream,
+)
+from git.util import IndexFileSHA1Writer, finalize_process
+
+from .typ import BaseIndexEntry, IndexEntry, CE_NAMEMASK, CE_STAGESHIFT
+from .util import pack, unpack
+
+# typing -----------------------------------------------------------------------------
+
+from typing import Dict, IO, List, Sequence, TYPE_CHECKING, Tuple, Type, Union, cast
+
+from git.types import PathLike
+
+if TYPE_CHECKING:
+    from git.db import GitCmdObjectDB
+    from git.objects.tree import TreeCacheTup
+
+    from .base import IndexFile
+
+# ------------------------------------------------------------------------------------
+
+S_IFGITLINK = S_IFLNK | S_IFDIR
+"""Flags for a submodule."""
+
+CE_NAMEMASK_INV = ~CE_NAMEMASK
+
+
+def hook_path(name: str, git_dir: PathLike) -> str:
+    """:return: path to the given named hook in the given git repository directory"""
+    return osp.join(git_dir, "hooks", name)
+
+
+def _has_file_extension(path: str) -> str:
+    return osp.splitext(path)[1]
+
+
+def run_commit_hook(name: str, index: "IndexFile", *args: str) -> None:
+    """Run the commit hook of the given name. Silently ignore hooks that do not exist.
+
+    :param name:
+        Name of hook, like ``pre-commit``.
+
+    :param index:
+        :class:`~git.index.base.IndexFile` instance.
+
+    :param args:
+        Arguments passed to hook file.
+
+    :raise git.exc.HookExecutionError:
+    """
+    hp = hook_path(name, index.repo.git_dir)
+    if not os.access(hp, os.X_OK):
+        return
+
+    env = os.environ.copy()
+    env["GIT_INDEX_FILE"] = safe_decode(str(index.path))
+    env["GIT_EDITOR"] = ":"
+    cmd = [hp]
+    try:
+        if sys.platform == "win32" and not _has_file_extension(hp):
+            # Windows only uses extensions to determine how to open files
+            # (doesn't understand shebangs). Try using bash to run the hook.
+            relative_hp = Path(hp).relative_to(index.repo.working_dir).as_posix()
+            cmd = ["bash.exe", relative_hp]
+
+        process = safer_popen(
+            cmd + list(args),
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            cwd=index.repo.working_dir,
+        )
+    except Exception as ex:
+        raise HookExecutionError(hp, ex) from ex
+    else:
+        stdout_list: List[str] = []
+        stderr_list: List[str] = []
+        handle_process_output(process, stdout_list.append, stderr_list.append, finalize_process)
+        stdout = "".join(stdout_list)
+        stderr = "".join(stderr_list)
+        if process.returncode != 0:
+            stdout = force_text(stdout, defenc)
+            stderr = force_text(stderr, defenc)
+            raise HookExecutionError(hp, process.returncode, stderr, stdout)
+    # END handle return code
+
+
+def stat_mode_to_index_mode(mode: int) -> int:
+    """Convert the given mode from a stat call to the corresponding index mode and
+    return it."""
+    if S_ISLNK(mode):  # symlinks
+        return S_IFLNK
+    if S_ISDIR(mode) or S_IFMT(mode) == S_IFGITLINK:  # submodules
+        return S_IFGITLINK
+    return S_IFREG | (mode & S_IXUSR and 0o755 or 0o644)  # blobs with or without executable bit
+
+
+def write_cache(
+    entries: Sequence[Union[BaseIndexEntry, "IndexEntry"]],
+    stream: IO[bytes],
+    extension_data: Union[None, bytes] = None,
+    ShaStreamCls: Type[IndexFileSHA1Writer] = IndexFileSHA1Writer,
+) -> None:
+    """Write the cache represented by entries to a stream.
+
+    :param entries:
+        **Sorted** list of entries.
+
+    :param stream:
+        Stream to wrap into the AdapterStreamCls - it is used for final output.
+
+    :param ShaStreamCls:
+        Type to use when writing to the stream. It produces a sha while writing to it,
+        before the data is passed on to the wrapped stream.
+
+    :param extension_data:
+        Any kind of data to write as a trailer, it must begin a 4 byte identifier,
+        followed by its size (4 bytes).
+    """
+    # Wrap the stream into a compatible writer.
+    stream_sha = ShaStreamCls(stream)
+
+    tell = stream_sha.tell
+    write = stream_sha.write
+
+    # Header
+    version = 2
+    write(b"DIRC")
+    write(pack(">LL", version, len(entries)))
+
+    # Body
+    for entry in entries:
+        beginoffset = tell()
+        write(entry.ctime_bytes)  # ctime
+        write(entry.mtime_bytes)  # mtime
+        path_str = str(entry.path)
+        path: bytes = force_bytes(path_str, encoding=defenc)
+        plen = len(path) & CE_NAMEMASK  # Path length
+        assert plen == len(path), "Path %s too long to fit into index" % entry.path
+        flags = plen | (entry.flags & CE_NAMEMASK_INV)  # Clear possible previous values.
+        write(
+            pack(
+                ">LLLLLL20sH",
+                entry.dev,
+                entry.inode,
+                entry.mode,
+                entry.uid,
+                entry.gid,
+                entry.size,
+                entry.binsha,
+                flags,
+            )
+        )
+        write(path)
+        real_size = (tell() - beginoffset + 8) & ~7
+        write(b"\0" * ((beginoffset + real_size) - tell()))
+    # END for each entry
+
+    # Write previously cached extensions data.
+    if extension_data is not None:
+        stream_sha.write(extension_data)
+
+    # Write the sha over the content.
+    stream_sha.write_sha()
+
+
+def read_header(stream: IO[bytes]) -> Tuple[int, int]:
+    """Return tuple(version_long, num_entries) from the given stream."""
+    type_id = stream.read(4)
+    if type_id != b"DIRC":
+        raise AssertionError("Invalid index file header: %r" % type_id)
+    unpacked = cast(Tuple[int, int], unpack(">LL", stream.read(4 * 2)))
+    version, num_entries = unpacked
+
+    # TODO: Handle version 3: extended data, see read-cache.c.
+    assert version in (1, 2), "Unsupported git index version %i, only 1 and 2 are supported" % version
+    return version, num_entries
+
+
+def entry_key(*entry: Union[BaseIndexEntry, PathLike, int]) -> Tuple[PathLike, int]:
+    """
+    :return:
+        Key suitable to be used for the
+        :attr:`index.entries <git.index.base.IndexFile.entries>` dictionary.
+
+    :param entry:
+        One instance of type BaseIndexEntry or the path and the stage.
+    """
+
+    # def is_entry_key_tup(entry_key: Tuple) -> TypeGuard[Tuple[PathLike, int]]:
+    #     return isinstance(entry_key, tuple) and len(entry_key) == 2
+
+    if len(entry) == 1:
+        entry_first = entry[0]
+        assert isinstance(entry_first, BaseIndexEntry)
+        return (entry_first.path, entry_first.stage)
+    else:
+        # assert is_entry_key_tup(entry)
+        entry = cast(Tuple[PathLike, int], entry)
+        return entry
+    # END handle entry
+
+
+def read_cache(
+    stream: IO[bytes],
+) -> Tuple[int, Dict[Tuple[PathLike, int], "IndexEntry"], bytes, bytes]:
+    """Read a cache file from the given stream.
+
+    :return:
+        tuple(version, entries_dict, extension_data, content_sha)
+
+        * *version* is the integer version number.
+        * *entries_dict* is a dictionary which maps IndexEntry instances to a path at a
+          stage.
+        * *extension_data* is ``""`` or 4 bytes of type + 4 bytes of size + size bytes.
+        * *content_sha* is a 20 byte sha on all cache file contents.
+    """
+    version, num_entries = read_header(stream)
+    count = 0
+    entries: Dict[Tuple[PathLike, int], "IndexEntry"] = {}
+
+    read = stream.read
+    tell = stream.tell
+    while count < num_entries:
+        beginoffset = tell()
+        ctime = unpack(">8s", read(8))[0]
+        mtime = unpack(">8s", read(8))[0]
+        (dev, ino, mode, uid, gid, size, sha, flags) = unpack(">LLLLLL20sH", read(20 + 4 * 6 + 2))
+        path_size = flags & CE_NAMEMASK
+        path = read(path_size).decode(defenc)
+
+        real_size = (tell() - beginoffset + 8) & ~7
+        read((beginoffset + real_size) - tell())
+        entry = IndexEntry((mode, sha, flags, path, ctime, mtime, dev, ino, uid, gid, size))
+        # entry_key would be the method to use, but we save the effort.
+        entries[(path, entry.stage)] = entry
+        count += 1
+    # END for each entry
+
+    # The footer contains extension data and a sha on the content so far.
+    # Keep the extension footer,and verify we have a sha in the end.
+    # Extension data format is:
+    #   4 bytes ID
+    #   4 bytes length of chunk
+    #   Repeated 0 - N times
+    extension_data = stream.read(~0)
+    assert len(extension_data) > 19, (
+        "Index Footer was not at least a sha on content as it was only %i bytes in size" % len(extension_data)
+    )
+
+    content_sha = extension_data[-20:]
+
+    # Truncate the sha in the end as we will dynamically create it anyway.
+    extension_data = extension_data[:-20]
+
+    return (version, entries, extension_data, content_sha)
+
+
+def write_tree_from_cache(
+    entries: List[IndexEntry], odb: "GitCmdObjectDB", sl: slice, si: int = 0
+) -> Tuple[bytes, List["TreeCacheTup"]]:
+    R"""Create a tree from the given sorted list of entries and put the respective
+    trees into the given object database.
+
+    :param entries:
+        **Sorted** list of :class:`~git.index.typ.IndexEntry`\s.
+
+    :param odb:
+        Object database to store the trees in.
+
+    :param si:
+        Start index at which we should start creating subtrees.
+
+    :param sl:
+        Slice indicating the range we should process on the entries list.
+
+    :return:
+        tuple(binsha, list(tree_entry, ...))
+
+        A tuple of a sha and a list of tree entries being a tuple of hexsha, mode, name.
+    """
+    tree_items: List["TreeCacheTup"] = []
+
+    ci = sl.start
+    end = sl.stop
+    while ci < end:
+        entry = entries[ci]
+        if entry.stage != 0:
+            raise UnmergedEntriesError(entry)
+        # END abort on unmerged
+        ci += 1
+        rbound = entry.path.find("/", si)
+        if rbound == -1:
+            # It's not a tree.
+            tree_items.append((entry.binsha, entry.mode, entry.path[si:]))
+        else:
+            # Find common base range.
+            base = entry.path[si:rbound]
+            xi = ci
+            while xi < end:
+                oentry = entries[xi]
+                orbound = oentry.path.find("/", si)
+                if orbound == -1 or oentry.path[si:orbound] != base:
+                    break
+                # END abort on base mismatch
+                xi += 1
+            # END find common base
+
+            # Enter recursion.
+            # ci - 1 as we want to count our current item as well.
+            sha, _tree_entry_list = write_tree_from_cache(entries, odb, slice(ci - 1, xi), rbound + 1)
+            tree_items.append((sha, S_IFDIR, base))
+
+            # Skip ahead.
+            ci = xi
+        # END handle bounds
+    # END for each entry
+
+    # Finally create the tree.
+    sio = BytesIO()
+    tree_to_stream(tree_items, sio.write)  # Writes to stream as bytes, but doesn't change tree_items.
+    sio.seek(0)
+
+    istream = odb.store(IStream(str_tree_type, len(sio.getvalue()), sio))
+    return (istream.binsha, tree_items)
+
+
+def _tree_entry_to_baseindexentry(tree_entry: "TreeCacheTup", stage: int) -> BaseIndexEntry:
+    return BaseIndexEntry((tree_entry[1], tree_entry[0], stage << CE_STAGESHIFT, tree_entry[2]))
+
+
+def aggressive_tree_merge(odb: "GitCmdObjectDB", tree_shas: Sequence[bytes]) -> List[BaseIndexEntry]:
+    R"""
+    :return:
+        List of :class:`~git.index.typ.BaseIndexEntry`\s representing the aggressive
+        merge of the given trees. All valid entries are on stage 0, whereas the
+        conflicting ones are left on stage 1, 2 or 3, whereas stage 1 corresponds to the
+        common ancestor tree, 2 to our tree and 3 to 'their' tree.
+
+    :param tree_shas:
+        1, 2 or 3 trees as identified by their binary 20 byte shas. If 1 or two, the
+        entries will effectively correspond to the last given tree. If 3 are given, a 3
+        way merge is performed.
+    """
+    out: List[BaseIndexEntry] = []
+
+    # One and two way is the same for us, as we don't have to handle an existing
+    # index, instrea
+    if len(tree_shas) in (1, 2):
+        for entry in traverse_tree_recursive(odb, tree_shas[-1], ""):
+            out.append(_tree_entry_to_baseindexentry(entry, 0))
+        # END for each entry
+        return out
+    # END handle single tree
+
+    if len(tree_shas) > 3:
+        raise ValueError("Cannot handle %i trees at once" % len(tree_shas))
+
+    # Three trees.
+    for base, ours, theirs in traverse_trees_recursive(odb, tree_shas, ""):
+        if base is not None:
+            # Base version exists.
+            if ours is not None:
+                # Ours exists.
+                if theirs is not None:
+                    # It exists in all branches. Ff it was changed in both
+                    # its a conflict. Otherwise, we take the changed version.
+                    # This should be the most common branch, so it comes first.
+                    if (base[0] != ours[0] and base[0] != theirs[0] and ours[0] != theirs[0]) or (
+                        base[1] != ours[1] and base[1] != theirs[1] and ours[1] != theirs[1]
+                    ):
+                        # Changed by both.
+                        out.append(_tree_entry_to_baseindexentry(base, 1))
+                        out.append(_tree_entry_to_baseindexentry(ours, 2))
+                        out.append(_tree_entry_to_baseindexentry(theirs, 3))
+                    elif base[0] != ours[0] or base[1] != ours[1]:
+                        # Only we changed it.
+                        out.append(_tree_entry_to_baseindexentry(ours, 0))
+                    else:
+                        # Either nobody changed it, or they did. In either
+                        # case, use theirs.
+                        out.append(_tree_entry_to_baseindexentry(theirs, 0))
+                    # END handle modification
+                else:
+                    if ours[0] != base[0] or ours[1] != base[1]:
+                        # They deleted it, we changed it, conflict.
+                        out.append(_tree_entry_to_baseindexentry(base, 1))
+                        out.append(_tree_entry_to_baseindexentry(ours, 2))
+                    # else:
+                    #   # We didn't change it, ignore.
+                    #   pass
+                    # END handle our change
+                # END handle theirs
+            else:
+                if theirs is None:
+                    # Deleted in both, its fine - it's out.
+                    pass
+                else:
+                    if theirs[0] != base[0] or theirs[1] != base[1]:
+                        # Deleted in ours, changed theirs, conflict.
+                        out.append(_tree_entry_to_baseindexentry(base, 1))
+                        out.append(_tree_entry_to_baseindexentry(theirs, 3))
+                    # END theirs changed
+                    # else:
+                    #   # Theirs didn't change.
+                    #   pass
+                # END handle theirs
+            # END handle ours
+        else:
+            # All three can't be None.
+            if ours is None:
+                # Added in their branch.
+                assert theirs is not None
+                out.append(_tree_entry_to_baseindexentry(theirs, 0))
+            elif theirs is None:
+                # Added in our branch.
+                out.append(_tree_entry_to_baseindexentry(ours, 0))
+            else:
+                # Both have it, except for the base, see whether it changed.
+                if ours[0] != theirs[0] or ours[1] != theirs[1]:
+                    out.append(_tree_entry_to_baseindexentry(ours, 2))
+                    out.append(_tree_entry_to_baseindexentry(theirs, 3))
+                else:
+                    # It was added the same in both.
+                    out.append(_tree_entry_to_baseindexentry(ours, 0))
+                # END handle two items
+            # END handle heads
+        # END handle base exists
+    # END for each entries tuple
+
+    return out

.venv/lib/python3.11/site-packages/git/index/typ.py

@@ -0,0 +1,202 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Additional types used by the index."""
+
+__all__ = ["BlobFilter", "BaseIndexEntry", "IndexEntry", "StageType"]
+
+from binascii import b2a_hex
+from pathlib import Path
+
+from git.objects import Blob
+
+from .util import pack, unpack
+
+# typing ----------------------------------------------------------------------
+
+from typing import NamedTuple, Sequence, TYPE_CHECKING, Tuple, Union, cast
+
+from git.types import PathLike
+
+if TYPE_CHECKING:
+    from git.repo import Repo
+
+StageType = int
+
+# ---------------------------------------------------------------------------------
+
+# { Invariants
+CE_NAMEMASK = 0x0FFF
+CE_STAGEMASK = 0x3000
+CE_EXTENDED = 0x4000
+CE_VALID = 0x8000
+CE_STAGESHIFT = 12
+
+# } END invariants
+
+
+class BlobFilter:
+    """Predicate to be used by
+    :meth:`IndexFile.iter_blobs <git.index.base.IndexFile.iter_blobs>` allowing to
+    filter only return blobs which match the given list of directories or files.
+
+    The given paths are given relative to the repository.
+    """
+
+    __slots__ = ("paths",)
+
+    def __init__(self, paths: Sequence[PathLike]) -> None:
+        """
+        :param paths:
+            Tuple or list of paths which are either pointing to directories or to files
+            relative to the current repository.
+        """
+        self.paths = paths
+
+    def __call__(self, stage_blob: Tuple[StageType, Blob]) -> bool:
+        blob_pathlike: PathLike = stage_blob[1].path
+        blob_path: Path = blob_pathlike if isinstance(blob_pathlike, Path) else Path(blob_pathlike)
+        for pathlike in self.paths:
+            path: Path = pathlike if isinstance(pathlike, Path) else Path(pathlike)
+            # TODO: Change to use `PosixPath.is_relative_to` once Python 3.8 is no
+            # longer supported.
+            filter_parts = path.parts
+            blob_parts = blob_path.parts
+            if len(filter_parts) > len(blob_parts):
+                continue
+            if all(i == j for i, j in zip(filter_parts, blob_parts)):
+                return True
+        return False
+
+
+class BaseIndexEntryHelper(NamedTuple):
+    """Typed named tuple to provide named attribute access for :class:`BaseIndexEntry`.
+
+    This is needed to allow overriding ``__new__`` in child class to preserve backwards
+    compatibility.
+    """
+
+    mode: int
+    binsha: bytes
+    flags: int
+    path: PathLike
+    ctime_bytes: bytes = pack(">LL", 0, 0)
+    mtime_bytes: bytes = pack(">LL", 0, 0)
+    dev: int = 0
+    inode: int = 0
+    uid: int = 0
+    gid: int = 0
+    size: int = 0
+
+
+class BaseIndexEntry(BaseIndexEntryHelper):
+    R"""Small brother of an index entry which can be created to describe changes
+    done to the index in which case plenty of additional information is not required.
+
+    As the first 4 data members match exactly to the :class:`IndexEntry` type, methods
+    expecting a :class:`BaseIndexEntry` can also handle full :class:`IndexEntry`\s even
+    if they use numeric indices for performance reasons.
+    """
+
+    def __new__(
+        cls,
+        inp_tuple: Union[
+            Tuple[int, bytes, int, PathLike],
+            Tuple[int, bytes, int, PathLike, bytes, bytes, int, int, int, int, int],
+        ],
+    ) -> "BaseIndexEntry":
+        """Override ``__new__`` to allow construction from a tuple for backwards
+        compatibility."""
+        return super().__new__(cls, *inp_tuple)
+
+    def __str__(self) -> str:
+        return "%o %s %i\t%s" % (self.mode, self.hexsha, self.stage, self.path)
+
+    def __repr__(self) -> str:
+        return "(%o, %s, %i, %s)" % (self.mode, self.hexsha, self.stage, self.path)
+
+    @property
+    def hexsha(self) -> str:
+        """hex version of our sha"""
+        return b2a_hex(self.binsha).decode("ascii")
+
+    @property
+    def stage(self) -> int:
+        """Stage of the entry, either:
+
+            * 0 = default stage
+            * 1 = stage before a merge or common ancestor entry in case of a 3 way merge
+            * 2 = stage of entries from the 'left' side of the merge
+            * 3 = stage of entries from the 'right' side of the merge
+
+        :note:
+            For more information, see :manpage:`git-read-tree(1)`.
+        """
+        return (self.flags & CE_STAGEMASK) >> CE_STAGESHIFT
+
+    @classmethod
+    def from_blob(cls, blob: Blob, stage: int = 0) -> "BaseIndexEntry":
+        """:return: Fully equipped BaseIndexEntry at the given stage"""
+        return cls((blob.mode, blob.binsha, stage << CE_STAGESHIFT, blob.path))
+
+    def to_blob(self, repo: "Repo") -> Blob:
+        """:return: Blob using the information of this index entry"""
+        return Blob(repo, self.binsha, self.mode, self.path)
+
+
+class IndexEntry(BaseIndexEntry):
+    """Allows convenient access to index entry data as defined in
+    :class:`BaseIndexEntry` without completely unpacking it.
+
+    Attributes usually accessed often are cached in the tuple whereas others are
+    unpacked on demand.
+
+    See the properties for a mapping between names and tuple indices.
+    """
+
+    @property
+    def ctime(self) -> Tuple[int, int]:
+        """
+        :return:
+            Tuple(int_time_seconds_since_epoch, int_nano_seconds) of the
+            file's creation time
+        """
+        return cast(Tuple[int, int], unpack(">LL", self.ctime_bytes))
+
+    @property
+    def mtime(self) -> Tuple[int, int]:
+        """See :attr:`ctime` property, but returns modification time."""
+        return cast(Tuple[int, int], unpack(">LL", self.mtime_bytes))
+
+    @classmethod
+    def from_base(cls, base: "BaseIndexEntry") -> "IndexEntry":
+        """
+        :return:
+            Minimal entry as created from the given :class:`BaseIndexEntry` instance.
+            Missing values will be set to null-like values.
+
+        :param base:
+            Instance of type :class:`BaseIndexEntry`.
+        """
+        time = pack(">LL", 0, 0)
+        return IndexEntry((base.mode, base.binsha, base.flags, base.path, time, time, 0, 0, 0, 0, 0))
+
+    @classmethod
+    def from_blob(cls, blob: Blob, stage: int = 0) -> "IndexEntry":
+        """:return: Minimal entry resembling the given blob object"""
+        time = pack(">LL", 0, 0)
+        return IndexEntry(
+            (
+                blob.mode,
+                blob.binsha,
+                stage << CE_STAGESHIFT,
+                blob.path,
+                time,
+                time,
+                0,
+                0,
+                0,
+                0,
+                blob.size,
+            )
+        )

.venv/lib/python3.11/site-packages/git/index/util.py

@@ -0,0 +1,121 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Index utilities."""
+
+__all__ = ["TemporaryFileSwap", "post_clear_cache", "default_index", "git_working_dir"]
+
+import contextlib
+from functools import wraps
+import os
+import os.path as osp
+import struct
+import tempfile
+from types import TracebackType
+
+# typing ----------------------------------------------------------------------
+
+from typing import Any, Callable, TYPE_CHECKING, Optional, Type
+
+from git.types import Literal, PathLike, _T
+
+if TYPE_CHECKING:
+    from git.index import IndexFile
+
+# ---------------------------------------------------------------------------------
+
+# { Aliases
+pack = struct.pack
+unpack = struct.unpack
+# } END aliases
+
+
+class TemporaryFileSwap:
+    """Utility class moving a file to a temporary location within the same directory and
+    moving it back on to where on object deletion."""
+
+    __slots__ = ("file_path", "tmp_file_path")
+
+    def __init__(self, file_path: PathLike) -> None:
+        self.file_path = file_path
+        dirname, basename = osp.split(file_path)
+        fd, self.tmp_file_path = tempfile.mkstemp(prefix=basename, dir=dirname)
+        os.close(fd)
+        with contextlib.suppress(OSError):  # It may be that the source does not exist.
+            os.replace(self.file_path, self.tmp_file_path)
+
+    def __enter__(self) -> "TemporaryFileSwap":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: Optional[Type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> Literal[False]:
+        if osp.isfile(self.tmp_file_path):
+            os.replace(self.tmp_file_path, self.file_path)
+        return False
+
+
+# { Decorators
+
+
+def post_clear_cache(func: Callable[..., _T]) -> Callable[..., _T]:
+    """Decorator for functions that alter the index using the git command.
+
+    When a git command alters the index, this invalidates our possibly existing entries
+    dictionary, which is why it must be deleted to allow it to be lazily reread later.
+    """
+
+    @wraps(func)
+    def post_clear_cache_if_not_raised(self: "IndexFile", *args: Any, **kwargs: Any) -> _T:
+        rval = func(self, *args, **kwargs)
+        self._delete_entries_cache()
+        return rval
+
+    # END wrapper method
+
+    return post_clear_cache_if_not_raised
+
+
+def default_index(func: Callable[..., _T]) -> Callable[..., _T]:
+    """Decorator ensuring the wrapped method may only run if we are the default
+    repository index.
+
+    This is as we rely on git commands that operate on that index only.
+    """
+
+    @wraps(func)
+    def check_default_index(self: "IndexFile", *args: Any, **kwargs: Any) -> _T:
+        if self._file_path != self._index_path():
+            raise AssertionError(
+                "Cannot call %r on indices that do not represent the default git index" % func.__name__
+            )
+        return func(self, *args, **kwargs)
+
+    # END wrapper method
+
+    return check_default_index
+
+
+def git_working_dir(func: Callable[..., _T]) -> Callable[..., _T]:
+    """Decorator which changes the current working dir to the one of the git
+    repository in order to ensure relative paths are handled correctly."""
+
+    @wraps(func)
+    def set_git_working_dir(self: "IndexFile", *args: Any, **kwargs: Any) -> _T:
+        cur_wd = os.getcwd()
+        os.chdir(str(self.repo.working_tree_dir))
+        try:
+            return func(self, *args, **kwargs)
+        finally:
+            os.chdir(cur_wd)
+        # END handle working dir
+
+    # END wrapper
+
+    return set_git_working_dir
+
+
+# } END decorators

.venv/lib/python3.11/site-packages/git/objects/__init__.py

@@ -0,0 +1,25 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Import all submodules' main classes into the package space."""
+
+__all__ = [
+    "IndexObject",
+    "Object",
+    "Blob",
+    "Commit",
+    "Submodule",
+    "UpdateProgress",
+    "RootModule",
+    "RootUpdateProgress",
+    "TagObject",
+    "Tree",
+    "TreeModifier",
+]
+
+from .base import IndexObject, Object
+from .blob import Blob
+from .commit import Commit
+from .submodule import RootModule, RootUpdateProgress, Submodule, UpdateProgress
+from .tag import TagObject
+from .tree import Tree, TreeModifier

.venv/lib/python3.11/site-packages/git/objects/base.py

@@ -0,0 +1,301 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+__all__ = ["Object", "IndexObject"]
+
+import os.path as osp
+
+import gitdb.typ as dbtyp
+
+from git.exc import WorkTreeRepositoryUnsupported
+from git.util import LazyMixin, bin_to_hex, join_path_native, stream_copy
+
+from .util import get_object_type_by_name
+
+# typing ------------------------------------------------------------------
+
+from typing import Any, TYPE_CHECKING, Union
+
+from git.types import AnyGitObject, GitObjectTypeString, PathLike
+
+if TYPE_CHECKING:
+    from gitdb.base import OStream
+
+    from git.refs.reference import Reference
+    from git.repo import Repo
+
+    from .blob import Blob
+    from .submodule.base import Submodule
+    from .tree import Tree
+
+IndexObjUnion = Union["Tree", "Blob", "Submodule"]
+
+# --------------------------------------------------------------------------
+
+
+class Object(LazyMixin):
+    """Base class for classes representing git object types.
+
+    The following four leaf classes represent specific kinds of git objects:
+
+    * :class:`Blob <git.objects.blob.Blob>`
+    * :class:`Tree <git.objects.tree.Tree>`
+    * :class:`Commit <git.objects.commit.Commit>`
+    * :class:`TagObject <git.objects.tag.TagObject>`
+
+    See :manpage:`gitglossary(7)` on:
+
+    * "object": https://git-scm.com/docs/gitglossary#def_object
+    * "object type": https://git-scm.com/docs/gitglossary#def_object_type
+    * "blob": https://git-scm.com/docs/gitglossary#def_blob_object
+    * "tree object": https://git-scm.com/docs/gitglossary#def_tree_object
+    * "commit object": https://git-scm.com/docs/gitglossary#def_commit_object
+    * "tag object": https://git-scm.com/docs/gitglossary#def_tag_object
+
+    :note:
+        See the :class:`~git.types.AnyGitObject` union type of the four leaf subclasses
+        that represent actual git object types.
+
+    :note:
+        :class:`~git.objects.submodule.base.Submodule` is defined under the hierarchy
+        rooted at this :class:`Object` class, even though submodules are not really a
+        type of git object. (This also applies to its
+        :class:`~git.objects.submodule.root.RootModule` subclass.)
+
+    :note:
+        This :class:`Object` class should not be confused with :class:`object` (the root
+        of the class hierarchy in Python).
+    """
+
+    NULL_HEX_SHA = "0" * 40
+    NULL_BIN_SHA = b"\0" * 20
+
+    TYPES = (
+        dbtyp.str_blob_type,
+        dbtyp.str_tree_type,
+        dbtyp.str_commit_type,
+        dbtyp.str_tag_type,
+    )
+
+    __slots__ = ("repo", "binsha", "size")
+
+    type: Union[GitObjectTypeString, None] = None
+    """String identifying (a concrete :class:`Object` subtype for) a git object type.
+
+    The subtypes that this may name correspond to the kinds of git objects that exist,
+    i.e., the objects that may be present in a git repository.
+
+    :note:
+        Most subclasses represent specific types of git objects and override this class
+        attribute accordingly. This attribute is ``None`` in the :class:`Object` base
+        class, as well as the :class:`IndexObject` intermediate subclass, but never
+        ``None`` in concrete leaf subclasses representing specific git object types.
+
+    :note:
+        See also :class:`~git.types.GitObjectTypeString`.
+    """
+
+    def __init__(self, repo: "Repo", binsha: bytes) -> None:
+        """Initialize an object by identifying it by its binary sha.
+
+        All keyword arguments will be set on demand if ``None``.
+
+        :param repo:
+            Repository this object is located in.
+
+        :param binsha:
+            20 byte SHA1
+        """
+        super().__init__()
+        self.repo = repo
+        self.binsha = binsha
+        assert len(binsha) == 20, "Require 20 byte binary sha, got %r, len = %i" % (
+            binsha,
+            len(binsha),
+        )
+
+    @classmethod
+    def new(cls, repo: "Repo", id: Union[str, "Reference"]) -> AnyGitObject:
+        """
+        :return:
+            New :class:`Object` instance of a type appropriate to the object type behind
+            `id`. The id of the newly created object will be a binsha even though the
+            input id may have been a :class:`~git.refs.reference.Reference` or rev-spec.
+
+        :param id:
+            :class:`~git.refs.reference.Reference`, rev-spec, or hexsha.
+
+        :note:
+            This cannot be a ``__new__`` method as it would always call :meth:`__init__`
+            with the input id which is not necessarily a binsha.
+        """
+        return repo.rev_parse(str(id))
+
+    @classmethod
+    def new_from_sha(cls, repo: "Repo", sha1: bytes) -> AnyGitObject:
+        """
+        :return:
+            New object instance of a type appropriate to represent the given binary sha1
+
+        :param sha1:
+            20 byte binary sha1.
+        """
+        if sha1 == cls.NULL_BIN_SHA:
+            # The NULL binsha is always the root commit.
+            return get_object_type_by_name(b"commit")(repo, sha1)
+        # END handle special case
+        oinfo = repo.odb.info(sha1)
+        inst = get_object_type_by_name(oinfo.type)(repo, oinfo.binsha)
+        inst.size = oinfo.size
+        return inst
+
+    def _set_cache_(self, attr: str) -> None:
+        """Retrieve object information."""
+        if attr == "size":
+            oinfo = self.repo.odb.info(self.binsha)
+            self.size = oinfo.size  # type: int
+        else:
+            super()._set_cache_(attr)
+
+    def __eq__(self, other: Any) -> bool:
+        """:return: ``True`` if the objects have the same SHA1"""
+        if not hasattr(other, "binsha"):
+            return False
+        return self.binsha == other.binsha
+
+    def __ne__(self, other: Any) -> bool:
+        """:return: ``True`` if the objects do not have the same SHA1"""
+        if not hasattr(other, "binsha"):
+            return True
+        return self.binsha != other.binsha
+
+    def __hash__(self) -> int:
+        """:return: Hash of our id allowing objects to be used in dicts and sets"""
+        return hash(self.binsha)
+
+    def __str__(self) -> str:
+        """:return: String of our SHA1 as understood by all git commands"""
+        return self.hexsha
+
+    def __repr__(self) -> str:
+        """:return: String with pythonic representation of our object"""
+        return '<git.%s "%s">' % (self.__class__.__name__, self.hexsha)
+
+    @property
+    def hexsha(self) -> str:
+        """:return: 40 byte hex version of our 20 byte binary sha"""
+        # b2a_hex produces bytes.
+        return bin_to_hex(self.binsha).decode("ascii")
+
+    @property
+    def data_stream(self) -> "OStream":
+        """
+        :return:
+            File-object compatible stream to the uncompressed raw data of the object
+
+        :note:
+            Returned streams must be read in order.
+        """
+        return self.repo.odb.stream(self.binsha)
+
+    def stream_data(self, ostream: "OStream") -> "Object":
+        """Write our data directly to the given output stream.
+
+        :param ostream:
+            File-object compatible stream object.
+
+        :return:
+            self
+        """
+        istream = self.repo.odb.stream(self.binsha)
+        stream_copy(istream, ostream)
+        return self
+
+
+class IndexObject(Object):
+    """Base for all objects that can be part of the index file.
+
+    The classes representing git object types that can be part of the index file are
+    :class:`~git.objects.tree.Tree` and :class:`~git.objects.blob.Blob`. In addition,
+    :class:`~git.objects.submodule.base.Submodule`, which is not really a git object
+    type but can be part of an index file, is also a subclass.
+    """
+
+    __slots__ = ("path", "mode")
+
+    # For compatibility with iterable lists.
+    _id_attribute_ = "path"
+
+    def __init__(
+        self,
+        repo: "Repo",
+        binsha: bytes,
+        mode: Union[None, int] = None,
+        path: Union[None, PathLike] = None,
+    ) -> None:
+        """Initialize a newly instanced :class:`IndexObject`.
+
+        :param repo:
+            The :class:`~git.repo.base.Repo` we are located in.
+
+        :param binsha:
+            20 byte sha1.
+
+        :param mode:
+            The stat-compatible file mode as :class:`int`.
+            Use the :mod:`stat` module to evaluate the information.
+
+        :param path:
+            The path to the file in the file system, relative to the git repository
+            root, like ``file.ext`` or ``folder/other.ext``.
+
+        :note:
+            Path may not be set if the index object has been created directly, as it
+            cannot be retrieved without knowing the parent tree.
+        """
+        super().__init__(repo, binsha)
+        if mode is not None:
+            self.mode = mode
+        if path is not None:
+            self.path = path
+
+    def __hash__(self) -> int:
+        """
+        :return:
+            Hash of our path as index items are uniquely identifiable by path, not by
+            their data!
+        """
+        return hash(self.path)
+
+    def _set_cache_(self, attr: str) -> None:
+        if attr in IndexObject.__slots__:
+            # They cannot be retrieved later on (not without searching for them).
+            raise AttributeError(
+                "Attribute '%s' unset: path and mode attributes must have been set during %s object creation"
+                % (attr, type(self).__name__)
+            )
+        else:
+            super()._set_cache_(attr)
+        # END handle slot attribute
+
+    @property
+    def name(self) -> str:
+        """:return: Name portion of the path, effectively being the basename"""
+        return osp.basename(self.path)
+
+    @property
+    def abspath(self) -> PathLike:
+        R"""
+        :return:
+            Absolute path to this index object in the file system (as opposed to the
+            :attr:`path` field which is a path relative to the git repository).
+
+            The returned path will be native to the system and contains ``\`` on
+            Windows.
+        """
+        if self.repo.working_tree_dir is not None:
+            return join_path_native(self.repo.working_tree_dir, self.path)
+        else:
+            raise WorkTreeRepositoryUnsupported("working_tree_dir was None or empty")

.venv/lib/python3.11/site-packages/git/objects/blob.py

@@ -0,0 +1,48 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+__all__ = ["Blob"]
+
+from mimetypes import guess_type
+import sys
+
+if sys.version_info >= (3, 8):
+    from typing import Literal
+else:
+    from typing_extensions import Literal
+
+from . import base
+
+
+class Blob(base.IndexObject):
+    """A Blob encapsulates a git blob object.
+
+    See :manpage:`gitglossary(7)` on "blob":
+    https://git-scm.com/docs/gitglossary#def_blob_object
+    """
+
+    DEFAULT_MIME_TYPE = "text/plain"
+    type: Literal["blob"] = "blob"
+
+    # Valid blob modes
+    executable_mode = 0o100755
+    file_mode = 0o100644
+    link_mode = 0o120000
+
+    __slots__ = ()
+
+    @property
+    def mime_type(self) -> str:
+        """
+        :return:
+            String describing the mime type of this file (based on the filename)
+
+        :note:
+            Defaults to ``text/plain`` in case the actual file type is unknown.
+        """
+        guesses = None
+        if self.path:
+            guesses = guess_type(str(self.path))
+        return guesses and guesses[0] or self.DEFAULT_MIME_TYPE

.venv/lib/python3.11/site-packages/git/objects/commit.py

@@ -0,0 +1,909 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+__all__ = ["Commit"]
+
+from collections import defaultdict
+import datetime
+from io import BytesIO
+import logging
+import os
+import re
+from subprocess import Popen, PIPE
+import sys
+from time import altzone, daylight, localtime, time, timezone
+import warnings
+
+from gitdb import IStream
+
+from git.cmd import Git
+from git.diff import Diffable
+from git.util import Actor, Stats, finalize_process, hex_to_bin
+
+from . import base
+from .tree import Tree
+from .util import (
+    Serializable,
+    TraversableIterableObj,
+    altz_to_utctz_str,
+    from_timestamp,
+    parse_actor_and_date,
+    parse_date,
+)
+
+# typing ------------------------------------------------------------------
+
+from typing import (
+    Any,
+    Dict,
+    IO,
+    Iterator,
+    List,
+    Sequence,
+    Tuple,
+    TYPE_CHECKING,
+    Union,
+    cast,
+)
+
+if sys.version_info >= (3, 8):
+    from typing import Literal
+else:
+    from typing_extensions import Literal
+
+from git.types import PathLike
+
+if TYPE_CHECKING:
+    from git.refs import SymbolicReference
+    from git.repo import Repo
+
+# ------------------------------------------------------------------------
+
+_logger = logging.getLogger(__name__)
+
+
+class Commit(base.Object, TraversableIterableObj, Diffable, Serializable):
+    """Wraps a git commit object.
+
+    See :manpage:`gitglossary(7)` on "commit object":
+    https://git-scm.com/docs/gitglossary#def_commit_object
+
+    :note:
+        This class will act lazily on some of its attributes and will query the value on
+        demand only if it involves calling the git binary.
+    """
+
+    # ENVIRONMENT VARIABLES
+    # Read when creating new commits.
+    env_author_date = "GIT_AUTHOR_DATE"
+    env_committer_date = "GIT_COMMITTER_DATE"
+
+    # CONFIGURATION KEYS
+    conf_encoding = "i18n.commitencoding"
+
+    # INVARIANTS
+    default_encoding = "UTF-8"
+
+    type: Literal["commit"] = "commit"
+
+    __slots__ = (
+        "tree",
+        "author",
+        "authored_date",
+        "author_tz_offset",
+        "committer",
+        "committed_date",
+        "committer_tz_offset",
+        "message",
+        "parents",
+        "encoding",
+        "gpgsig",
+    )
+
+    _id_attribute_ = "hexsha"
+
+    parents: Sequence["Commit"]
+
+    def __init__(
+        self,
+        repo: "Repo",
+        binsha: bytes,
+        tree: Union[Tree, None] = None,
+        author: Union[Actor, None] = None,
+        authored_date: Union[int, None] = None,
+        author_tz_offset: Union[None, float] = None,
+        committer: Union[Actor, None] = None,
+        committed_date: Union[int, None] = None,
+        committer_tz_offset: Union[None, float] = None,
+        message: Union[str, bytes, None] = None,
+        parents: Union[Sequence["Commit"], None] = None,
+        encoding: Union[str, None] = None,
+        gpgsig: Union[str, None] = None,
+    ) -> None:
+        """Instantiate a new :class:`Commit`. All keyword arguments taking ``None`` as
+        default will be implicitly set on first query.
+
+        :param binsha:
+            20 byte sha1.
+
+        :param tree:
+            A :class:`~git.objects.tree.Tree` object.
+
+        :param author:
+            The author :class:`~git.util.Actor` object.
+
+        :param authored_date: int_seconds_since_epoch
+            The authored DateTime - use :func:`time.gmtime` to convert it into a
+            different format.
+
+        :param author_tz_offset: int_seconds_west_of_utc
+            The timezone that the `authored_date` is in.
+
+        :param committer:
+            The committer string, as an :class:`~git.util.Actor` object.
+
+        :param committed_date: int_seconds_since_epoch
+            The committed DateTime - use :func:`time.gmtime` to convert it into a
+            different format.
+
+        :param committer_tz_offset: int_seconds_west_of_utc
+            The timezone that the `committed_date` is in.
+
+        :param message: string
+            The commit message.
+
+        :param encoding: string
+            Encoding of the message, defaults to UTF-8.
+
+        :param parents:
+            List or tuple of :class:`Commit` objects which are our parent(s) in the
+            commit dependency graph.
+
+        :return:
+            :class:`Commit`
+
+        :note:
+            Timezone information is in the same format and in the same sign as what
+            :func:`time.altzone` returns. The sign is inverted compared to git's UTC
+            timezone.
+        """
+        super().__init__(repo, binsha)
+        self.binsha = binsha
+        if tree is not None:
+            assert isinstance(tree, Tree), "Tree needs to be a Tree instance, was %s" % type(tree)
+        if tree is not None:
+            self.tree = tree
+        if author is not None:
+            self.author = author
+        if authored_date is not None:
+            self.authored_date = authored_date
+        if author_tz_offset is not None:
+            self.author_tz_offset = author_tz_offset
+        if committer is not None:
+            self.committer = committer
+        if committed_date is not None:
+            self.committed_date = committed_date
+        if committer_tz_offset is not None:
+            self.committer_tz_offset = committer_tz_offset
+        if message is not None:
+            self.message = message
+        if parents is not None:
+            self.parents = parents
+        if encoding is not None:
+            self.encoding = encoding
+        if gpgsig is not None:
+            self.gpgsig = gpgsig
+
+    @classmethod
+    def _get_intermediate_items(cls, commit: "Commit") -> Tuple["Commit", ...]:
+        return tuple(commit.parents)
+
+    @classmethod
+    def _calculate_sha_(cls, repo: "Repo", commit: "Commit") -> bytes:
+        """Calculate the sha of a commit.
+
+        :param repo:
+            :class:`~git.repo.base.Repo` object the commit should be part of.
+
+        :param commit:
+            :class:`Commit` object for which to generate the sha.
+        """
+
+        stream = BytesIO()
+        commit._serialize(stream)
+        streamlen = stream.tell()
+        stream.seek(0)
+
+        istream = repo.odb.store(IStream(cls.type, streamlen, stream))
+        return istream.binsha
+
+    def replace(self, **kwargs: Any) -> "Commit":
+        """Create new commit object from an existing commit object.
+
+        Any values provided as keyword arguments will replace the corresponding
+        attribute in the new object.
+        """
+
+        attrs = {k: getattr(self, k) for k in self.__slots__}
+
+        for attrname in kwargs:
+            if attrname not in self.__slots__:
+                raise ValueError("invalid attribute name")
+
+        attrs.update(kwargs)
+        new_commit = self.__class__(self.repo, self.NULL_BIN_SHA, **attrs)
+        new_commit.binsha = self._calculate_sha_(self.repo, new_commit)
+
+        return new_commit
+
+    def _set_cache_(self, attr: str) -> None:
+        if attr in Commit.__slots__:
+            # Read the data in a chunk, its faster - then provide a file wrapper.
+            _binsha, _typename, self.size, stream = self.repo.odb.stream(self.binsha)
+            self._deserialize(BytesIO(stream.read()))
+        else:
+            super()._set_cache_(attr)
+        # END handle attrs
+
+    @property
+    def authored_datetime(self) -> datetime.datetime:
+        return from_timestamp(self.authored_date, self.author_tz_offset)
+
+    @property
+    def committed_datetime(self) -> datetime.datetime:
+        return from_timestamp(self.committed_date, self.committer_tz_offset)
+
+    @property
+    def summary(self) -> Union[str, bytes]:
+        """:return: First line of the commit message"""
+        if isinstance(self.message, str):
+            return self.message.split("\n", 1)[0]
+        else:
+            return self.message.split(b"\n", 1)[0]
+
+    def count(self, paths: Union[PathLike, Sequence[PathLike]] = "", **kwargs: Any) -> int:
+        """Count the number of commits reachable from this commit.
+
+        :param paths:
+            An optional path or a list of paths restricting the return value to commits
+            actually containing the paths.
+
+        :param kwargs:
+            Additional options to be passed to :manpage:`git-rev-list(1)`. They must not
+            alter the output style of the command, or parsing will yield incorrect
+            results.
+
+        :return:
+            An int defining the number of reachable commits
+        """
+        # Yes, it makes a difference whether empty paths are given or not in our case as
+        # the empty paths version will ignore merge commits for some reason.
+        if paths:
+            return len(self.repo.git.rev_list(self.hexsha, "--", paths, **kwargs).splitlines())
+        return len(self.repo.git.rev_list(self.hexsha, **kwargs).splitlines())
+
+    @property
+    def name_rev(self) -> str:
+        """
+        :return:
+            String describing the commits hex sha based on the closest
+            :class:`~git.refs.reference.Reference`.
+
+        :note:
+            Mostly useful for UI purposes.
+        """
+        return self.repo.git.name_rev(self)
+
+    @classmethod
+    def iter_items(
+        cls,
+        repo: "Repo",
+        rev: Union[str, "Commit", "SymbolicReference"],
+        paths: Union[PathLike, Sequence[PathLike]] = "",
+        **kwargs: Any,
+    ) -> Iterator["Commit"]:
+        R"""Find all commits matching the given criteria.
+
+        :param repo:
+            The :class:`~git.repo.base.Repo`.
+
+        :param rev:
+            Revision specifier. See :manpage:`git-rev-parse(1)` for viable options.
+
+        :param paths:
+            An optional path or list of paths. If set only :class:`Commit`\s that
+            include the path or paths will be considered.
+
+        :param kwargs:
+            Optional keyword arguments to :manpage:`git-rev-list(1)` where:
+
+            * ``max_count`` is the maximum number of commits to fetch.
+            * ``skip`` is the number of commits to skip.
+            * ``since`` selects all commits since some date, e.g. ``"1970-01-01"``.
+
+        :return:
+            Iterator yielding :class:`Commit` items.
+        """
+        if "pretty" in kwargs:
+            raise ValueError("--pretty cannot be used as parsing expects single sha's only")
+        # END handle pretty
+
+        # Use -- in all cases, to prevent possibility of ambiguous arguments.
+        # See https://github.com/gitpython-developers/GitPython/issues/264.
+
+        args_list: List[PathLike] = ["--"]
+
+        if paths:
+            paths_tup: Tuple[PathLike, ...]
+            if isinstance(paths, (str, os.PathLike)):
+                paths_tup = (paths,)
+            else:
+                paths_tup = tuple(paths)
+
+            args_list.extend(paths_tup)
+        # END if paths
+
+        proc = repo.git.rev_list(rev, args_list, as_process=True, **kwargs)
+        return cls._iter_from_process_or_stream(repo, proc)
+
+    def iter_parents(self, paths: Union[PathLike, Sequence[PathLike]] = "", **kwargs: Any) -> Iterator["Commit"]:
+        R"""Iterate *all* parents of this commit.
+
+        :param paths:
+            Optional path or list of paths limiting the :class:`Commit`\s to those that
+            contain at least one of the paths.
+
+        :param kwargs:
+            All arguments allowed by :manpage:`git-rev-list(1)`.
+
+        :return:
+            Iterator yielding :class:`Commit` objects which are parents of ``self``
+        """
+        # skip ourselves
+        skip = kwargs.get("skip", 1)
+        if skip == 0:  # skip ourselves
+            skip = 1
+        kwargs["skip"] = skip
+
+        return self.iter_items(self.repo, self, paths, **kwargs)
+
+    @property
+    def stats(self) -> Stats:
+        """Create a git stat from changes between this commit and its first parent
+        or from all changes done if this is the very first commit.
+
+        :return:
+            :class:`Stats`
+        """
+
+        def process_lines(lines: List[str]) -> str:
+            text = ""
+            for file_info, line in zip(lines, lines[len(lines) // 2 :]):
+                change_type = file_info.split("\t")[0][-1]
+                (insertions, deletions, filename) = line.split("\t")
+                text += "%s\t%s\t%s\t%s\n" % (change_type, insertions, deletions, filename)
+            return text
+
+        if not self.parents:
+            lines = self.repo.git.diff_tree(
+                self.hexsha, "--", numstat=True, no_renames=True, root=True, raw=True
+            ).splitlines()[1:]
+            text = process_lines(lines)
+        else:
+            lines = self.repo.git.diff(
+                self.parents[0].hexsha, self.hexsha, "--", numstat=True, no_renames=True, raw=True
+            ).splitlines()
+            text = process_lines(lines)
+        return Stats._list_from_string(self.repo, text)
+
+    @property
+    def trailers(self) -> Dict[str, str]:
+        """Deprecated. Get the trailers of the message as a dictionary.
+
+        :note:
+            This property is deprecated, please use either :attr:`trailers_list` or
+            :attr:`trailers_dict`.
+
+        :return:
+            Dictionary containing whitespace stripped trailer information.
+            Only contains the latest instance of each trailer key.
+        """
+        warnings.warn(
+            "Commit.trailers is deprecated, use Commit.trailers_list or Commit.trailers_dict instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return {k: v[0] for k, v in self.trailers_dict.items()}
+
+    @property
+    def trailers_list(self) -> List[Tuple[str, str]]:
+        """Get the trailers of the message as a list.
+
+        Git messages can contain trailer information that are similar to :rfc:`822`
+        e-mail headers. See :manpage:`git-interpret-trailers(1)`.
+
+        This function calls ``git interpret-trailers --parse`` onto the message to
+        extract the trailer information, returns the raw trailer data as a list.
+
+        Valid message with trailer::
+
+            Subject line
+
+            some body information
+
+            another information
+
+            key1: value1.1
+            key1: value1.2
+            key2 :    value 2 with inner spaces
+
+        Returned list will look like this::
+
+            [
+                ("key1", "value1.1"),
+                ("key1", "value1.2"),
+                ("key2", "value 2 with inner spaces"),
+            ]
+
+        :return:
+            List containing key-value tuples of whitespace stripped trailer information.
+        """
+        cmd = ["git", "interpret-trailers", "--parse"]
+        proc: Git.AutoInterrupt = self.repo.git.execute(  # type: ignore[call-overload]
+            cmd,
+            as_process=True,
+            istream=PIPE,
+        )
+        trailer: str = proc.communicate(str(self.message).encode())[0].decode("utf8")
+        trailer = trailer.strip()
+
+        if not trailer:
+            return []
+
+        trailer_list = []
+        for t in trailer.split("\n"):
+            key, val = t.split(":", 1)
+            trailer_list.append((key.strip(), val.strip()))
+
+        return trailer_list
+
+    @property
+    def trailers_dict(self) -> Dict[str, List[str]]:
+        """Get the trailers of the message as a dictionary.
+
+        Git messages can contain trailer information that are similar to :rfc:`822`
+        e-mail headers. See :manpage:`git-interpret-trailers(1)`.
+
+        This function calls ``git interpret-trailers --parse`` onto the message to
+        extract the trailer information. The key value pairs are stripped of leading and
+        trailing whitespaces before they get saved into a dictionary.
+
+        Valid message with trailer::
+
+            Subject line
+
+            some body information
+
+            another information
+
+            key1: value1.1
+            key1: value1.2
+            key2 :    value 2 with inner spaces
+
+        Returned dictionary will look like this::
+
+            {
+                "key1": ["value1.1", "value1.2"],
+                "key2": ["value 2 with inner spaces"],
+            }
+
+
+        :return:
+            Dictionary containing whitespace stripped trailer information, mapping
+            trailer keys to a list of their corresponding values.
+        """
+        d = defaultdict(list)
+        for key, val in self.trailers_list:
+            d[key].append(val)
+        return dict(d)
+
+    @classmethod
+    def _iter_from_process_or_stream(cls, repo: "Repo", proc_or_stream: Union[Popen, IO]) -> Iterator["Commit"]:
+        """Parse out commit information into a list of :class:`Commit` objects.
+
+        We expect one line per commit, and parse the actual commit information directly
+        from our lighting fast object database.
+
+        :param proc:
+            :manpage:`git-rev-list(1)` process instance - one sha per line.
+
+        :return:
+            Iterator supplying :class:`Commit` objects
+        """
+
+        # def is_proc(inp) -> TypeGuard[Popen]:
+        #     return hasattr(proc_or_stream, 'wait') and not hasattr(proc_or_stream, 'readline')
+
+        # def is_stream(inp) -> TypeGuard[IO]:
+        #     return hasattr(proc_or_stream, 'readline')
+
+        if hasattr(proc_or_stream, "wait"):
+            proc_or_stream = cast(Popen, proc_or_stream)
+            if proc_or_stream.stdout is not None:
+                stream = proc_or_stream.stdout
+        elif hasattr(proc_or_stream, "readline"):
+            proc_or_stream = cast(IO, proc_or_stream)  # type: ignore[redundant-cast]
+            stream = proc_or_stream
+
+        readline = stream.readline
+        while True:
+            line = readline()
+            if not line:
+                break
+            hexsha = line.strip()
+            if len(hexsha) > 40:
+                # Split additional information, as returned by bisect for instance.
+                hexsha, _ = line.split(None, 1)
+            # END handle extra info
+
+            assert len(hexsha) == 40, "Invalid line: %s" % hexsha
+            yield cls(repo, hex_to_bin(hexsha))
+        # END for each line in stream
+
+        # TODO: Review this - it seems process handling got a bit out of control due to
+        # many developers trying to fix the open file handles issue.
+        if hasattr(proc_or_stream, "wait"):
+            proc_or_stream = cast(Popen, proc_or_stream)
+            finalize_process(proc_or_stream)
+
+    @classmethod
+    def create_from_tree(
+        cls,
+        repo: "Repo",
+        tree: Union[Tree, str],
+        message: str,
+        parent_commits: Union[None, List["Commit"]] = None,
+        head: bool = False,
+        author: Union[None, Actor] = None,
+        committer: Union[None, Actor] = None,
+        author_date: Union[None, str, datetime.datetime] = None,
+        commit_date: Union[None, str, datetime.datetime] = None,
+    ) -> "Commit":
+        """Commit the given tree, creating a :class:`Commit` object.
+
+        :param repo:
+            :class:`~git.repo.base.Repo` object the commit should be part of.
+
+        :param tree:
+            :class:`~git.objects.tree.Tree` object or hex or bin sha.
+            The tree of the new commit.
+
+        :param message:
+            Commit message. It may be an empty string if no message is provided. It will
+            be converted to a string, in any case.
+
+        :param parent_commits:
+            Optional :class:`Commit` objects to use as parents for the new commit. If
+            empty list, the commit will have no parents at all and become a root commit.
+            If ``None``, the current head commit will be the parent of the new commit
+            object.
+
+        :param head:
+            If ``True``, the HEAD will be advanced to the new commit automatically.
+            Otherwise the HEAD will remain pointing on the previous commit. This could
+            lead to undesired results when diffing files.
+
+        :param author:
+            The name of the author, optional.
+            If unset, the repository configuration is used to obtain this value.
+
+        :param committer:
+            The name of the committer, optional.
+            If unset, the repository configuration is used to obtain this value.
+
+        :param author_date:
+            The timestamp for the author field.
+
+        :param commit_date:
+            The timestamp for the committer field.
+
+        :return:
+            :class:`Commit` object representing the new commit.
+
+        :note:
+            Additional information about the committer and author are taken from the
+            environment or from the git configuration. See :manpage:`git-commit-tree(1)`
+            for more information.
+        """
+        if parent_commits is None:
+            try:
+                parent_commits = [repo.head.commit]
+            except ValueError:
+                # Empty repositories have no head commit.
+                parent_commits = []
+            # END handle parent commits
+        else:
+            for p in parent_commits:
+                if not isinstance(p, cls):
+                    raise ValueError(f"Parent commit '{p!r}' must be of type {cls}")
+            # END check parent commit types
+        # END if parent commits are unset
+
+        # Retrieve all additional information, create a commit object, and serialize it.
+        # Generally:
+        # * Environment variables override configuration values.
+        # * Sensible defaults are set according to the git documentation.
+
+        # COMMITTER AND AUTHOR INFO
+        cr = repo.config_reader()
+        env = os.environ
+
+        committer = committer or Actor.committer(cr)
+        author = author or Actor.author(cr)
+
+        # PARSE THE DATES
+        unix_time = int(time())
+        is_dst = daylight and localtime().tm_isdst > 0
+        offset = altzone if is_dst else timezone
+
+        author_date_str = env.get(cls.env_author_date, "")
+        if author_date:
+            author_time, author_offset = parse_date(author_date)
+        elif author_date_str:
+            author_time, author_offset = parse_date(author_date_str)
+        else:
+            author_time, author_offset = unix_time, offset
+        # END set author time
+
+        committer_date_str = env.get(cls.env_committer_date, "")
+        if commit_date:
+            committer_time, committer_offset = parse_date(commit_date)
+        elif committer_date_str:
+            committer_time, committer_offset = parse_date(committer_date_str)
+        else:
+            committer_time, committer_offset = unix_time, offset
+        # END set committer time
+
+        # Assume UTF-8 encoding.
+        enc_section, enc_option = cls.conf_encoding.split(".")
+        conf_encoding = cr.get_value(enc_section, enc_option, cls.default_encoding)
+        if not isinstance(conf_encoding, str):
+            raise TypeError("conf_encoding could not be coerced to str")
+
+        # If the tree is no object, make sure we create one - otherwise the created
+        # commit object is invalid.
+        if isinstance(tree, str):
+            tree = repo.tree(tree)
+        # END tree conversion
+
+        # CREATE NEW COMMIT
+        new_commit = cls(
+            repo,
+            cls.NULL_BIN_SHA,
+            tree,
+            author,
+            author_time,
+            author_offset,
+            committer,
+            committer_time,
+            committer_offset,
+            message,
+            parent_commits,
+            conf_encoding,
+        )
+
+        new_commit.binsha = cls._calculate_sha_(repo, new_commit)
+
+        if head:
+            # Need late import here, importing git at the very beginning throws as
+            # well...
+            import git.refs
+
+            try:
+                repo.head.set_commit(new_commit, logmsg=message)
+            except ValueError:
+                # head is not yet set to the ref our HEAD points to.
+                # Happens on first commit.
+                master = git.refs.Head.create(
+                    repo,
+                    repo.head.ref,
+                    new_commit,
+                    logmsg="commit (initial): %s" % message,
+                )
+                repo.head.set_reference(master, logmsg="commit: Switching to %s" % master)
+            # END handle empty repositories
+        # END advance head handling
+
+        return new_commit
+
+    # { Serializable Implementation
+
+    def _serialize(self, stream: BytesIO) -> "Commit":
+        write = stream.write
+        write(("tree %s\n" % self.tree).encode("ascii"))
+        for p in self.parents:
+            write(("parent %s\n" % p).encode("ascii"))
+
+        a = self.author
+        aname = a.name
+        c = self.committer
+        fmt = "%s %s <%s> %s %s\n"
+        write(
+            (
+                fmt
+                % (
+                    "author",
+                    aname,
+                    a.email,
+                    self.authored_date,
+                    altz_to_utctz_str(self.author_tz_offset),
+                )
+            ).encode(self.encoding)
+        )
+
+        # Encode committer.
+        aname = c.name
+        write(
+            (
+                fmt
+                % (
+                    "committer",
+                    aname,
+                    c.email,
+                    self.committed_date,
+                    altz_to_utctz_str(self.committer_tz_offset),
+                )
+            ).encode(self.encoding)
+        )
+
+        if self.encoding != self.default_encoding:
+            write(("encoding %s\n" % self.encoding).encode("ascii"))
+
+        try:
+            if self.__getattribute__("gpgsig"):
+                write(b"gpgsig")
+                for sigline in self.gpgsig.rstrip("\n").split("\n"):
+                    write((" " + sigline + "\n").encode("ascii"))
+        except AttributeError:
+            pass
+
+        write(b"\n")
+
+        # Write plain bytes, be sure its encoded according to our encoding.
+        if isinstance(self.message, str):
+            write(self.message.encode(self.encoding))
+        else:
+            write(self.message)
+        # END handle encoding
+        return self
+
+    def _deserialize(self, stream: BytesIO) -> "Commit":
+        readline = stream.readline
+        self.tree = Tree(self.repo, hex_to_bin(readline().split()[1]), Tree.tree_id << 12, "")
+
+        self.parents = []
+        next_line = None
+        while True:
+            parent_line = readline()
+            if not parent_line.startswith(b"parent"):
+                next_line = parent_line
+                break
+            # END abort reading parents
+            self.parents.append(type(self)(self.repo, hex_to_bin(parent_line.split()[-1].decode("ascii"))))
+        # END for each parent line
+        self.parents = tuple(self.parents)
+
+        # We don't know actual author encoding before we have parsed it, so keep the
+        # lines around.
+        author_line = next_line
+        committer_line = readline()
+
+        # We might run into one or more mergetag blocks, skip those for now.
+        next_line = readline()
+        while next_line.startswith(b"mergetag "):
+            next_line = readline()
+            while next_line.startswith(b" "):
+                next_line = readline()
+        # END skip mergetags
+
+        # Now we can have the encoding line, or an empty line followed by the optional
+        # message.
+        self.encoding = self.default_encoding
+        self.gpgsig = ""
+
+        # Read headers.
+        enc = next_line
+        buf = enc.strip()
+        while buf:
+            if buf[0:10] == b"encoding ":
+                self.encoding = buf[buf.find(b" ") + 1 :].decode(self.encoding, "ignore")
+            elif buf[0:7] == b"gpgsig ":
+                sig = buf[buf.find(b" ") + 1 :] + b"\n"
+                is_next_header = False
+                while True:
+                    sigbuf = readline()
+                    if not sigbuf:
+                        break
+                    if sigbuf[0:1] != b" ":
+                        buf = sigbuf.strip()
+                        is_next_header = True
+                        break
+                    sig += sigbuf[1:]
+                # END read all signature
+                self.gpgsig = sig.rstrip(b"\n").decode(self.encoding, "ignore")
+                if is_next_header:
+                    continue
+            buf = readline().strip()
+
+        # Decode the author's name.
+        try:
+            (
+                self.author,
+                self.authored_date,
+                self.author_tz_offset,
+            ) = parse_actor_and_date(author_line.decode(self.encoding, "replace"))
+        except UnicodeDecodeError:
+            _logger.error(
+                "Failed to decode author line '%s' using encoding %s",
+                author_line,
+                self.encoding,
+                exc_info=True,
+            )
+
+        try:
+            (
+                self.committer,
+                self.committed_date,
+                self.committer_tz_offset,
+            ) = parse_actor_and_date(committer_line.decode(self.encoding, "replace"))
+        except UnicodeDecodeError:
+            _logger.error(
+                "Failed to decode committer line '%s' using encoding %s",
+                committer_line,
+                self.encoding,
+                exc_info=True,
+            )
+        # END handle author's encoding
+
+        # A stream from our data simply gives us the plain message.
+        # The end of our message stream is marked with a newline that we strip.
+        self.message = stream.read()
+        try:
+            self.message = self.message.decode(self.encoding, "replace")
+        except UnicodeDecodeError:
+            _logger.error(
+                "Failed to decode message '%s' using encoding %s",
+                self.message,
+                self.encoding,
+                exc_info=True,
+            )
+        # END exception handling
+
+        return self
+
+    # } END serializable implementation
+
+    @property
+    def co_authors(self) -> List[Actor]:
+        """Search the commit message for any co-authors of this commit.
+
+        Details on co-authors:
+        https://github.blog/2018-01-29-commit-together-with-co-authors/
+
+        :return:
+            List of co-authors for this commit (as :class:`~git.util.Actor` objects).
+        """
+        co_authors = []
+
+        if self.message:
+            results = re.findall(
+                r"^Co-authored-by: (.*) <(.*?)>$",
+                self.message,
+                re.MULTILINE,
+            )
+            for author in results:
+                co_authors.append(Actor(*author))
+
+        return co_authors

.venv/lib/python3.11/site-packages/git/objects/fun.py

@@ -0,0 +1,281 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Functions that are supposed to be as fast as possible."""
+
+__all__ = [
+    "tree_to_stream",
+    "tree_entries_from_data",
+    "traverse_trees_recursive",
+    "traverse_tree_recursive",
+]
+
+from stat import S_ISDIR
+
+from git.compat import safe_decode, defenc
+
+# typing ----------------------------------------------
+
+from typing import (
+    Callable,
+    List,
+    MutableSequence,
+    Sequence,
+    Tuple,
+    TYPE_CHECKING,
+    Union,
+    overload,
+)
+
+if TYPE_CHECKING:
+    from _typeshed import ReadableBuffer
+
+    from git import GitCmdObjectDB
+
+EntryTup = Tuple[bytes, int, str]  # Same as TreeCacheTup in tree.py.
+EntryTupOrNone = Union[EntryTup, None]
+
+# ---------------------------------------------------
+
+
+def tree_to_stream(entries: Sequence[EntryTup], write: Callable[["ReadableBuffer"], Union[int, None]]) -> None:
+    """Write the given list of entries into a stream using its ``write`` method.
+
+    :param entries:
+        **Sorted** list of tuples with (binsha, mode, name).
+
+    :param write:
+        A ``write`` method which takes a data string.
+    """
+    ord_zero = ord("0")
+    bit_mask = 7  # 3 bits set.
+
+    for binsha, mode, name in entries:
+        mode_str = b""
+        for i in range(6):
+            mode_str = bytes([((mode >> (i * 3)) & bit_mask) + ord_zero]) + mode_str
+        # END for each 8 octal value
+
+        # git slices away the first octal if it's zero.
+        if mode_str[0] == ord_zero:
+            mode_str = mode_str[1:]
+        # END save a byte
+
+        # Here it comes: If the name is actually unicode, the replacement below will not
+        # work as the binsha is not part of the ascii unicode encoding - hence we must
+        # convert to an UTF-8 string for it to work properly. According to my tests,
+        # this is exactly what git does, that is it just takes the input literally,
+        # which appears to be UTF-8 on linux.
+        if isinstance(name, str):
+            name_bytes = name.encode(defenc)
+        else:
+            name_bytes = name  # type: ignore[unreachable]  # check runtime types - is always str?
+        write(b"".join((mode_str, b" ", name_bytes, b"\0", binsha)))
+    # END for each item
+
+
+def tree_entries_from_data(data: bytes) -> List[EntryTup]:
+    """Read the binary representation of a tree and returns tuples of
+    :class:`~git.objects.tree.Tree` items.
+
+    :param data:
+        Data block with tree data (as bytes).
+
+    :return:
+        list(tuple(binsha, mode, tree_relative_path), ...)
+    """
+    ord_zero = ord("0")
+    space_ord = ord(" ")
+    len_data = len(data)
+    i = 0
+    out = []
+    while i < len_data:
+        mode = 0
+
+        # Read Mode
+        # Some git versions truncate the leading 0, some don't.
+        # The type will be extracted from the mode later.
+        while data[i] != space_ord:
+            # Move existing mode integer up one level being 3 bits and add the actual
+            # ordinal value of the character.
+            mode = (mode << 3) + (data[i] - ord_zero)
+            i += 1
+        # END while reading mode
+
+        # Byte is space now, skip it.
+        i += 1
+
+        # Parse name, it is NULL separated.
+
+        ns = i
+        while data[i] != 0:
+            i += 1
+        # END while not reached NULL
+
+        # Default encoding for strings in git is UTF-8.
+        # Only use the respective unicode object if the byte stream was encoded.
+        name_bytes = data[ns:i]
+        name = safe_decode(name_bytes)
+
+        # Byte is NULL, get next 20.
+        i += 1
+        sha = data[i : i + 20]
+        i = i + 20
+        out.append((sha, mode, name))
+    # END for each byte in data stream
+    return out
+
+
+def _find_by_name(tree_data: MutableSequence[EntryTupOrNone], name: str, is_dir: bool, start_at: int) -> EntryTupOrNone:
+    """Return data entry matching the given name and tree mode or ``None``.
+
+    Before the item is returned, the respective data item is set None in the `tree_data`
+    list to mark it done.
+    """
+
+    try:
+        item = tree_data[start_at]
+        if item and item[2] == name and S_ISDIR(item[1]) == is_dir:
+            tree_data[start_at] = None
+            return item
+    except IndexError:
+        pass
+    # END exception handling
+    for index, item in enumerate(tree_data):
+        if item and item[2] == name and S_ISDIR(item[1]) == is_dir:
+            tree_data[index] = None
+            return item
+        # END if item matches
+    # END for each item
+    return None
+
+
+@overload
+def _to_full_path(item: None, path_prefix: str) -> None: ...
+
+
+@overload
+def _to_full_path(item: EntryTup, path_prefix: str) -> EntryTup: ...
+
+
+def _to_full_path(item: EntryTupOrNone, path_prefix: str) -> EntryTupOrNone:
+    """Rebuild entry with given path prefix."""
+    if not item:
+        return item
+    return (item[0], item[1], path_prefix + item[2])
+
+
+def traverse_trees_recursive(
+    odb: "GitCmdObjectDB", tree_shas: Sequence[Union[bytes, None]], path_prefix: str
+) -> List[Tuple[EntryTupOrNone, ...]]:
+    """
+    :return:
+        List of list with entries according to the given binary tree-shas.
+
+        The result is encoded in a list
+        of n tuple|None per blob/commit, (n == len(tree_shas)), where:
+
+        * [0] == 20 byte sha
+        * [1] == mode as int
+        * [2] == path relative to working tree root
+
+        The entry tuple is ``None`` if the respective blob/commit did not exist in the
+        given tree.
+
+    :param tree_shas:
+        Iterable of shas pointing to trees. All trees must be on the same level.
+        A tree-sha may be ``None``, in which case ``None``.
+
+    :param path_prefix:
+        A prefix to be added to the returned paths on this level.
+        Set it ``""`` for the first iteration.
+
+    :note:
+        The ordering of the returned items will be partially lost.
+    """
+    trees_data: List[List[EntryTupOrNone]] = []
+
+    nt = len(tree_shas)
+    for tree_sha in tree_shas:
+        if tree_sha is None:
+            data: List[EntryTupOrNone] = []
+        else:
+            # Make new list for typing as list invariant.
+            data = list(tree_entries_from_data(odb.stream(tree_sha).read()))
+        # END handle muted trees
+        trees_data.append(data)
+    # END for each sha to get data for
+
+    out: List[Tuple[EntryTupOrNone, ...]] = []
+
+    # Find all matching entries and recursively process them together if the match is a
+    # tree. If the match is a non-tree item, put it into the result.
+    # Processed items will be set None.
+    for ti, tree_data in enumerate(trees_data):
+        for ii, item in enumerate(tree_data):
+            if not item:
+                continue
+            # END skip already done items
+            entries: List[EntryTupOrNone]
+            entries = [None for _ in range(nt)]
+            entries[ti] = item
+            _sha, mode, name = item
+            is_dir = S_ISDIR(mode)  # Type mode bits
+
+            # Find this item in all other tree data items.
+            # Wrap around, but stop one before our current index, hence ti+nt, not
+            # ti+1+nt.
+            for tio in range(ti + 1, ti + nt):
+                tio = tio % nt
+                entries[tio] = _find_by_name(trees_data[tio], name, is_dir, ii)
+
+            # END for each other item data
+            # If we are a directory, enter recursion.
+            if is_dir:
+                out.extend(
+                    traverse_trees_recursive(
+                        odb,
+                        [((ei and ei[0]) or None) for ei in entries],
+                        path_prefix + name + "/",
+                    )
+                )
+            else:
+                out.append(tuple(_to_full_path(e, path_prefix) for e in entries))
+
+            # END handle recursion
+            # Finally mark it done.
+            tree_data[ii] = None
+        # END for each item
+
+        # We are done with one tree, set all its data empty.
+        del tree_data[:]
+    # END for each tree_data chunk
+    return out
+
+
+def traverse_tree_recursive(odb: "GitCmdObjectDB", tree_sha: bytes, path_prefix: str) -> List[EntryTup]:
+    """
+    :return:
+        List of entries of the tree pointed to by the binary `tree_sha`.
+
+        An entry has the following format:
+
+        * [0] 20 byte sha
+        * [1] mode as int
+        * [2] path relative to the repository
+
+    :param path_prefix:
+        Prefix to prepend to the front of all returned paths.
+    """
+    entries = []
+    data = tree_entries_from_data(odb.stream(tree_sha).read())
+
+    # Unpacking/packing is faster than accessing individual items.
+    for sha, mode, name in data:
+        if S_ISDIR(mode):
+            entries.extend(traverse_tree_recursive(odb, sha, path_prefix + name + "/"))
+        else:
+            entries.append((sha, mode, path_prefix + name))
+    # END for each item
+
+    return entries

.venv/lib/python3.11/site-packages/git/objects/submodule/__init__.py

@@ -0,0 +1,7 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+__all__ = ["Submodule", "UpdateProgress", "RootModule", "RootUpdateProgress"]
+
+from .base import Submodule, UpdateProgress
+from .root import RootModule, RootUpdateProgress

.venv/lib/python3.11/site-packages/git/objects/submodule/base.py

@@ -0,0 +1,1642 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+__all__ = ["Submodule", "UpdateProgress"]
+
+import gc
+from io import BytesIO
+import logging
+import os
+import os.path as osp
+import stat
+import sys
+import uuid
+import urllib
+
+import git
+from git.cmd import Git
+from git.compat import defenc
+from git.config import GitConfigParser, SectionConstraint, cp
+from git.exc import (
+    BadName,
+    InvalidGitRepositoryError,
+    NoSuchPathError,
+    RepositoryDirtyError,
+)
+from git.objects.base import IndexObject, Object
+from git.objects.util import TraversableIterableObj
+from git.util import (
+    IterableList,
+    RemoteProgress,
+    join_path_native,
+    rmtree,
+    to_native_path_linux,
+    unbare_repo,
+)
+
+from .util import (
+    SubmoduleConfigParser,
+    find_first_remote_branch,
+    mkhead,
+    sm_name,
+    sm_section,
+)
+
+# typing ----------------------------------------------------------------------
+
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterator,
+    Mapping,
+    Sequence,
+    TYPE_CHECKING,
+    Union,
+    cast,
+)
+
+if sys.version_info >= (3, 8):
+    from typing import Literal
+else:
+    from typing_extensions import Literal
+
+from git.types import Commit_ish, PathLike, TBD
+
+if TYPE_CHECKING:
+    from git.index import IndexFile
+    from git.objects.commit import Commit
+    from git.refs import Head
+    from git.repo import Repo
+
+# -----------------------------------------------------------------------------
+
+_logger = logging.getLogger(__name__)
+
+
+class UpdateProgress(RemoteProgress):
+    """Class providing detailed progress information to the caller who should
+    derive from it and implement the
+    :meth:`update(...) <git.util.RemoteProgress.update>` message."""
+
+    CLONE, FETCH, UPDWKTREE = [1 << x for x in range(RemoteProgress._num_op_codes, RemoteProgress._num_op_codes + 3)]
+    _num_op_codes: int = RemoteProgress._num_op_codes + 3
+
+    __slots__ = ()
+
+
+BEGIN = UpdateProgress.BEGIN
+END = UpdateProgress.END
+CLONE = UpdateProgress.CLONE
+FETCH = UpdateProgress.FETCH
+UPDWKTREE = UpdateProgress.UPDWKTREE
+
+
+# IndexObject comes via the util module. It's a 'hacky' fix thanks to Python's import
+# mechanism, which causes plenty of trouble if the only reason for packages and modules
+# is refactoring - subpackages shouldn't depend on parent packages.
+class Submodule(IndexObject, TraversableIterableObj):
+    """Implements access to a git submodule. They are special in that their sha
+    represents a commit in the submodule's repository which is to be checked out
+    at the path of this instance.
+
+    The submodule type does not have a string type associated with it, as it exists
+    solely as a marker in the tree and index.
+
+    All methods work in bare and non-bare repositories.
+    """
+
+    _id_attribute_ = "name"
+    k_modules_file = ".gitmodules"
+    k_head_option = "branch"
+    k_head_default = "master"
+    k_default_mode = stat.S_IFDIR | stat.S_IFLNK
+    """Submodule flags. Submodules are directories with link-status."""
+
+    type: Literal["submodule"] = "submodule"  # type: ignore[assignment]
+    """This is a bogus type string for base class compatibility."""
+
+    __slots__ = ("_parent_commit", "_url", "_branch_path", "_name", "__weakref__")
+
+    _cache_attrs = ("path", "_url", "_branch_path")
+
+    def __init__(
+        self,
+        repo: "Repo",
+        binsha: bytes,
+        mode: Union[int, None] = None,
+        path: Union[PathLike, None] = None,
+        name: Union[str, None] = None,
+        parent_commit: Union["Commit", None] = None,
+        url: Union[str, None] = None,
+        branch_path: Union[PathLike, None] = None,
+    ) -> None:
+        """Initialize this instance with its attributes.
+
+        We only document the parameters that differ from
+        :class:`~git.objects.base.IndexObject`.
+
+        :param repo:
+            Our parent repository.
+
+        :param binsha:
+            Binary sha referring to a commit in the remote repository.
+            See the `url` parameter.
+
+        :param parent_commit:
+            The :class:`~git.objects.commit.Commit` whose tree is supposed to contain
+            the ``.gitmodules`` blob, or ``None`` to always point to the most recent
+            commit. See :meth:`set_parent_commit` for details.
+
+        :param url:
+            The URL to the remote repository which is the submodule.
+
+        :param branch_path:
+            Full repository-relative path to ref to checkout when cloning the remote
+            repository.
+        """
+        super().__init__(repo, binsha, mode, path)
+        self.size = 0
+        self._parent_commit = parent_commit
+        if url is not None:
+            self._url = url
+        if branch_path is not None:
+            self._branch_path = branch_path
+        if name is not None:
+            self._name = name
+
+    def _set_cache_(self, attr: str) -> None:
+        if attr in ("path", "_url", "_branch_path"):
+            reader: SectionConstraint = self.config_reader()
+            # Default submodule values.
+            try:
+                self.path = reader.get("path")
+            except cp.NoSectionError as e:
+                if self.repo.working_tree_dir is not None:
+                    raise ValueError(
+                        "This submodule instance does not exist anymore in '%s' file"
+                        % osp.join(self.repo.working_tree_dir, ".gitmodules")
+                    ) from e
+
+            self._url = reader.get("url")
+            # GitPython extension values - optional.
+            self._branch_path = reader.get_value(self.k_head_option, git.Head.to_full_path(self.k_head_default))
+        elif attr == "_name":
+            raise AttributeError("Cannot retrieve the name of a submodule if it was not set initially")
+        else:
+            super()._set_cache_(attr)
+        # END handle attribute name
+
+    @classmethod
+    def _get_intermediate_items(cls, item: "Submodule") -> IterableList["Submodule"]:
+        """:return: All the submodules of our module repository"""
+        try:
+            return cls.list_items(item.module())
+        except InvalidGitRepositoryError:
+            return IterableList("")
+        # END handle intermediate items
+
+    @classmethod
+    def _need_gitfile_submodules(cls, git: Git) -> bool:
+        return git.version_info[:3] >= (1, 7, 5)
+
+    def __eq__(self, other: Any) -> bool:
+        """Compare with another submodule."""
+        # We may only compare by name as this should be the ID they are hashed with.
+        # Otherwise this type wouldn't be hashable.
+        # return self.path == other.path and self.url == other.url and super().__eq__(other)
+        return self._name == other._name
+
+    def __ne__(self, other: object) -> bool:
+        """Compare with another submodule for inequality."""
+        return not (self == other)
+
+    def __hash__(self) -> int:
+        """Hash this instance using its logical id, not the sha."""
+        return hash(self._name)
+
+    def __str__(self) -> str:
+        return self._name
+
+    def __repr__(self) -> str:
+        return "git.%s(name=%s, path=%s, url=%s, branch_path=%s)" % (
+            type(self).__name__,
+            self._name,
+            self.path,
+            self.url,
+            self.branch_path,
+        )
+
+    @classmethod
+    def _config_parser(
+        cls, repo: "Repo", parent_commit: Union["Commit", None], read_only: bool
+    ) -> SubmoduleConfigParser:
+        """
+        :return:
+            Config parser constrained to our submodule in read or write mode
+
+        :raise IOError:
+            If the ``.gitmodules`` file cannot be found, either locally or in the
+            repository at the given parent commit. Otherwise the exception would be
+            delayed until the first access of the config parser.
+        """
+        parent_matches_head = True
+        if parent_commit is not None:
+            try:
+                parent_matches_head = repo.head.commit == parent_commit
+            except ValueError:
+                # We are most likely in an empty repository, so the HEAD doesn't point
+                # to a valid ref.
+                pass
+        # END handle parent_commit
+        fp_module: Union[str, BytesIO]
+        if not repo.bare and parent_matches_head and repo.working_tree_dir:
+            fp_module = osp.join(repo.working_tree_dir, cls.k_modules_file)
+        else:
+            assert parent_commit is not None, "need valid parent_commit in bare repositories"
+            try:
+                fp_module = cls._sio_modules(parent_commit)
+            except KeyError as e:
+                raise IOError(
+                    "Could not find %s file in the tree of parent commit %s" % (cls.k_modules_file, parent_commit)
+                ) from e
+            # END handle exceptions
+        # END handle non-bare working tree
+
+        if not read_only and (repo.bare or not parent_matches_head):
+            raise ValueError("Cannot write blobs of 'historical' submodule configurations")
+        # END handle writes of historical submodules
+
+        return SubmoduleConfigParser(fp_module, read_only=read_only)
+
+    def _clear_cache(self) -> None:
+        """Clear the possibly changed values."""
+        for name in self._cache_attrs:
+            try:
+                delattr(self, name)
+            except AttributeError:
+                pass
+            # END try attr deletion
+        # END for each name to delete
+
+    @classmethod
+    def _sio_modules(cls, parent_commit: "Commit") -> BytesIO:
+        """
+        :return:
+            Configuration file as :class:`~io.BytesIO` - we only access it through the
+            respective blob's data
+        """
+        sio = BytesIO(parent_commit.tree[cls.k_modules_file].data_stream.read())
+        sio.name = cls.k_modules_file
+        return sio
+
+    def _config_parser_constrained(self, read_only: bool) -> SectionConstraint:
+        """:return: Config parser constrained to our submodule in read or write mode"""
+        try:
+            pc = self.parent_commit
+        except ValueError:
+            pc = None
+        # END handle empty parent repository
+        parser = self._config_parser(self.repo, pc, read_only)
+        parser.set_submodule(self)
+        return SectionConstraint(parser, sm_section(self.name))
+
+    @classmethod
+    def _module_abspath(cls, parent_repo: "Repo", path: PathLike, name: str) -> PathLike:
+        if cls._need_gitfile_submodules(parent_repo.git):
+            return osp.join(parent_repo.git_dir, "modules", name)
+        if parent_repo.working_tree_dir:
+            return osp.join(parent_repo.working_tree_dir, path)
+        raise NotADirectoryError()
+
+    @classmethod
+    def _clone_repo(
+        cls,
+        repo: "Repo",
+        url: str,
+        path: PathLike,
+        name: str,
+        allow_unsafe_options: bool = False,
+        allow_unsafe_protocols: bool = False,
+        **kwargs: Any,
+    ) -> "Repo":
+        """
+        :return:
+            :class:`~git.repo.base.Repo` instance of newly cloned repository.
+
+        :param repo:
+            Our parent repository.
+
+        :param url:
+            URL to clone from.
+
+        :param path:
+            Repository-relative path to the submodule checkout location.
+
+        :param name:
+            Canonical name of the submodule.
+
+        :param allow_unsafe_protocols:
+            Allow unsafe protocols to be used, like ``ext``.
+
+        :param allow_unsafe_options:
+            Allow unsafe options to be used, like ``--upload-pack``.
+
+        :param kwargs:
+            Additional arguments given to :manpage:`git-clone(1)`.
+        """
+        module_abspath = cls._module_abspath(repo, path, name)
+        module_checkout_path = module_abspath
+        if cls._need_gitfile_submodules(repo.git):
+            kwargs["separate_git_dir"] = module_abspath
+            module_abspath_dir = osp.dirname(module_abspath)
+            if not osp.isdir(module_abspath_dir):
+                os.makedirs(module_abspath_dir)
+            module_checkout_path = osp.join(str(repo.working_tree_dir), path)
+
+        if url.startswith("../"):
+            remote_name = repo.active_branch.tracking_branch().remote_name
+            repo_remote_url = repo.remote(remote_name).url
+            url = os.path.join(repo_remote_url, url)
+
+        clone = git.Repo.clone_from(
+            url,
+            module_checkout_path,
+            allow_unsafe_options=allow_unsafe_options,
+            allow_unsafe_protocols=allow_unsafe_protocols,
+            **kwargs,
+        )
+        if cls._need_gitfile_submodules(repo.git):
+            cls._write_git_file_and_module_config(module_checkout_path, module_abspath)
+
+        return clone
+
+    @classmethod
+    def _to_relative_path(cls, parent_repo: "Repo", path: PathLike) -> PathLike:
+        """:return: A path guaranteed to be relative to the given parent repository
+
+        :raise ValueError:
+            If path is not contained in the parent repository's working tree.
+        """
+        path = to_native_path_linux(path)
+        if path.endswith("/"):
+            path = path[:-1]
+        # END handle trailing slash
+
+        if osp.isabs(path) and parent_repo.working_tree_dir:
+            working_tree_linux = to_native_path_linux(parent_repo.working_tree_dir)
+            if not path.startswith(working_tree_linux):
+                raise ValueError(
+                    "Submodule checkout path '%s' needs to be within the parents repository at '%s'"
+                    % (working_tree_linux, path)
+                )
+            path = path[len(working_tree_linux.rstrip("/")) + 1 :]
+            if not path:
+                raise ValueError("Absolute submodule path '%s' didn't yield a valid relative path" % path)
+            # END verify converted relative path makes sense
+        # END convert to a relative path
+
+        return path
+
+    @classmethod
+    def _write_git_file_and_module_config(cls, working_tree_dir: PathLike, module_abspath: PathLike) -> None:
+        """Write a ``.git`` file containing a (preferably) relative path to the actual
+        git module repository.
+
+        It is an error if the `module_abspath` cannot be made into a relative path,
+        relative to the `working_tree_dir`.
+
+        :note:
+            This will overwrite existing files!
+
+        :note:
+            As we rewrite both the git file as well as the module configuration, we
+            might fail on the configuration and will not roll back changes done to the
+            git file. This should be a non-issue, but may easily be fixed if it becomes
+            one.
+
+        :param working_tree_dir:
+            Directory to write the ``.git`` file into.
+
+        :param module_abspath:
+            Absolute path to the bare repository.
+        """
+        git_file = osp.join(working_tree_dir, ".git")
+        rela_path = osp.relpath(module_abspath, start=working_tree_dir)
+        if sys.platform == "win32" and osp.isfile(git_file):
+            os.remove(git_file)
+        with open(git_file, "wb") as fp:
+            fp.write(("gitdir: %s" % rela_path).encode(defenc))
+
+        with GitConfigParser(osp.join(module_abspath, "config"), read_only=False, merge_includes=False) as writer:
+            writer.set_value(
+                "core",
+                "worktree",
+                to_native_path_linux(osp.relpath(working_tree_dir, start=module_abspath)),
+            )
+
+    # { Edit Interface
+
+    @classmethod
+    def add(
+        cls,
+        repo: "Repo",
+        name: str,
+        path: PathLike,
+        url: Union[str, None] = None,
+        branch: Union[str, None] = None,
+        no_checkout: bool = False,
+        depth: Union[int, None] = None,
+        env: Union[Mapping[str, str], None] = None,
+        clone_multi_options: Union[Sequence[TBD], None] = None,
+        allow_unsafe_options: bool = False,
+        allow_unsafe_protocols: bool = False,
+    ) -> "Submodule":
+        """Add a new submodule to the given repository. This will alter the index as
+        well as the ``.gitmodules`` file, but will not create a new commit. If the
+        submodule already exists, no matter if the configuration differs from the one
+        provided, the existing submodule will be returned.
+
+        :param repo:
+            Repository instance which should receive the submodule.
+
+        :param name:
+            The name/identifier for the submodule.
+
+        :param path:
+            Repository-relative or absolute path at which the submodule should be
+            located.
+            It will be created as required during the repository initialization.
+
+        :param url:
+            ``git clone ...``-compatible URL. See :manpage:`git-clone(1)` for more
+            information. If ``None``, the repository is assumed to exist, and the URL of
+            the first remote is taken instead. This is useful if you want to make an
+            existing repository a submodule of another one.
+
+        :param branch:
+            Name of branch at which the submodule should (later) be checked out. The
+            given branch must exist in the remote repository, and will be checked out
+            locally as a tracking branch.
+            It will only be written into the configuration if it not ``None``, which is
+            when the checked out branch will be the one the remote HEAD pointed to.
+            The result you get in these situation is somewhat fuzzy, and it is
+            recommended to specify at least ``master`` here.
+            Examples are ``master`` or ``feature/new``.
+
+        :param no_checkout:
+            If ``True``, and if the repository has to be cloned manually, no checkout
+            will be performed.
+
+        :param depth:
+            Create a shallow clone with a history truncated to the specified number of
+            commits.
+
+        :param env:
+            Optional dictionary containing the desired environment variables.
+
+            Note: Provided variables will be used to update the execution environment
+            for ``git``. If some variable is not specified in `env` and is defined in
+            attr:`os.environ`, the value from attr:`os.environ` will be used. If you
+            want to unset some variable, consider providing an empty string as its
+            value.
+
+        :param clone_multi_options:
+            A list of clone options. Please see
+            :meth:`Repo.clone <git.repo.base.Repo.clone>` for details.
+
+        :param allow_unsafe_protocols:
+            Allow unsafe protocols to be used, like ``ext``.
+
+        :param allow_unsafe_options:
+            Allow unsafe options to be used, like ``--upload-pack``.
+
+        :return:
+            The newly created :class:`Submodule` instance.
+
+        :note:
+            Works atomically, such that no change will be done if, for example, the
+            repository update fails.
+        """
+        if repo.bare:
+            raise InvalidGitRepositoryError("Cannot add submodules to bare repositories")
+        # END handle bare repos
+
+        path = cls._to_relative_path(repo, path)
+
+        # Ensure we never put backslashes into the URL, as might happen on Windows.
+        if url is not None:
+            url = to_native_path_linux(url)
+        # END ensure URL correctness
+
+        # INSTANTIATE INTERMEDIATE SM
+        sm = cls(
+            repo,
+            cls.NULL_BIN_SHA,
+            cls.k_default_mode,
+            path,
+            name,
+            url="invalid-temporary",
+        )
+        if sm.exists():
+            # Reretrieve submodule from tree.
+            try:
+                sm = repo.head.commit.tree[str(path)]
+                sm._name = name
+                return sm
+            except KeyError:
+                # Could only be in index.
+                index = repo.index
+                entry = index.entries[index.entry_key(path, 0)]
+                sm.binsha = entry.binsha
+                return sm
+            # END handle exceptions
+        # END handle existing
+
+        # fake-repo - we only need the functionality on the branch instance.
+        br = git.Head(repo, git.Head.to_full_path(str(branch) or cls.k_head_default))
+        has_module = sm.module_exists()
+        branch_is_default = branch is None
+        if has_module and url is not None:
+            if url not in [r.url for r in sm.module().remotes]:
+                raise ValueError(
+                    "Specified URL '%s' does not match any remote url of the repository at '%s'" % (url, sm.abspath)
+                )
+            # END check url
+        # END verify urls match
+
+        mrepo: Union[Repo, None] = None
+
+        if url is None:
+            if not has_module:
+                raise ValueError("A URL was not given and a repository did not exist at %s" % path)
+            # END check url
+            mrepo = sm.module()
+            # assert isinstance(mrepo, git.Repo)
+            urls = [r.url for r in mrepo.remotes]
+            if not urls:
+                raise ValueError("Didn't find any remote url in repository at %s" % sm.abspath)
+            # END verify we have url
+            url = urls[0]
+        else:
+            # Clone new repo.
+            kwargs: Dict[str, Union[bool, int, str, Sequence[TBD]]] = {"n": no_checkout}
+            if not branch_is_default:
+                kwargs["b"] = br.name
+            # END setup checkout-branch
+
+            if depth:
+                if isinstance(depth, int):
+                    kwargs["depth"] = depth
+                else:
+                    raise ValueError("depth should be an integer")
+            if clone_multi_options:
+                kwargs["multi_options"] = clone_multi_options
+
+            # _clone_repo(cls, repo, url, path, name, **kwargs):
+            mrepo = cls._clone_repo(
+                repo,
+                url,
+                path,
+                name,
+                env=env,
+                allow_unsafe_options=allow_unsafe_options,
+                allow_unsafe_protocols=allow_unsafe_protocols,
+                **kwargs,
+            )
+        # END verify url
+
+        ## See #525 for ensuring git URLs in config-files are valid under Windows.
+        url = Git.polish_url(url)
+
+        # It's important to add the URL to the parent config, to let `git submodule` know.
+        # Otherwise there is a '-' character in front of the submodule listing:
+        #  a38efa84daef914e4de58d1905a500d8d14aaf45 mymodule (v0.9.0-1-ga38efa8)
+        # -a38efa84daef914e4de58d1905a500d8d14aaf45 submodules/intermediate/one
+        writer: Union[GitConfigParser, SectionConstraint]
+
+        with sm.repo.config_writer() as writer:
+            writer.set_value(sm_section(name), "url", url)
+
+        # Update configuration and index.
+        index = sm.repo.index
+        with sm.config_writer(index=index, write=False) as writer:
+            writer.set_value("url", url)
+            writer.set_value("path", path)
+
+            sm._url = url
+            if not branch_is_default:
+                # Store full path.
+                writer.set_value(cls.k_head_option, br.path)
+                sm._branch_path = br.path
+
+        # We deliberately assume that our head matches our index!
+        if mrepo:
+            sm.binsha = mrepo.head.commit.binsha
+        index.add([sm], write=True)
+
+        return sm
+
+    def update(
+        self,
+        recursive: bool = False,
+        init: bool = True,
+        to_latest_revision: bool = False,
+        progress: Union["UpdateProgress", None] = None,
+        dry_run: bool = False,
+        force: bool = False,
+        keep_going: bool = False,
+        env: Union[Mapping[str, str], None] = None,
+        clone_multi_options: Union[Sequence[TBD], None] = None,
+        allow_unsafe_options: bool = False,
+        allow_unsafe_protocols: bool = False,
+    ) -> "Submodule":
+        """Update the repository of this submodule to point to the checkout we point at
+        with the binsha of this instance.
+
+        :param recursive:
+            If ``True``, we will operate recursively and update child modules as well.
+
+        :param init:
+            If ``True``, the module repository will be cloned into place if necessary.
+
+        :param to_latest_revision:
+            If ``True``, the submodule's sha will be ignored during checkout. Instead,
+            the remote will be fetched, and the local tracking branch updated. This only
+            works if we have a local tracking branch, which is the case if the remote
+            repository had a master branch, or if the ``branch`` option was specified
+            for this submodule and the branch existed remotely.
+
+        :param progress:
+            :class:`UpdateProgress` instance, or ``None`` if no progress should be
+            shown.
+
+        :param dry_run:
+            If ``True``, the operation will only be simulated, but not performed.
+            All performed operations are read-only.
+
+        :param force:
+            If ``True``, we may reset heads even if the repository in question is dirty.
+            Additionally we will be allowed to set a tracking branch which is ahead of
+            its remote branch back into the past or the location of the remote branch.
+            This will essentially 'forget' commits.
+
+            If ``False``, local tracking branches that are in the future of their
+            respective remote branches will simply not be moved.
+
+        :param keep_going:
+            If ``True``, we will ignore but log all errors, and keep going recursively.
+            Unless `dry_run` is set as well, `keep_going` could cause
+            subsequent/inherited errors you wouldn't see otherwise.
+            In conjunction with `dry_run`, it can be useful to anticipate all errors
+            when updating submodules.
+
+        :param env:
+            Optional dictionary containing the desired environment variables.
+
+            Note: Provided variables will be used to update the execution environment
+            for ``git``. If some variable is not specified in `env` and is defined in
+            attr:`os.environ`, value from attr:`os.environ` will be used.
+
+            If you want to unset some variable, consider providing the empty string as
+            its value.
+
+        :param clone_multi_options:
+            List of :manpage:`git-clone(1)` options.
+            Please see :meth:`Repo.clone <git.repo.base.Repo.clone>` for details.
+            They only take effect with the `init` option.
+
+        :param allow_unsafe_protocols:
+            Allow unsafe protocols to be used, like ``ext``.
+
+        :param allow_unsafe_options:
+            Allow unsafe options to be used, like ``--upload-pack``.
+
+        :note:
+            Does nothing in bare repositories.
+
+        :note:
+            This method is definitely not atomic if `recursive` is ``True``.
+
+        :return:
+            self
+        """
+        if self.repo.bare:
+            return self
+        # END pass in bare mode
+
+        if progress is None:
+            progress = UpdateProgress()
+        # END handle progress
+        prefix = ""
+        if dry_run:
+            prefix = "DRY-RUN: "
+        # END handle prefix
+
+        # To keep things plausible in dry-run mode.
+        if dry_run:
+            mrepo = None
+        # END init mrepo
+
+        try:
+            # ENSURE REPO IS PRESENT AND UP-TO-DATE
+            #######################################
+            try:
+                mrepo = self.module()
+                rmts = mrepo.remotes
+                len_rmts = len(rmts)
+                for i, remote in enumerate(rmts):
+                    op = FETCH
+                    if i == 0:
+                        op |= BEGIN
+                    # END handle start
+
+                    progress.update(
+                        op,
+                        i,
+                        len_rmts,
+                        prefix + "Fetching remote %s of submodule %r" % (remote, self.name),
+                    )
+                    # ===============================
+                    if not dry_run:
+                        remote.fetch(progress=progress)
+                    # END handle dry-run
+                    # ===============================
+                    if i == len_rmts - 1:
+                        op |= END
+                    # END handle end
+                    progress.update(
+                        op,
+                        i,
+                        len_rmts,
+                        prefix + "Done fetching remote of submodule %r" % self.name,
+                    )
+                # END fetch new data
+            except InvalidGitRepositoryError:
+                mrepo = None
+                if not init:
+                    return self
+                # END early abort if init is not allowed
+
+                # There is no git-repository yet - but delete empty paths.
+                checkout_module_abspath = self.abspath
+                if not dry_run and osp.isdir(checkout_module_abspath):
+                    try:
+                        os.rmdir(checkout_module_abspath)
+                    except OSError as e:
+                        raise OSError(
+                            "Module directory at %r does already exist and is non-empty" % checkout_module_abspath
+                        ) from e
+                    # END handle OSError
+                # END handle directory removal
+
+                # Don't check it out at first - nonetheless it will create a local
+                # branch according to the remote-HEAD if possible.
+                progress.update(
+                    BEGIN | CLONE,
+                    0,
+                    1,
+                    prefix
+                    + "Cloning url '%s' to '%s' in submodule %r" % (self.url, checkout_module_abspath, self.name),
+                )
+                if not dry_run:
+                    if self.url.startswith("."):
+                        url = urllib.parse.urljoin(self.repo.remotes.origin.url + "/", self.url)
+                    else:
+                        url = self.url
+                    mrepo = self._clone_repo(
+                        self.repo,
+                        url,
+                        self.path,
+                        self.name,
+                        n=True,
+                        env=env,
+                        multi_options=clone_multi_options,
+                        allow_unsafe_options=allow_unsafe_options,
+                        allow_unsafe_protocols=allow_unsafe_protocols,
+                    )
+                # END handle dry-run
+                progress.update(
+                    END | CLONE,
+                    0,
+                    1,
+                    prefix + "Done cloning to %s" % checkout_module_abspath,
+                )
+
+                if not dry_run:
+                    # See whether we have a valid branch to check out.
+                    try:
+                        mrepo = cast("Repo", mrepo)
+                        # Find a remote which has our branch - we try to be flexible.
+                        remote_branch = find_first_remote_branch(mrepo.remotes, self.branch_name)
+                        local_branch = mkhead(mrepo, self.branch_path)
+
+                        # Have a valid branch, but no checkout - make sure we can figure
+                        # that out by marking the commit with a null_sha.
+                        local_branch.set_object(Object(mrepo, self.NULL_BIN_SHA))
+                        # END initial checkout + branch creation
+
+                        # Make sure HEAD is not detached.
+                        mrepo.head.set_reference(
+                            local_branch,
+                            logmsg="submodule: attaching head to %s" % local_branch,
+                        )
+                        mrepo.head.reference.set_tracking_branch(remote_branch)
+                    except (IndexError, InvalidGitRepositoryError):
+                        _logger.warning("Failed to checkout tracking branch %s", self.branch_path)
+                    # END handle tracking branch
+
+                    # NOTE: Have to write the repo config file as well, otherwise the
+                    # default implementation will be offended and not update the
+                    # repository. Maybe this is a good way to ensure it doesn't get into
+                    # our way, but we want to stay backwards compatible too... It's so
+                    # redundant!
+                    with self.repo.config_writer() as writer:
+                        writer.set_value(sm_section(self.name), "url", self.url)
+                # END handle dry_run
+            # END handle initialization
+
+            # DETERMINE SHAS TO CHECK OUT
+            #############################
+            binsha = self.binsha
+            hexsha = self.hexsha
+            if mrepo is not None:
+                # mrepo is only set if we are not in dry-run mode or if the module
+                # existed.
+                is_detached = mrepo.head.is_detached
+            # END handle dry_run
+
+            if mrepo is not None and to_latest_revision:
+                msg_base = "Cannot update to latest revision in repository at %r as " % mrepo.working_dir
+                if not is_detached:
+                    rref = mrepo.head.reference.tracking_branch()
+                    if rref is not None:
+                        rcommit = rref.commit
+                        binsha = rcommit.binsha
+                        hexsha = rcommit.hexsha
+                    else:
+                        _logger.error(
+                            "%s a tracking branch was not set for local branch '%s'",
+                            msg_base,
+                            mrepo.head.reference,
+                        )
+                    # END handle remote ref
+                else:
+                    _logger.error("%s there was no local tracking branch", msg_base)
+                # END handle detached head
+            # END handle to_latest_revision option
+
+            # Update the working tree.
+            # Handles dry_run.
+            if mrepo is not None and mrepo.head.commit.binsha != binsha:
+                # We must ensure that our destination sha (the one to point to) is in
+                # the future of our current head. Otherwise, we will reset changes that
+                # might have been done on the submodule, but were not yet pushed. We
+                # also handle the case that history has been rewritten, leaving no
+                # merge-base. In that case we behave conservatively, protecting possible
+                # changes the user had done.
+                may_reset = True
+                if mrepo.head.commit.binsha != self.NULL_BIN_SHA:
+                    base_commit = mrepo.merge_base(mrepo.head.commit, hexsha)
+                    if len(base_commit) == 0 or (base_commit[0] is not None and base_commit[0].hexsha == hexsha):
+                        if force:
+                            msg = "Will force checkout or reset on local branch that is possibly in the future of"
+                            msg += " the commit it will be checked out to, effectively 'forgetting' new commits"
+                            _logger.debug(msg)
+                        else:
+                            msg = "Skipping %s on branch '%s' of submodule repo '%s' as it contains un-pushed commits"
+                            msg %= (
+                                is_detached and "checkout" or "reset",
+                                mrepo.head,
+                                mrepo,
+                            )
+                            _logger.info(msg)
+                            may_reset = False
+                        # END handle force
+                    # END handle if we are in the future
+
+                    if may_reset and not force and mrepo.is_dirty(index=True, working_tree=True, untracked_files=True):
+                        raise RepositoryDirtyError(mrepo, "Cannot reset a dirty repository")
+                    # END handle force and dirty state
+                # END handle empty repo
+
+                # END verify future/past
+                progress.update(
+                    BEGIN | UPDWKTREE,
+                    0,
+                    1,
+                    prefix
+                    + "Updating working tree at %s for submodule %r to revision %s" % (self.path, self.name, hexsha),
+                )
+
+                if not dry_run and may_reset:
+                    if is_detached:
+                        # NOTE: For now we force. The user is not supposed to change
+                        # detached submodules anyway. Maybe at some point this becomes
+                        # an option, to properly handle user modifications - see below
+                        # for future options regarding rebase and merge.
+                        mrepo.git.checkout(hexsha, force=force)
+                    else:
+                        mrepo.head.reset(hexsha, index=True, working_tree=True)
+                    # END handle checkout
+                # If we may reset/checkout.
+                progress.update(
+                    END | UPDWKTREE,
+                    0,
+                    1,
+                    prefix + "Done updating working tree for submodule %r" % self.name,
+                )
+            # END update to new commit only if needed
+        except Exception as err:
+            if not keep_going:
+                raise
+            _logger.error(str(err))
+        # END handle keep_going
+
+        # HANDLE RECURSION
+        ##################
+        if recursive:
+            # In dry_run mode, the module might not exist.
+            if mrepo is not None:
+                for submodule in self.iter_items(self.module()):
+                    submodule.update(
+                        recursive,
+                        init,
+                        to_latest_revision,
+                        progress=progress,
+                        dry_run=dry_run,
+                        force=force,
+                        keep_going=keep_going,
+                    )
+                # END handle recursive update
+            # END handle dry run
+        # END for each submodule
+
+        return self
+
+    @unbare_repo
+    def move(self, module_path: PathLike, configuration: bool = True, module: bool = True) -> "Submodule":
+        """Move the submodule to a another module path. This involves physically moving
+        the repository at our current path, changing the configuration, as well as
+        adjusting our index entry accordingly.
+
+        :param module_path:
+            The path to which to move our module in the parent repository's working
+            tree, given as repository-relative or absolute path. Intermediate
+            directories will be created accordingly. If the path already exists, it must
+            be empty. Trailing (back)slashes are removed automatically.
+
+        :param configuration:
+            If ``True``, the configuration will be adjusted to let the submodule point
+            to the given path.
+
+        :param module:
+            If ``True``, the repository managed by this submodule will be moved as well.
+            If ``False``, we don't move the submodule's checkout, which may leave the
+            parent repository in an inconsistent state.
+
+        :return:
+            self
+
+        :raise ValueError:
+            If the module path existed and was not empty, or was a file.
+
+        :note:
+            Currently the method is not atomic, and it could leave the repository in an
+            inconsistent state if a sub-step fails for some reason.
+        """
+        if module + configuration < 1:
+            raise ValueError("You must specify to move at least the module or the configuration of the submodule")
+        # END handle input
+
+        module_checkout_path = self._to_relative_path(self.repo, module_path)
+
+        # VERIFY DESTINATION
+        if module_checkout_path == self.path:
+            return self
+        # END handle no change
+
+        module_checkout_abspath = join_path_native(str(self.repo.working_tree_dir), module_checkout_path)
+        if osp.isfile(module_checkout_abspath):
+            raise ValueError("Cannot move repository onto a file: %s" % module_checkout_abspath)
+        # END handle target files
+
+        index = self.repo.index
+        tekey = index.entry_key(module_checkout_path, 0)
+        # if the target item already exists, fail
+        if configuration and tekey in index.entries:
+            raise ValueError("Index entry for target path did already exist")
+        # END handle index key already there
+
+        # Remove existing destination.
+        if module:
+            if osp.exists(module_checkout_abspath):
+                if len(os.listdir(module_checkout_abspath)):
+                    raise ValueError("Destination module directory was not empty")
+                # END handle non-emptiness
+
+                if osp.islink(module_checkout_abspath):
+                    os.remove(module_checkout_abspath)
+                else:
+                    os.rmdir(module_checkout_abspath)
+                # END handle link
+            else:
+                # Recreate parent directories.
+                # NOTE: renames() does that now.
+                pass
+            # END handle existence
+        # END handle module
+
+        # Move the module into place if possible.
+        cur_path = self.abspath
+        renamed_module = False
+        if module and osp.exists(cur_path):
+            os.renames(cur_path, module_checkout_abspath)
+            renamed_module = True
+
+            if osp.isfile(osp.join(module_checkout_abspath, ".git")):
+                module_abspath = self._module_abspath(self.repo, self.path, self.name)
+                self._write_git_file_and_module_config(module_checkout_abspath, module_abspath)
+            # END handle git file rewrite
+        # END move physical module
+
+        # Rename the index entry - we have to manipulate the index directly as git-mv
+        # cannot be used on submodules... yeah.
+        previous_sm_path = self.path
+        try:
+            if configuration:
+                try:
+                    ekey = index.entry_key(self.path, 0)
+                    entry = index.entries[ekey]
+                    del index.entries[ekey]
+                    nentry = git.IndexEntry(entry[:3] + (module_checkout_path,) + entry[4:])
+                    index.entries[tekey] = nentry
+                except KeyError as e:
+                    raise InvalidGitRepositoryError("Submodule's entry at %r did not exist" % (self.path)) from e
+                # END handle submodule doesn't exist
+
+                # Update configuration.
+                with self.config_writer(index=index) as writer:  # Auto-write.
+                    writer.set_value("path", module_checkout_path)
+                    self.path = module_checkout_path
+            # END handle configuration flag
+        except Exception:
+            if renamed_module:
+                os.renames(module_checkout_abspath, cur_path)
+            # END undo module renaming
+            raise
+        # END handle undo rename
+
+        # Auto-rename submodule if its name was 'default', that is, the checkout
+        # directory.
+        if previous_sm_path == self.name:
+            self.rename(module_checkout_path)
+
+        return self
+
+    @unbare_repo
+    def remove(
+        self,
+        module: bool = True,
+        force: bool = False,
+        configuration: bool = True,
+        dry_run: bool = False,
+    ) -> "Submodule":
+        """Remove this submodule from the repository. This will remove our entry
+        from the ``.gitmodules`` file and the entry in the ``.git/config`` file.
+
+        :param module:
+            If ``True``, the checked out module we point to will be deleted as well. If
+            that module is currently on a commit outside any branch in the remote, or if
+            it is ahead of its tracking branch, or if there are modified or untracked
+            files in its working tree, then the removal will fail. In case the removal
+            of the repository fails for these reasons, the submodule status will not
+            have been altered.
+
+            If this submodule has child modules of its own, these will be deleted prior
+            to touching the direct submodule.
+
+        :param force:
+            Enforces the deletion of the module even though it contains modifications.
+            This basically enforces a brute-force file system based deletion.
+
+        :param configuration:
+            If ``True``, the submodule is deleted from the configuration, otherwise it
+            isn't. Although this should be enabled most of the time, this flag enables
+            you to safely delete the repository of your submodule.
+
+        :param dry_run:
+            If ``True``, we will not actually do anything, but throw the errors we would
+            usually throw.
+
+        :return:
+            self
+
+        :note:
+            Doesn't work in bare repositories.
+
+        :note:
+            Doesn't work atomically, as failure to remove any part of the submodule will
+            leave an inconsistent state.
+
+        :raise git.exc.InvalidGitRepositoryError:
+            Thrown if the repository cannot be deleted.
+
+        :raise OSError:
+            If directories or files could not be removed.
+        """
+        if not (module or configuration):
+            raise ValueError("Need to specify to delete at least the module, or the configuration")
+        # END handle parameters
+
+        # Recursively remove children of this submodule.
+        nc = 0
+        for csm in self.children():
+            nc += 1
+            csm.remove(module, force, configuration, dry_run)
+            del csm
+
+        if configuration and not dry_run and nc > 0:
+            # Ensure we don't leave the parent repository in a dirty state, and commit
+            # our changes. It's important for recursive, unforced, deletions to work as
+            # expected.
+            self.module().index.commit("Removed at least one of child-modules of '%s'" % self.name)
+        # END handle recursion
+
+        # DELETE REPOSITORY WORKING TREE
+        ################################
+        if module and self.module_exists():
+            mod = self.module()
+            git_dir = mod.git_dir
+            if force:
+                # Take the fast lane and just delete everything in our module path.
+                # TODO: If we run into permission problems, we have a highly
+                # inconsistent state. Delete the .git folders last, start with the
+                # submodules first.
+                mp = self.abspath
+                method: Union[None, Callable[[PathLike], None]] = None
+                if osp.islink(mp):
+                    method = os.remove
+                elif osp.isdir(mp):
+                    method = rmtree
+                elif osp.exists(mp):
+                    raise AssertionError("Cannot forcibly delete repository as it was neither a link, nor a directory")
+                # END handle brutal deletion
+                if not dry_run:
+                    assert method
+                    method(mp)
+                # END apply deletion method
+            else:
+                # Verify we may delete our module.
+                if mod.is_dirty(index=True, working_tree=True, untracked_files=True):
+                    raise InvalidGitRepositoryError(
+                        "Cannot delete module at %s with any modifications, unless force is specified"
+                        % mod.working_tree_dir
+                    )
+                # END check for dirt
+
+                # Figure out whether we have new commits compared to the remotes.
+                # NOTE: If the user pulled all the time, the remote heads might not have
+                # been updated, so commits coming from the remote look as if they come
+                # from us. But we stay strictly read-only and don't fetch beforehand.
+                for remote in mod.remotes:
+                    num_branches_with_new_commits = 0
+                    rrefs = remote.refs
+                    for rref in rrefs:
+                        num_branches_with_new_commits += len(mod.git.cherry(rref)) != 0
+                    # END for each remote ref
+                    # Not a single remote branch contained all our commits.
+                    if len(rrefs) and num_branches_with_new_commits == len(rrefs):
+                        raise InvalidGitRepositoryError(
+                            "Cannot delete module at %s as there are new commits" % mod.working_tree_dir
+                        )
+                    # END handle new commits
+                    # We have to manually delete some references to allow resources to
+                    # be cleaned up immediately when we are done with them, because
+                    # Python's scoping is no more granular than the whole function (loop
+                    # bodies are not scopes). When the objects stay alive longer, they
+                    # can keep handles open. On Windows, this is a problem.
+                    if len(rrefs):
+                        del rref  # skipcq: PYL-W0631
+                    # END handle remotes
+                    del rrefs
+                    del remote
+                # END for each remote
+
+                # Finally delete our own submodule.
+                if not dry_run:
+                    self._clear_cache()
+                    wtd = mod.working_tree_dir
+                    del mod  # Release file-handles (Windows).
+                    gc.collect()
+                    rmtree(str(wtd))
+                # END delete tree if possible
+            # END handle force
+
+            if not dry_run and osp.isdir(git_dir):
+                self._clear_cache()
+                rmtree(git_dir)
+            # END handle separate bare repository
+        # END handle module deletion
+
+        # Void our data so as not to delay invalid access.
+        if not dry_run:
+            self._clear_cache()
+
+        # DELETE CONFIGURATION
+        ######################
+        if configuration and not dry_run:
+            # First the index-entry.
+            parent_index = self.repo.index
+            try:
+                del parent_index.entries[parent_index.entry_key(self.path, 0)]
+            except KeyError:
+                pass
+            # END delete entry
+            parent_index.write()
+
+            # Now git config - we need the config intact, otherwise we can't query
+            # information anymore.
+
+            with self.repo.config_writer() as gcp_writer:
+                gcp_writer.remove_section(sm_section(self.name))
+
+            with self.config_writer() as sc_writer:
+                sc_writer.remove_section()
+        # END delete configuration
+
+        return self
+
+    def set_parent_commit(self, commit: Union[Commit_ish, str, None], check: bool = True) -> "Submodule":
+        """Set this instance to use the given commit whose tree is supposed to
+        contain the ``.gitmodules`` blob.
+
+        :param commit:
+            Commit-ish reference pointing at the root tree, or ``None`` to always point
+            to the most recent commit.
+
+        :param check:
+            If ``True``, relatively expensive checks will be performed to verify
+            validity of the submodule.
+
+        :raise ValueError:
+            If the commit's tree didn't contain the ``.gitmodules`` blob.
+
+        :raise ValueError:
+            If the parent commit didn't store this submodule under the current path.
+
+        :return:
+            self
+        """
+        if commit is None:
+            self._parent_commit = None
+            return self
+        # END handle None
+        pcommit = self.repo.commit(commit)
+        pctree = pcommit.tree
+        if self.k_modules_file not in pctree:
+            raise ValueError("Tree of commit %s did not contain the %s file" % (commit, self.k_modules_file))
+        # END handle exceptions
+
+        prev_pc = self._parent_commit
+        self._parent_commit = pcommit
+
+        if check:
+            parser = self._config_parser(self.repo, self._parent_commit, read_only=True)
+            if not parser.has_section(sm_section(self.name)):
+                self._parent_commit = prev_pc
+                raise ValueError("Submodule at path %r did not exist in parent commit %s" % (self.path, commit))
+            # END handle submodule did not exist
+        # END handle checking mode
+
+        # Update our sha, it could have changed.
+        # If check is False, we might see a parent-commit that doesn't even contain the
+        # submodule anymore. in that case, mark our sha as being NULL.
+        try:
+            self.binsha = pctree[str(self.path)].binsha
+        except KeyError:
+            self.binsha = self.NULL_BIN_SHA
+
+        self._clear_cache()
+        return self
+
+    @unbare_repo
+    def config_writer(
+        self, index: Union["IndexFile", None] = None, write: bool = True
+    ) -> SectionConstraint["SubmoduleConfigParser"]:
+        """
+        :return:
+            A config writer instance allowing you to read and write the data belonging
+            to this submodule into the ``.gitmodules`` file.
+
+        :param index:
+            If not ``None``, an :class:`~git.index.base.IndexFile` instance which should
+            be written. Defaults to the index of the :class:`Submodule`'s parent
+            repository.
+
+        :param write:
+            If ``True``, the index will be written each time a configuration value changes.
+
+        :note:
+            The parameters allow for a more efficient writing of the index, as you can
+            pass in a modified index on your own, prevent automatic writing, and write
+            yourself once the whole operation is complete.
+
+        :raise ValueError:
+            If trying to get a writer on a parent_commit which does not match the
+            current head commit.
+
+        :raise IOError:
+            If the ``.gitmodules`` file/blob could not be read.
+        """
+        writer = self._config_parser_constrained(read_only=False)
+        if index is not None:
+            writer.config._index = index
+        writer.config._auto_write = write
+        return writer
+
+    @unbare_repo
+    def rename(self, new_name: str) -> "Submodule":
+        """Rename this submodule.
+
+        :note:
+            This method takes care of renaming the submodule in various places, such as:
+
+            * ``$parent_git_dir / config``
+            * ``$working_tree_dir / .gitmodules``
+            * (git >= v1.8.0: move submodule repository to new name)
+
+        As ``.gitmodules`` will be changed, you would need to make a commit afterwards.
+        The changed ``.gitmodules`` file will already be added to the index.
+
+        :return:
+            This :class:`Submodule` instance
+        """
+        if self.name == new_name:
+            return self
+
+        # .git/config
+        with self.repo.config_writer() as pw:
+            # As we ourselves didn't write anything about submodules into the parent
+            # .git/config, we will not require it to exist, and just ignore missing
+            # entries.
+            if pw.has_section(sm_section(self.name)):
+                pw.rename_section(sm_section(self.name), sm_section(new_name))
+
+        # .gitmodules
+        with self.config_writer(write=True).config as cw:
+            cw.rename_section(sm_section(self.name), sm_section(new_name))
+
+        self._name = new_name
+
+        # .git/modules
+        mod = self.module()
+        if mod.has_separate_working_tree():
+            destination_module_abspath = self._module_abspath(self.repo, self.path, new_name)
+            source_dir = mod.git_dir
+            # Let's be sure the submodule name is not so obviously tied to a directory.
+            if str(destination_module_abspath).startswith(str(mod.git_dir)):
+                tmp_dir = self._module_abspath(self.repo, self.path, str(uuid.uuid4()))
+                os.renames(source_dir, tmp_dir)
+                source_dir = tmp_dir
+            # END handle self-containment
+            os.renames(source_dir, destination_module_abspath)
+            if mod.working_tree_dir:
+                self._write_git_file_and_module_config(mod.working_tree_dir, destination_module_abspath)
+        # END move separate git repository
+
+        return self
+
+    # } END edit interface
+
+    # { Query Interface
+
+    @unbare_repo
+    def module(self) -> "Repo":
+        """
+        :return:
+            :class:`~git.repo.base.Repo` instance initialized from the repository at our
+            submodule path
+
+        :raise git.exc.InvalidGitRepositoryError:
+            If a repository was not available.
+            This could also mean that it was not yet initialized.
+        """
+        module_checkout_abspath = self.abspath
+        try:
+            repo = git.Repo(module_checkout_abspath)
+            if repo != self.repo:
+                return repo
+            # END handle repo uninitialized
+        except (InvalidGitRepositoryError, NoSuchPathError) as e:
+            raise InvalidGitRepositoryError("No valid repository at %s" % module_checkout_abspath) from e
+        else:
+            raise InvalidGitRepositoryError("Repository at %r was not yet checked out" % module_checkout_abspath)
+        # END handle exceptions
+
+    def module_exists(self) -> bool:
+        """
+        :return:
+            ``True`` if our module exists and is a valid git repository.
+            See the :meth:`module` method.
+        """
+        try:
+            self.module()
+            return True
+        except Exception:
+            return False
+        # END handle exception
+
+    def exists(self) -> bool:
+        """
+        :return:
+            ``True`` if the submodule exists, ``False`` otherwise.
+            Please note that a submodule may exist (in the ``.gitmodules`` file) even
+            though its module doesn't exist on disk.
+        """
+        # Keep attributes for later, and restore them if we have no valid data.
+        # This way we do not actually alter the state of the object.
+        loc = locals()
+        for attr in self._cache_attrs:
+            try:
+                if hasattr(self, attr):
+                    loc[attr] = getattr(self, attr)
+                # END if we have the attribute cache
+            except (cp.NoSectionError, ValueError):
+                # On PY3, this can happen apparently... don't know why this doesn't
+                # happen on PY2.
+                pass
+        # END for each attr
+        self._clear_cache()
+
+        try:
+            try:
+                self.path  # noqa: B018
+                return True
+            except Exception:
+                return False
+            # END handle exceptions
+        finally:
+            for attr in self._cache_attrs:
+                if attr in loc:
+                    setattr(self, attr, loc[attr])
+                # END if we have a cache
+            # END reapply each attribute
+        # END handle object state consistency
+
+    @property
+    def branch(self) -> "Head":
+        """
+        :return:
+            The branch instance that we are to checkout
+
+        :raise git.exc.InvalidGitRepositoryError:
+            If our module is not yet checked out.
+        """
+        return mkhead(self.module(), self._branch_path)
+
+    @property
+    def branch_path(self) -> PathLike:
+        """
+        :return:
+            Full repository-relative path as string to the branch we would checkout from
+            the remote and track
+        """
+        return self._branch_path
+
+    @property
+    def branch_name(self) -> str:
+        """
+        :return:
+            The name of the branch, which is the shortest possible branch name
+        """
+        # Use an instance method, for this we create a temporary Head instance which
+        # uses a repository that is available at least (it makes no difference).
+        return git.Head(self.repo, self._branch_path).name
+
+    @property
+    def url(self) -> str:
+        """:return: The url to the repository our submodule's repository refers to"""
+        return self._url
+
+    @property
+    def parent_commit(self) -> "Commit":
+        """
+        :return:
+            :class:`~git.objects.commit.Commit` instance with the tree containing the
+            ``.gitmodules`` file
+
+        :note:
+            Will always point to the current head's commit if it was not set explicitly.
+        """
+        if self._parent_commit is None:
+            return self.repo.commit()
+        return self._parent_commit
+
+    @property
+    def name(self) -> str:
+        """
+        :return:
+            The name of this submodule. It is used to identify it within the
+            ``.gitmodules`` file.
+
+        :note:
+            By default, this is the name is the path at which to find the submodule, but
+            in GitPython it should be a unique identifier similar to the identifiers
+            used for remotes, which allows to change the path of the submodule easily.
+        """
+        return self._name
+
+    def config_reader(self) -> SectionConstraint[SubmoduleConfigParser]:
+        """
+        :return:
+            ConfigReader instance which allows you to query the configuration values of
+            this submodule, as provided by the ``.gitmodules`` file.
+
+        :note:
+            The config reader will actually read the data directly from the repository
+            and thus does not need nor care about your working tree.
+
+        :note:
+            Should be cached by the caller and only kept as long as needed.
+
+        :raise IOError:
+            If the ``.gitmodules`` file/blob could not be read.
+        """
+        return self._config_parser_constrained(read_only=True)
+
+    def children(self) -> IterableList["Submodule"]:
+        """
+        :return:
+            IterableList(Submodule, ...) An iterable list of :class:`Submodule`
+            instances which are children of this submodule or 0 if the submodule is not
+            checked out.
+        """
+        return self._get_intermediate_items(self)
+
+    # } END query interface
+
+    # { Iterable Interface
+
+    @classmethod
+    def iter_items(
+        cls,
+        repo: "Repo",
+        parent_commit: Union[Commit_ish, str] = "HEAD",
+        *args: Any,
+        **kwargs: Any,
+    ) -> Iterator["Submodule"]:
+        """
+        :return:
+            Iterator yielding :class:`Submodule` instances available in the given
+            repository
+        """
+        try:
+            pc = repo.commit(parent_commit)  # Parent commit instance
+            parser = cls._config_parser(repo, pc, read_only=True)
+        except (IOError, BadName):
+            return
+        # END handle empty iterator
+
+        for sms in parser.sections():
+            n = sm_name(sms)
+            p = parser.get(sms, "path")
+            u = parser.get(sms, "url")
+            b = cls.k_head_default
+            if parser.has_option(sms, cls.k_head_option):
+                b = str(parser.get(sms, cls.k_head_option))
+            # END handle optional information
+
+            # Get the binsha.
+            index = repo.index
+            try:
+                rt = pc.tree  # Root tree
+                sm = rt[p]
+            except KeyError:
+                # Try the index, maybe it was just added.
+                try:
+                    entry = index.entries[index.entry_key(p, 0)]
+                    sm = Submodule(repo, entry.binsha, entry.mode, entry.path)
+                except KeyError:
+                    # The submodule doesn't exist, probably it wasn't removed from the
+                    # .gitmodules file.
+                    continue
+                # END handle keyerror
+            # END handle critical error
+
+            # Make sure we are looking at a submodule object.
+            if type(sm) is not git.objects.submodule.base.Submodule:
+                continue
+
+            # Fill in remaining info - saves time as it doesn't have to be parsed again.
+            sm._name = n
+            if pc != repo.commit():
+                sm._parent_commit = pc
+            # END set only if not most recent!
+            sm._branch_path = git.Head.to_full_path(b)
+            sm._url = u
+
+            yield sm
+        # END for each section
+
+    # } END iterable interface

.venv/lib/python3.11/site-packages/git/objects/submodule/root.py

@@ -0,0 +1,467 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+__all__ = ["RootModule", "RootUpdateProgress"]
+
+import logging
+
+import git
+from git.exc import InvalidGitRepositoryError
+
+from .base import Submodule, UpdateProgress
+from .util import find_first_remote_branch
+
+# typing -------------------------------------------------------------------
+
+from typing import TYPE_CHECKING, Union
+
+from git.types import Commit_ish
+
+if TYPE_CHECKING:
+    from git.repo import Repo
+    from git.util import IterableList
+
+# ----------------------------------------------------------------------------
+
+_logger = logging.getLogger(__name__)
+
+
+class RootUpdateProgress(UpdateProgress):
+    """Utility class which adds more opcodes to
+    :class:`~git.objects.submodule.base.UpdateProgress`."""
+
+    REMOVE, PATHCHANGE, BRANCHCHANGE, URLCHANGE = [
+        1 << x for x in range(UpdateProgress._num_op_codes, UpdateProgress._num_op_codes + 4)
+    ]
+    _num_op_codes = UpdateProgress._num_op_codes + 4
+
+    __slots__ = ()
+
+
+BEGIN = RootUpdateProgress.BEGIN
+END = RootUpdateProgress.END
+REMOVE = RootUpdateProgress.REMOVE
+BRANCHCHANGE = RootUpdateProgress.BRANCHCHANGE
+URLCHANGE = RootUpdateProgress.URLCHANGE
+PATHCHANGE = RootUpdateProgress.PATHCHANGE
+
+
+class RootModule(Submodule):
+    """A (virtual) root of all submodules in the given repository.
+
+    This can be used to more easily traverse all submodules of the
+    superproject (master repository).
+    """
+
+    __slots__ = ()
+
+    k_root_name = "__ROOT__"
+
+    def __init__(self, repo: "Repo") -> None:
+        # repo, binsha, mode=None, path=None, name = None, parent_commit=None, url=None, ref=None)
+        super().__init__(
+            repo,
+            binsha=self.NULL_BIN_SHA,
+            mode=self.k_default_mode,
+            path="",
+            name=self.k_root_name,
+            parent_commit=repo.head.commit,
+            url="",
+            branch_path=git.Head.to_full_path(self.k_head_default),
+        )
+
+    def _clear_cache(self) -> None:
+        """May not do anything."""
+        pass
+
+    # { Interface
+
+    def update(  # type: ignore[override]
+        self,
+        previous_commit: Union[Commit_ish, str, None] = None,
+        recursive: bool = True,
+        force_remove: bool = False,
+        init: bool = True,
+        to_latest_revision: bool = False,
+        progress: Union[None, "RootUpdateProgress"] = None,
+        dry_run: bool = False,
+        force_reset: bool = False,
+        keep_going: bool = False,
+    ) -> "RootModule":
+        """Update the submodules of this repository to the current HEAD commit.
+
+        This method behaves smartly by determining changes of the path of a submodule's
+        repository, next to changes to the to-be-checked-out commit or the branch to be
+        checked out. This works if the submodule's ID does not change.
+
+        Additionally it will detect addition and removal of submodules, which will be
+        handled gracefully.
+
+        :param previous_commit:
+            If set to a commit-ish, the commit we should use as the previous commit the
+            HEAD pointed to before it was set to the commit it points to now.
+            If ``None``, it defaults to ``HEAD@{1}`` otherwise.
+
+        :param recursive:
+            If ``True``, the children of submodules will be updated as well using the
+            same technique.
+
+        :param force_remove:
+            If submodules have been deleted, they will be forcibly removed. Otherwise
+            the update may fail if a submodule's repository cannot be deleted as changes
+            have been made to it.
+            (See :meth:`Submodule.update <git.objects.submodule.base.Submodule.update>`
+            for more information.)
+
+        :param init:
+            If we encounter a new module which would need to be initialized, then do it.
+
+        :param to_latest_revision:
+            If ``True``, instead of checking out the revision pointed to by this
+            submodule's sha, the checked out tracking branch will be merged with the
+            latest remote branch fetched from the repository's origin.
+
+            Unless `force_reset` is specified, a local tracking branch will never be
+            reset into its past, therefore the remote branch must be in the future for
+            this to have an effect.
+
+        :param force_reset:
+            If ``True``, submodules may checkout or reset their branch even if the
+            repository has pending changes that would be overwritten, or if the local
+            tracking branch is in the future of the remote tracking branch and would be
+            reset into its past.
+
+        :param progress:
+            :class:`RootUpdateProgress` instance, or ``None`` if no progress should be
+            sent.
+
+        :param dry_run:
+            If ``True``, operations will not actually be performed. Progress messages
+            will change accordingly to indicate the WOULD DO state of the operation.
+
+        :param keep_going:
+            If ``True``, we will ignore but log all errors, and keep going recursively.
+            Unless `dry_run` is set as well, `keep_going` could cause
+            subsequent/inherited errors you wouldn't see otherwise.
+            In conjunction with `dry_run`, this can be useful to anticipate all errors
+            when updating submodules.
+
+        :return:
+            self
+        """
+        if self.repo.bare:
+            raise InvalidGitRepositoryError("Cannot update submodules in bare repositories")
+        # END handle bare
+
+        if progress is None:
+            progress = RootUpdateProgress()
+        # END ensure progress is set
+
+        prefix = ""
+        if dry_run:
+            prefix = "DRY-RUN: "
+
+        repo = self.repo
+
+        try:
+            # SETUP BASE COMMIT
+            ###################
+            cur_commit = repo.head.commit
+            if previous_commit is None:
+                try:
+                    previous_commit = repo.commit(repo.head.log_entry(-1).oldhexsha)
+                    if previous_commit.binsha == previous_commit.NULL_BIN_SHA:
+                        raise IndexError
+                    # END handle initial commit
+                except IndexError:
+                    # In new repositories, there is no previous commit.
+                    previous_commit = cur_commit
+                # END exception handling
+            else:
+                previous_commit = repo.commit(previous_commit)  # Obtain commit object.
+            # END handle previous commit
+
+            psms: "IterableList[Submodule]" = self.list_items(repo, parent_commit=previous_commit)
+            sms: "IterableList[Submodule]" = self.list_items(repo)
+            spsms = set(psms)
+            ssms = set(sms)
+
+            # HANDLE REMOVALS
+            ###################
+            rrsm = spsms - ssms
+            len_rrsm = len(rrsm)
+
+            for i, rsm in enumerate(rrsm):
+                op = REMOVE
+                if i == 0:
+                    op |= BEGIN
+                # END handle begin
+
+                # Fake it into thinking its at the current commit to allow deletion
+                # of previous module. Trigger the cache to be updated before that.
+                progress.update(
+                    op,
+                    i,
+                    len_rrsm,
+                    prefix + "Removing submodule %r at %s" % (rsm.name, rsm.abspath),
+                )
+                rsm._parent_commit = repo.head.commit
+                rsm.remove(
+                    configuration=False,
+                    module=True,
+                    force=force_remove,
+                    dry_run=dry_run,
+                )
+
+                if i == len_rrsm - 1:
+                    op |= END
+                # END handle end
+                progress.update(op, i, len_rrsm, prefix + "Done removing submodule %r" % rsm.name)
+            # END for each removed submodule
+
+            # HANDLE PATH RENAMES
+            #####################
+            # URL changes + branch changes.
+            csms = spsms & ssms
+            len_csms = len(csms)
+            for i, csm in enumerate(csms):
+                psm: "Submodule" = psms[csm.name]
+                sm: "Submodule" = sms[csm.name]
+
+                # PATH CHANGES
+                ##############
+                if sm.path != psm.path and psm.module_exists():
+                    progress.update(
+                        BEGIN | PATHCHANGE,
+                        i,
+                        len_csms,
+                        prefix + "Moving repository of submodule %r from %s to %s" % (sm.name, psm.abspath, sm.abspath),
+                    )
+                    # Move the module to the new path.
+                    if not dry_run:
+                        psm.move(sm.path, module=True, configuration=False)
+                    # END handle dry_run
+                    progress.update(
+                        END | PATHCHANGE,
+                        i,
+                        len_csms,
+                        prefix + "Done moving repository of submodule %r" % sm.name,
+                    )
+                # END handle path changes
+
+                if sm.module_exists():
+                    # HANDLE URL CHANGE
+                    ###################
+                    if sm.url != psm.url:
+                        # Add the new remote, remove the old one.
+                        # This way, if the url just changes, the commits will not have
+                        # to be re-retrieved.
+                        nn = "__new_origin__"
+                        smm = sm.module()
+                        rmts = smm.remotes
+
+                        # Don't do anything if we already have the url we search in
+                        # place.
+                        if len([r for r in rmts if r.url == sm.url]) == 0:
+                            progress.update(
+                                BEGIN | URLCHANGE,
+                                i,
+                                len_csms,
+                                prefix + "Changing url of submodule %r from %s to %s" % (sm.name, psm.url, sm.url),
+                            )
+
+                            if not dry_run:
+                                assert nn not in [r.name for r in rmts]
+                                smr = smm.create_remote(nn, sm.url)
+                                smr.fetch(progress=progress)
+
+                                # If we have a tracking branch, it should be available
+                                # in the new remote as well.
+                                if len([r for r in smr.refs if r.remote_head == sm.branch_name]) == 0:
+                                    raise ValueError(
+                                        "Submodule branch named %r was not available in new submodule remote at %r"
+                                        % (sm.branch_name, sm.url)
+                                    )
+                                # END head is not detached
+
+                                # Now delete the changed one.
+                                rmt_for_deletion = None
+                                for remote in rmts:
+                                    if remote.url == psm.url:
+                                        rmt_for_deletion = remote
+                                        break
+                                    # END if urls match
+                                # END for each remote
+
+                                # If we didn't find a matching remote, but have exactly
+                                # one, we can safely use this one.
+                                if rmt_for_deletion is None:
+                                    if len(rmts) == 1:
+                                        rmt_for_deletion = rmts[0]
+                                    else:
+                                        # If we have not found any remote with the
+                                        # original URL we may not have a name. This is a
+                                        # special case, and its okay to fail here.
+                                        # Alternatively we could just generate a unique
+                                        # name and leave all existing ones in place.
+                                        raise InvalidGitRepositoryError(
+                                            "Couldn't find original remote-repo at url %r" % psm.url
+                                        )
+                                    # END handle one single remote
+                                # END handle check we found a remote
+
+                                orig_name = rmt_for_deletion.name
+                                smm.delete_remote(rmt_for_deletion)
+                                # NOTE: Currently we leave tags from the deleted remotes
+                                # as well as separate tracking branches in the possibly
+                                # totally changed repository (someone could have changed
+                                # the url to another project). At some point, one might
+                                # want to clean it up, but the danger is high to remove
+                                # stuff the user has added explicitly.
+
+                                # Rename the new remote back to what it was.
+                                smr.rename(orig_name)
+
+                                # Early on, we verified that the our current tracking
+                                # branch exists in the remote. Now we have to ensure
+                                # that the sha we point to is still contained in the new
+                                # remote tracking branch.
+                                smsha = sm.binsha
+                                found = False
+                                rref = smr.refs[self.branch_name]
+                                for c in rref.commit.traverse():
+                                    if c.binsha == smsha:
+                                        found = True
+                                        break
+                                    # END traverse all commits in search for sha
+                                # END for each commit
+
+                                if not found:
+                                    # Adjust our internal binsha to use the one of the
+                                    # remote this way, it will be checked out in the
+                                    # next step. This will change the submodule relative
+                                    # to us, so the user will be able to commit the
+                                    # change easily.
+                                    _logger.warning(
+                                        "Current sha %s was not contained in the tracking\
+             branch at the new remote, setting it the the remote's tracking branch",
+                                        sm.hexsha,
+                                    )
+                                    sm.binsha = rref.commit.binsha
+                                # END reset binsha
+
+                                # NOTE: All checkout is performed by the base
+                                # implementation of update.
+                            # END handle dry_run
+                            progress.update(
+                                END | URLCHANGE,
+                                i,
+                                len_csms,
+                                prefix + "Done adjusting url of submodule %r" % (sm.name),
+                            )
+                        # END skip remote handling if new url already exists in module
+                    # END handle url
+
+                    # HANDLE PATH CHANGES
+                    #####################
+                    if sm.branch_path != psm.branch_path:
+                        # Finally, create a new tracking branch which tracks the new
+                        # remote branch.
+                        progress.update(
+                            BEGIN | BRANCHCHANGE,
+                            i,
+                            len_csms,
+                            prefix
+                            + "Changing branch of submodule %r from %s to %s"
+                            % (sm.name, psm.branch_path, sm.branch_path),
+                        )
+                        if not dry_run:
+                            smm = sm.module()
+                            smmr = smm.remotes
+                            # As the branch might not exist yet, we will have to fetch
+                            # all remotes to be sure...
+                            for remote in smmr:
+                                remote.fetch(progress=progress)
+                            # END for each remote
+
+                            try:
+                                tbr = git.Head.create(
+                                    smm,
+                                    sm.branch_name,
+                                    logmsg="branch: Created from HEAD",
+                                )
+                            except OSError:
+                                # ...or reuse the existing one.
+                                tbr = git.Head(smm, sm.branch_path)
+                            # END ensure tracking branch exists
+
+                            tbr.set_tracking_branch(find_first_remote_branch(smmr, sm.branch_name))
+                            # NOTE: All head-resetting is done in the base
+                            # implementation of update but we will have to checkout the
+                            # new branch here. As it still points to the currently
+                            # checked out commit, we don't do any harm.
+                            # As we don't want to update working-tree or index, changing
+                            # the ref is all there is to do.
+                            smm.head.reference = tbr
+                        # END handle dry_run
+
+                        progress.update(
+                            END | BRANCHCHANGE,
+                            i,
+                            len_csms,
+                            prefix + "Done changing branch of submodule %r" % sm.name,
+                        )
+                    # END handle branch
+                # END handle
+            # END for each common submodule
+        except Exception as err:
+            if not keep_going:
+                raise
+            _logger.error(str(err))
+        # END handle keep_going
+
+        # FINALLY UPDATE ALL ACTUAL SUBMODULES
+        ######################################
+        for sm in sms:
+            # Update the submodule using the default method.
+            sm.update(
+                recursive=False,
+                init=init,
+                to_latest_revision=to_latest_revision,
+                progress=progress,
+                dry_run=dry_run,
+                force=force_reset,
+                keep_going=keep_going,
+            )
+
+            # Update recursively depth first - question is which inconsistent state will
+            # be better in case it fails somewhere. Defective branch or defective depth.
+            # The RootSubmodule type will never process itself, which was done in the
+            # previous expression.
+            if recursive:
+                # The module would exist by now if we are not in dry_run mode.
+                if sm.module_exists():
+                    type(self)(sm.module()).update(
+                        recursive=True,
+                        force_remove=force_remove,
+                        init=init,
+                        to_latest_revision=to_latest_revision,
+                        progress=progress,
+                        dry_run=dry_run,
+                        force_reset=force_reset,
+                        keep_going=keep_going,
+                    )
+                # END handle dry_run
+            # END handle recursive
+        # END for each submodule to update
+
+        return self
+
+    def module(self) -> "Repo":
+        """:return: The actual repository containing the submodules"""
+        return self.repo
+
+    # } END interface
+
+
+# } END classes

.venv/lib/python3.11/site-packages/git/objects/submodule/util.py

@@ -0,0 +1,121 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+__all__ = [
+    "sm_section",
+    "sm_name",
+    "mkhead",
+    "find_first_remote_branch",
+    "SubmoduleConfigParser",
+]
+
+from io import BytesIO
+import weakref
+
+import git
+from git.config import GitConfigParser
+from git.exc import InvalidGitRepositoryError
+
+# typing -----------------------------------------------------------------------
+
+from typing import Any, Sequence, TYPE_CHECKING, Union
+
+from git.types import PathLike
+
+if TYPE_CHECKING:
+    from weakref import ReferenceType
+
+    from git.refs import Head, RemoteReference
+    from git.remote import Remote
+    from git.repo import Repo
+
+    from .base import Submodule
+
+# { Utilities
+
+
+def sm_section(name: str) -> str:
+    """:return: Section title used in ``.gitmodules`` configuration file"""
+    return f'submodule "{name}"'
+
+
+def sm_name(section: str) -> str:
+    """:return: Name of the submodule as parsed from the section name"""
+    section = section.strip()
+    return section[11:-1]
+
+
+def mkhead(repo: "Repo", path: PathLike) -> "Head":
+    """:return: New branch/head instance"""
+    return git.Head(repo, git.Head.to_full_path(path))
+
+
+def find_first_remote_branch(remotes: Sequence["Remote"], branch_name: str) -> "RemoteReference":
+    """Find the remote branch matching the name of the given branch or raise
+    :exc:`~git.exc.InvalidGitRepositoryError`."""
+    for remote in remotes:
+        try:
+            return remote.refs[branch_name]
+        except IndexError:
+            continue
+        # END exception handling
+    # END for remote
+    raise InvalidGitRepositoryError("Didn't find remote branch '%r' in any of the given remotes" % branch_name)
+
+
+# } END utilities
+
+# { Classes
+
+
+class SubmoduleConfigParser(GitConfigParser):
+    """Catches calls to :meth:`~git.config.GitConfigParser.write`, and updates the
+    ``.gitmodules`` blob in the index with the new data, if we have written into a
+    stream.
+
+    Otherwise it would add the local file to the index to make it correspond with the
+    working tree. Additionally, the cache must be cleared.
+
+    Please note that no mutating method will work in bare mode.
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        self._smref: Union["ReferenceType[Submodule]", None] = None
+        self._index = None
+        self._auto_write = True
+        super().__init__(*args, **kwargs)
+
+    # { Interface
+    def set_submodule(self, submodule: "Submodule") -> None:
+        """Set this instance's submodule. It must be called before the first write
+        operation begins."""
+        self._smref = weakref.ref(submodule)
+
+    def flush_to_index(self) -> None:
+        """Flush changes in our configuration file to the index."""
+        assert self._smref is not None
+        # Should always have a file here.
+        assert not isinstance(self._file_or_files, BytesIO)
+
+        sm = self._smref()
+        if sm is not None:
+            index = self._index
+            if index is None:
+                index = sm.repo.index
+            # END handle index
+            index.add([sm.k_modules_file], write=self._auto_write)
+            sm._clear_cache()
+        # END handle weakref
+
+    # } END interface
+
+    # { Overridden Methods
+    def write(self) -> None:  # type: ignore[override]
+        rval: None = super().write()
+        self.flush_to_index()
+        return rval
+
+    # END overridden methods
+
+
+# } END classes

.venv/lib/python3.11/site-packages/git/objects/tag.py

@@ -0,0 +1,140 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Provides an :class:`~git.objects.base.Object`-based type for annotated tags.
+
+This defines the :class:`TagObject` class, which represents annotated tags.
+For lightweight tags, see the :mod:`git.refs.tag` module.
+"""
+
+__all__ = ["TagObject"]
+
+import sys
+
+from git.compat import defenc
+from git.util import Actor, hex_to_bin
+
+from . import base
+from .util import get_object_type_by_name, parse_actor_and_date
+
+# typing ----------------------------------------------
+
+from typing import List, TYPE_CHECKING, Union
+
+if sys.version_info >= (3, 8):
+    from typing import Literal
+else:
+    from typing_extensions import Literal
+
+if TYPE_CHECKING:
+    from git.repo import Repo
+
+    from .blob import Blob
+    from .commit import Commit
+    from .tree import Tree
+
+# ---------------------------------------------------
+
+
+class TagObject(base.Object):
+    """Annotated (i.e. non-lightweight) tag carrying additional information about an
+    object we are pointing to.
+
+    See :manpage:`gitglossary(7)` on "tag object":
+    https://git-scm.com/docs/gitglossary#def_tag_object
+    """
+
+    type: Literal["tag"] = "tag"
+
+    __slots__ = (
+        "object",
+        "tag",
+        "tagger",
+        "tagged_date",
+        "tagger_tz_offset",
+        "message",
+    )
+
+    def __init__(
+        self,
+        repo: "Repo",
+        binsha: bytes,
+        object: Union[None, base.Object] = None,
+        tag: Union[None, str] = None,
+        tagger: Union[None, Actor] = None,
+        tagged_date: Union[int, None] = None,
+        tagger_tz_offset: Union[int, None] = None,
+        message: Union[str, None] = None,
+    ) -> None:  # @ReservedAssignment
+        """Initialize a tag object with additional data.
+
+        :param repo:
+            Repository this object is located in.
+
+        :param binsha:
+            20 byte SHA1.
+
+        :param object:
+            :class:`~git.objects.base.Object` instance of object we are pointing to.
+
+        :param tag:
+            Name of this tag.
+
+        :param tagger:
+            :class:`~git.util.Actor` identifying the tagger.
+
+        :param tagged_date: int_seconds_since_epoch
+            The DateTime of the tag creation.
+            Use :func:`time.gmtime` to convert it into a different format.
+
+        :param tagger_tz_offset: int_seconds_west_of_utc
+            The timezone that the `tagged_date` is in, in a format similar to
+            :attr:`time.altzone`.
+        """
+        super().__init__(repo, binsha)
+        if object is not None:
+            self.object: Union["Commit", "Blob", "Tree", "TagObject"] = object
+        if tag is not None:
+            self.tag = tag
+        if tagger is not None:
+            self.tagger = tagger
+        if tagged_date is not None:
+            self.tagged_date = tagged_date
+        if tagger_tz_offset is not None:
+            self.tagger_tz_offset = tagger_tz_offset
+        if message is not None:
+            self.message = message
+
+    def _set_cache_(self, attr: str) -> None:
+        """Cache all our attributes at once."""
+        if attr in TagObject.__slots__:
+            ostream = self.repo.odb.stream(self.binsha)
+            lines: List[str] = ostream.read().decode(defenc, "replace").splitlines()
+
+            _obj, hexsha = lines[0].split(" ")
+            _type_token, type_name = lines[1].split(" ")
+            object_type = get_object_type_by_name(type_name.encode("ascii"))
+            self.object = object_type(self.repo, hex_to_bin(hexsha))
+
+            self.tag = lines[2][4:]  # tag <tag name>
+
+            if len(lines) > 3:
+                tagger_info = lines[3]  # tagger <actor> <date>
+                (
+                    self.tagger,
+                    self.tagged_date,
+                    self.tagger_tz_offset,
+                ) = parse_actor_and_date(tagger_info)
+
+            # Line 4 empty - it could mark the beginning of the next header.
+            # In case there really is no message, it would not exist.
+            # Otherwise a newline separates header from message.
+            if len(lines) > 5:
+                self.message = "\n".join(lines[5:])
+            else:
+                self.message = ""
+        # END check our attributes
+        else:
+            super()._set_cache_(attr)

.venv/lib/python3.11/site-packages/git/objects/tree.py

@@ -0,0 +1,416 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+__all__ = ["TreeModifier", "Tree"]
+
+import sys
+
+import git.diff as git_diff
+from git.util import IterableList, join_path, to_bin_sha
+
+from . import util
+from .base import IndexObjUnion, IndexObject
+from .blob import Blob
+from .fun import tree_entries_from_data, tree_to_stream
+from .submodule.base import Submodule
+
+# typing -------------------------------------------------
+
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterable,
+    Iterator,
+    List,
+    Tuple,
+    TYPE_CHECKING,
+    Type,
+    Union,
+    cast,
+)
+
+if sys.version_info >= (3, 8):
+    from typing import Literal
+else:
+    from typing_extensions import Literal
+
+from git.types import PathLike
+
+if TYPE_CHECKING:
+    from io import BytesIO
+
+    from git.repo import Repo
+
+TreeCacheTup = Tuple[bytes, int, str]
+
+TraversedTreeTup = Union[Tuple[Union["Tree", None], IndexObjUnion, Tuple["Submodule", "Submodule"]]]
+
+# --------------------------------------------------------
+
+
+def cmp(a: str, b: str) -> int:
+    return (a > b) - (a < b)
+
+
+class TreeModifier:
+    """A utility class providing methods to alter the underlying cache in a list-like
+    fashion.
+
+    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.
+    """
+
+    __slots__ = ("_cache",)
+
+    def __init__(self, cache: List[TreeCacheTup]) -> None:
+        self._cache = cache
+
+    def _index_by_name(self, name: str) -> int:
+        """:return: index of an item with name, or -1 if not found"""
+        for i, t in enumerate(self._cache):
+            if t[2] == name:
+                return i
+            # END found item
+        # END for each item in cache
+        return -1
+
+    # { Interface
+    def set_done(self) -> "TreeModifier":
+        """Call this method once you are done modifying the tree information.
+
+        This may be called several times, but be aware that each call will cause a sort
+        operation.
+
+        :return:
+            self
+        """
+        self._cache.sort(key=lambda x: (x[2] + "/") if x[1] == Tree.tree_id << 12 else x[2])
+        return self
+
+    # } END interface
+
+    # { Mutators
+    def add(self, sha: bytes, mode: int, name: str, force: bool = False) -> "TreeModifier":
+        """Add the given item to the tree.
+
+        If an item with the given name already exists, nothing will be done, but a
+        :exc:`ValueError` will be raised if the sha and mode of the existing item do not
+        match the one you add, unless `force` is ``True``.
+
+        :param sha:
+            The 20 or 40 byte sha of the item to add.
+
+        :param mode:
+            :class:`int` representing the stat-compatible mode of the item.
+
+        :param force:
+            If ``True``, an item with your name and information will overwrite any
+            existing item with the same name, no matter which information it has.
+
+        :return:
+            self
+        """
+        if "/" in name:
+            raise ValueError("Name must not contain '/' characters")
+        if (mode >> 12) not in Tree._map_id_to_type:
+            raise ValueError("Invalid object type according to mode %o" % mode)
+
+        sha = to_bin_sha(sha)
+        index = self._index_by_name(name)
+
+        item = (sha, mode, name)
+
+        if index == -1:
+            self._cache.append(item)
+        else:
+            if force:
+                self._cache[index] = item
+            else:
+                ex_item = self._cache[index]
+                if ex_item[0] != sha or ex_item[1] != mode:
+                    raise ValueError("Item %r existed with different properties" % name)
+                # END handle mismatch
+            # END handle force
+        # END handle name exists
+        return self
+
+    def add_unchecked(self, binsha: bytes, mode: int, name: str) -> None:
+        """Add the given item to the tree. Its correctness is assumed, so it is the
+        caller's responsibility to ensure that the input is correct.
+
+        For more information on the parameters, see :meth:`add`.
+
+        :param binsha:
+            20 byte binary sha.
+        """
+        assert isinstance(binsha, bytes) and isinstance(mode, int) and isinstance(name, str)
+        tree_cache = (binsha, mode, name)
+
+        self._cache.append(tree_cache)
+
+    def __delitem__(self, name: str) -> None:
+        """Delete an item with the given name if it exists."""
+        index = self._index_by_name(name)
+        if index > -1:
+            del self._cache[index]
+
+    # } END mutators
+
+
+class Tree(IndexObject, git_diff.Diffable, util.Traversable, util.Serializable):
+    R"""Tree objects represent an ordered list of :class:`~git.objects.blob.Blob`\s and
+    other :class:`Tree`\s.
+
+    See :manpage:`gitglossary(7)` on "tree object":
+    https://git-scm.com/docs/gitglossary#def_tree_object
+
+    Subscripting is supported, as with a list or dict:
+
+    * Access a specific blob using the ``tree["filename"]`` notation.
+    * You may likewise access by index, like ``blob = tree[0]``.
+    """
+
+    type: Literal["tree"] = "tree"
+
+    __slots__ = ("_cache",)
+
+    # Actual integer IDs for comparison.
+    commit_id = 0o16  # Equals stat.S_IFDIR | stat.S_IFLNK - a directory link.
+    blob_id = 0o10
+    symlink_id = 0o12
+    tree_id = 0o04
+
+    _map_id_to_type: Dict[int, Type[IndexObjUnion]] = {
+        commit_id: Submodule,
+        blob_id: Blob,
+        symlink_id: Blob,
+        # Tree ID added once Tree is defined.
+    }
+
+    def __init__(
+        self,
+        repo: "Repo",
+        binsha: bytes,
+        mode: int = tree_id << 12,
+        path: Union[PathLike, None] = None,
+    ):
+        super().__init__(repo, binsha, mode, path)
+
+    @classmethod
+    def _get_intermediate_items(
+        cls,
+        index_object: IndexObjUnion,
+    ) -> Union[Tuple["Tree", ...], Tuple[()]]:
+        if index_object.type == "tree":
+            return tuple(index_object._iter_convert_to_object(index_object._cache))
+        return ()
+
+    def _set_cache_(self, attr: str) -> None:
+        if attr == "_cache":
+            # Set the data when we need it.
+            ostream = self.repo.odb.stream(self.binsha)
+            self._cache: List[TreeCacheTup] = tree_entries_from_data(ostream.read())
+        else:
+            super()._set_cache_(attr)
+        # END handle attribute
+
+    def _iter_convert_to_object(self, iterable: Iterable[TreeCacheTup]) -> Iterator[IndexObjUnion]:
+        """Iterable yields tuples of (binsha, mode, name), which will be converted to
+        the respective object representation.
+        """
+        for binsha, mode, name in iterable:
+            path = join_path(self.path, name)
+            try:
+                yield self._map_id_to_type[mode >> 12](self.repo, binsha, mode, path)
+            except KeyError as e:
+                raise TypeError("Unknown mode %o found in tree data for path '%s'" % (mode, path)) from e
+        # END for each item
+
+    def join(self, file: str) -> IndexObjUnion:
+        """Find the named object in this tree's contents.
+
+        :return:
+            :class:`~git.objects.blob.Blob`, :class:`Tree`, or
+            :class:`~git.objects.submodule.base.Submodule`
+
+        :raise KeyError:
+            If the given file or tree does not exist in this tree.
+        """
+        msg = "Blob or Tree named %r not found"
+        if "/" in file:
+            tree = self
+            item = self
+            tokens = file.split("/")
+            for i, token in enumerate(tokens):
+                item = tree[token]
+                if item.type == "tree":
+                    tree = item
+                else:
+                    # Safety assertion - blobs are at the end of the path.
+                    if i != len(tokens) - 1:
+                        raise KeyError(msg % file)
+                    return item
+                # END handle item type
+            # END for each token of split path
+            if item == self:
+                raise KeyError(msg % file)
+            return item
+        else:
+            for info in self._cache:
+                if info[2] == file:  # [2] == name
+                    return self._map_id_to_type[info[1] >> 12](
+                        self.repo, info[0], info[1], join_path(self.path, info[2])
+                    )
+            # END for each obj
+            raise KeyError(msg % file)
+        # END handle long paths
+
+    def __truediv__(self, file: str) -> IndexObjUnion:
+        """The ``/`` operator is another syntax for joining.
+
+        See :meth:`join` for details.
+        """
+        return self.join(file)
+
+    @property
+    def trees(self) -> List["Tree"]:
+        """:return: list(Tree, ...) List of trees directly below this tree"""
+        return [i for i in self if i.type == "tree"]
+
+    @property
+    def blobs(self) -> List[Blob]:
+        """:return: list(Blob, ...) List of blobs directly below this tree"""
+        return [i for i in self if i.type == "blob"]
+
+    @property
+    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.
+
+        :note:
+            See :class:`TreeModifier` for more information on how to alter the cache.
+        """
+        return TreeModifier(self._cache)
+
+    def traverse(
+        self,
+        predicate: Callable[[Union[IndexObjUnion, TraversedTreeTup], int], bool] = lambda i, d: True,
+        prune: Callable[[Union[IndexObjUnion, TraversedTreeTup], int], bool] = lambda i, d: False,
+        depth: int = -1,
+        branch_first: bool = True,
+        visit_once: bool = False,
+        ignore_self: int = 1,
+        as_edge: bool = False,
+    ) -> Union[Iterator[IndexObjUnion], Iterator[TraversedTreeTup]]:
+        """For documentation, see
+        `Traversable._traverse() <git.objects.util.Traversable._traverse>`.
+
+        Trees are set to ``visit_once = False`` to gain more performance in the
+        traversal.
+        """
+
+        # # To typecheck instead of using cast.
+        # import itertools
+        # def is_tree_traversed(inp: Tuple) -> TypeGuard[Tuple[Iterator[Union['Tree', 'Blob', 'Submodule']]]]:
+        #     return all(isinstance(x, (Blob, Tree, Submodule)) for x in inp[1])
+
+        # ret = super().traverse(predicate, prune, depth, branch_first, visit_once, ignore_self)
+        # ret_tup = itertools.tee(ret, 2)
+        # assert is_tree_traversed(ret_tup), f"Type is {[type(x) for x in list(ret_tup[0])]}"
+        # return ret_tup[0]
+
+        return cast(
+            Union[Iterator[IndexObjUnion], Iterator[TraversedTreeTup]],
+            super()._traverse(
+                predicate,  # type: ignore[arg-type]
+                prune,  # type: ignore[arg-type]
+                depth,
+                branch_first,
+                visit_once,
+                ignore_self,
+            ),
+        )
+
+    def list_traverse(self, *args: Any, **kwargs: Any) -> IterableList[IndexObjUnion]:
+        """
+        :return:
+            :class:`~git.util.IterableList` with the results of the traversal as
+            produced by :meth:`traverse`
+
+            Tree -> IterableList[Union[Submodule, Tree, Blob]]
+        """
+        return super()._list_traverse(*args, **kwargs)
+
+    # List protocol
+
+    def __getslice__(self, i: int, j: int) -> List[IndexObjUnion]:
+        return list(self._iter_convert_to_object(self._cache[i:j]))
+
+    def __iter__(self) -> Iterator[IndexObjUnion]:
+        return self._iter_convert_to_object(self._cache)
+
+    def __len__(self) -> int:
+        return len(self._cache)
+
+    def __getitem__(self, item: Union[str, int, slice]) -> IndexObjUnion:
+        if isinstance(item, int):
+            info = self._cache[item]
+            return self._map_id_to_type[info[1] >> 12](self.repo, info[0], info[1], join_path(self.path, info[2]))
+
+        if isinstance(item, str):
+            # compatibility
+            return self.join(item)
+        # END index is basestring
+
+        raise TypeError("Invalid index type: %r" % item)
+
+    def __contains__(self, item: Union[IndexObjUnion, PathLike]) -> bool:
+        if isinstance(item, IndexObject):
+            for info in self._cache:
+                if item.binsha == info[0]:
+                    return True
+                # END compare sha
+            # END for each entry
+        # END handle item is index object
+        # compatibility
+
+        # Treat item as repo-relative path.
+        else:
+            path = self.path
+            for info in self._cache:
+                if item == join_path(path, info[2]):
+                    return True
+        # END for each item
+        return False
+
+    def __reversed__(self) -> Iterator[IndexObjUnion]:
+        return reversed(self._iter_convert_to_object(self._cache))  # type: ignore[call-overload]
+
+    def _serialize(self, stream: "BytesIO") -> "Tree":
+        """Serialize this tree into the stream. Assumes sorted tree data.
+
+        :note:
+            We will assume our tree data to be in a sorted state. If this is not the
+            case, serialization will not generate a correct tree representation as these
+            are assumed to be sorted by algorithms.
+        """
+        tree_to_stream(self._cache, stream.write)
+        return self
+
+    def _deserialize(self, stream: "BytesIO") -> "Tree":
+        self._cache = tree_entries_from_data(stream.read())
+        return self
+
+
+# END tree
+
+# Finalize map definition.
+Tree._map_id_to_type[Tree.tree_id] = Tree

.venv/lib/python3.11/site-packages/git/objects/util.py

@@ -0,0 +1,700 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Utility functions for working with git objects."""
+
+__all__ = [
+    "get_object_type_by_name",
+    "parse_date",
+    "parse_actor_and_date",
+    "ProcessStreamAdapter",
+    "Traversable",
+    "altz_to_utctz_str",
+    "utctz_to_altz",
+    "verify_utctz",
+    "Actor",
+    "tzoffset",
+    "utc",
+]
+
+from abc import ABC, abstractmethod
+import calendar
+from collections import deque
+from datetime import datetime, timedelta, tzinfo
+import re
+from string import digits
+import time
+import warnings
+
+from git.util import Actor, IterableList, IterableObj
+
+# typing ------------------------------------------------------------
+
+from typing import (
+    Any,
+    Callable,
+    Deque,
+    Iterator,
+    NamedTuple,
+    Sequence,
+    TYPE_CHECKING,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+    cast,
+    overload,
+)
+
+from git.types import Has_id_attribute, Literal
+
+if TYPE_CHECKING:
+    from io import BytesIO, StringIO
+    from subprocess import Popen
+
+    from git.types import Protocol, runtime_checkable
+
+    from .blob import Blob
+    from .commit import Commit
+    from .submodule.base import Submodule
+    from .tag import TagObject
+    from .tree import TraversedTreeTup, Tree
+else:
+    Protocol = ABC
+
+    def runtime_checkable(f):
+        return f
+
+
+class TraverseNT(NamedTuple):
+    depth: int
+    item: Union["Traversable", "Blob"]
+    src: Union["Traversable", None]
+
+
+T_TIobj = TypeVar("T_TIobj", bound="TraversableIterableObj")  # For TraversableIterableObj.traverse()
+
+TraversedTup = Union[
+    Tuple[Union["Traversable", None], "Traversable"],  # For Commit, Submodule.
+    "TraversedTreeTup",  # For Tree.traverse().
+]
+
+# --------------------------------------------------------------------
+
+ZERO = timedelta(0)
+
+# { Functions
+
+
+def mode_str_to_int(modestr: Union[bytes, str]) -> int:
+    """Convert mode bits from an octal mode string to an integer mode for git.
+
+    :param modestr:
+        String like ``755`` or ``644`` or ``100644`` - only the last 6 chars will be
+        used.
+
+    :return:
+        String identifying a mode compatible to the mode methods ids of the :mod:`stat`
+        module regarding the rwx permissions for user, group and other, special flags
+        and file system flags, such as whether it is a symlink.
+    """
+    mode = 0
+    for iteration, char in enumerate(reversed(modestr[-6:])):
+        char = cast(Union[str, int], char)
+        mode += int(char) << iteration * 3
+    # END for each char
+    return mode
+
+
+def get_object_type_by_name(
+    object_type_name: bytes,
+) -> Union[Type["Commit"], Type["TagObject"], Type["Tree"], Type["Blob"]]:
+    """Retrieve the Python class GitPython uses to represent a kind of Git object.
+
+    :return:
+        A type suitable to handle the given as `object_type_name`.
+        This type can be called create new instances.
+
+    :param object_type_name:
+        Member of :attr:`Object.TYPES <git.objects.base.Object.TYPES>`.
+
+    :raise ValueError:
+        If `object_type_name` is unknown.
+    """
+    if object_type_name == b"commit":
+        from . import commit
+
+        return commit.Commit
+    elif object_type_name == b"tag":
+        from . import tag
+
+        return tag.TagObject
+    elif object_type_name == b"blob":
+        from . import blob
+
+        return blob.Blob
+    elif object_type_name == b"tree":
+        from . import tree
+
+        return tree.Tree
+    else:
+        raise ValueError("Cannot handle unknown object type: %s" % object_type_name.decode())
+
+
+def utctz_to_altz(utctz: str) -> int:
+    """Convert a git timezone offset into a timezone offset west of UTC in seconds
+    (compatible with :attr:`time.altzone`).
+
+    :param utctz:
+        git utc timezone string, e.g. +0200
+    """
+    int_utctz = int(utctz)
+    seconds = (abs(int_utctz) // 100) * 3600 + (abs(int_utctz) % 100) * 60
+    return seconds if int_utctz < 0 else -seconds
+
+
+def altz_to_utctz_str(altz: float) -> str:
+    """Convert a timezone offset west of UTC in seconds into a Git timezone offset
+    string.
+
+    :param altz:
+        Timezone offset in seconds west of UTC.
+    """
+    hours = abs(altz) // 3600
+    minutes = (abs(altz) % 3600) // 60
+    sign = "-" if altz >= 60 else "+"
+    return "{}{:02}{:02}".format(sign, hours, minutes)
+
+
+def verify_utctz(offset: str) -> str:
+    """
+    :raise ValueError:
+        If `offset` is incorrect.
+
+    :return:
+        `offset`
+    """
+    fmt_exc = ValueError("Invalid timezone offset format: %s" % offset)
+    if len(offset) != 5:
+        raise fmt_exc
+    if offset[0] not in "+-":
+        raise fmt_exc
+    if offset[1] not in digits or offset[2] not in digits or offset[3] not in digits or offset[4] not in digits:
+        raise fmt_exc
+    # END for each char
+    return offset
+
+
+class tzoffset(tzinfo):
+    def __init__(self, secs_west_of_utc: float, name: Union[None, str] = None) -> None:
+        self._offset = timedelta(seconds=-secs_west_of_utc)
+        self._name = name or "fixed"
+
+    def __reduce__(self) -> Tuple[Type["tzoffset"], Tuple[float, str]]:
+        return tzoffset, (-self._offset.total_seconds(), self._name)
+
+    def utcoffset(self, dt: Union[datetime, None]) -> timedelta:
+        return self._offset
+
+    def tzname(self, dt: Union[datetime, None]) -> str:
+        return self._name
+
+    def dst(self, dt: Union[datetime, None]) -> timedelta:
+        return ZERO
+
+
+utc = tzoffset(0, "UTC")
+
+
+def from_timestamp(timestamp: float, tz_offset: float) -> datetime:
+    """Convert a `timestamp` + `tz_offset` into an aware :class:`~datetime.datetime`
+    instance."""
+    utc_dt = datetime.fromtimestamp(timestamp, utc)
+    try:
+        local_dt = utc_dt.astimezone(tzoffset(tz_offset))
+        return local_dt
+    except ValueError:
+        return utc_dt
+
+
+def parse_date(string_date: Union[str, datetime]) -> Tuple[int, int]:
+    """Parse the given date as one of the following:
+
+        * Aware datetime instance
+        * Git internal format: timestamp offset
+        * :rfc:`2822`: ``Thu, 07 Apr 2005 22:13:13 +0200``
+        * ISO 8601: ``2005-04-07T22:13:13`` - The ``T`` can be a space as well.
+
+    :return:
+        Tuple(int(timestamp_UTC), int(offset)), both in seconds since epoch
+
+    :raise ValueError:
+        If the format could not be understood.
+
+    :note:
+        Date can also be ``YYYY.MM.DD``, ``MM/DD/YYYY`` and ``DD.MM.YYYY``.
+    """
+    if isinstance(string_date, datetime):
+        if string_date.tzinfo:
+            utcoffset = cast(timedelta, string_date.utcoffset())  # typeguard, if tzinfoand is not None
+            offset = -int(utcoffset.total_seconds())
+            return int(string_date.astimezone(utc).timestamp()), offset
+        else:
+            raise ValueError(f"string_date datetime object without tzinfo, {string_date}")
+
+    # Git time
+    try:
+        if string_date.count(" ") == 1 and string_date.rfind(":") == -1:
+            timestamp, offset_str = string_date.split()
+            if timestamp.startswith("@"):
+                timestamp = timestamp[1:]
+            timestamp_int = int(timestamp)
+            return timestamp_int, utctz_to_altz(verify_utctz(offset_str))
+        else:
+            offset_str = "+0000"  # Local time by default.
+            if string_date[-5] in "-+":
+                offset_str = verify_utctz(string_date[-5:])
+                string_date = string_date[:-6]  # skip space as well
+            # END split timezone info
+            offset = utctz_to_altz(offset_str)
+
+            # Now figure out the date and time portion - split time.
+            date_formats = []
+            splitter = -1
+            if "," in string_date:
+                date_formats.append("%a, %d %b %Y")
+                splitter = string_date.rfind(" ")
+            else:
+                # ISO plus additional
+                date_formats.append("%Y-%m-%d")
+                date_formats.append("%Y.%m.%d")
+                date_formats.append("%m/%d/%Y")
+                date_formats.append("%d.%m.%Y")
+
+                splitter = string_date.rfind("T")
+                if splitter == -1:
+                    splitter = string_date.rfind(" ")
+                # END handle 'T' and ' '
+            # END handle RFC or ISO
+
+            assert splitter > -1
+
+            # Split date and time.
+            time_part = string_date[splitter + 1 :]  # Skip space.
+            date_part = string_date[:splitter]
+
+            # Parse time.
+            tstruct = time.strptime(time_part, "%H:%M:%S")
+
+            for fmt in date_formats:
+                try:
+                    dtstruct = time.strptime(date_part, fmt)
+                    utctime = calendar.timegm(
+                        (
+                            dtstruct.tm_year,
+                            dtstruct.tm_mon,
+                            dtstruct.tm_mday,
+                            tstruct.tm_hour,
+                            tstruct.tm_min,
+                            tstruct.tm_sec,
+                            dtstruct.tm_wday,
+                            dtstruct.tm_yday,
+                            tstruct.tm_isdst,
+                        )
+                    )
+                    return int(utctime), offset
+                except ValueError:
+                    continue
+                # END exception handling
+            # END for each fmt
+
+            # Still here ? fail.
+            raise ValueError("no format matched")
+        # END handle format
+    except Exception as e:
+        raise ValueError(f"Unsupported date format or type: {string_date}, type={type(string_date)}") from e
+    # END handle exceptions
+
+
+# Precompiled regexes
+_re_actor_epoch = re.compile(r"^.+? (.*) (\d+) ([+-]\d+).*$")
+_re_only_actor = re.compile(r"^.+? (.*)$")
+
+
+def parse_actor_and_date(line: str) -> Tuple[Actor, int, int]:
+    """Parse out the actor (author or committer) info from a line like::
+
+        author Tom Preston-Werner <tom@mojombo.com> 1191999972 -0700
+
+    :return:
+        [Actor, int_seconds_since_epoch, int_timezone_offset]
+    """
+    actor, epoch, offset = "", "0", "0"
+    m = _re_actor_epoch.search(line)
+    if m:
+        actor, epoch, offset = m.groups()
+    else:
+        m = _re_only_actor.search(line)
+        actor = m.group(1) if m else line or ""
+    return (Actor._from_string(actor), int(epoch), utctz_to_altz(offset))
+
+
+# } END functions
+
+
+# { Classes
+
+
+class ProcessStreamAdapter:
+    """Class wiring all calls to the contained Process instance.
+
+    Use this type to hide the underlying process to provide access only to a specified
+    stream. The process is usually wrapped into an :class:`~git.cmd.Git.AutoInterrupt`
+    class to kill it if the instance goes out of scope.
+    """
+
+    __slots__ = ("_proc", "_stream")
+
+    def __init__(self, process: "Popen", stream_name: str) -> None:
+        self._proc = process
+        self._stream: StringIO = getattr(process, stream_name)  # guessed type
+
+    def __getattr__(self, attr: str) -> Any:
+        return getattr(self._stream, attr)
+
+
+@runtime_checkable
+class Traversable(Protocol):
+    """Simple interface to perform depth-first or breadth-first traversals in one
+    direction.
+
+    Subclasses only need to implement one function.
+
+    Instances of the subclass must be hashable.
+
+    Defined subclasses:
+
+    * :class:`Commit <git.objects.Commit>`
+    * :class:`Tree <git.objects.tree.Tree>`
+    * :class:`Submodule <git.objects.submodule.base.Submodule>`
+    """
+
+    __slots__ = ()
+
+    @classmethod
+    @abstractmethod
+    def _get_intermediate_items(cls, item: Any) -> Sequence["Traversable"]:
+        """
+        :return:
+            Tuple of items connected to the given item.
+            Must be implemented in subclass.
+
+        class Commit::     (cls, Commit) -> Tuple[Commit, ...]
+        class Submodule::  (cls, Submodule) -> Iterablelist[Submodule]
+        class Tree::       (cls, Tree) -> Tuple[Tree, ...]
+        """
+        raise NotImplementedError("To be implemented in subclass")
+
+    @abstractmethod
+    def list_traverse(self, *args: Any, **kwargs: Any) -> Any:
+        """Traverse self and collect all items found.
+
+        Calling this directly on the abstract base class, including via a ``super()``
+        proxy, is deprecated. Only overridden implementations should be called.
+        """
+        warnings.warn(
+            "list_traverse() method should only be called from subclasses."
+            " Calling from Traversable abstract class will raise NotImplementedError in 4.0.0."
+            " The concrete subclasses in GitPython itself are 'Commit', 'RootModule', 'Submodule', and 'Tree'.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self._list_traverse(*args, **kwargs)
+
+    def _list_traverse(
+        self, as_edge: bool = False, *args: Any, **kwargs: Any
+    ) -> IterableList[Union["Commit", "Submodule", "Tree", "Blob"]]:
+        """Traverse self and collect all items found.
+
+        :return:
+            :class:`~git.util.IterableList` with the results of the traversal as
+            produced by :meth:`traverse`::
+
+                Commit -> IterableList[Commit]
+                Submodule ->  IterableList[Submodule]
+                Tree -> IterableList[Union[Submodule, Tree, Blob]]
+        """
+        # Commit and Submodule have id.__attribute__ as IterableObj.
+        # Tree has id.__attribute__ inherited from IndexObject.
+        if isinstance(self, Has_id_attribute):
+            id = self._id_attribute_
+        else:
+            # Shouldn't reach here, unless Traversable subclass created with no
+            # _id_attribute_.
+            id = ""
+            # Could add _id_attribute_ to Traversable, or make all Traversable also
+            # Iterable?
+
+        if not as_edge:
+            out: IterableList[Union["Commit", "Submodule", "Tree", "Blob"]] = IterableList(id)
+            out.extend(self.traverse(as_edge=as_edge, *args, **kwargs))  # noqa: B026
+            return out
+            # Overloads in subclasses (mypy doesn't allow typing self: subclass).
+            # Union[IterableList['Commit'], IterableList['Submodule'], IterableList[Union['Submodule', 'Tree', 'Blob']]]
+        else:
+            # Raise DeprecationWarning, it doesn't make sense to use this.
+            out_list: IterableList = IterableList(self.traverse(*args, **kwargs))
+            return out_list
+
+    @abstractmethod
+    def traverse(self, *args: Any, **kwargs: Any) -> Any:
+        """Iterator yielding items found when traversing self.
+
+        Calling this directly on the abstract base class, including via a ``super()``
+        proxy, is deprecated. Only overridden implementations should be called.
+        """
+        warnings.warn(
+            "traverse() method should only be called from subclasses."
+            " Calling from Traversable abstract class will raise NotImplementedError in 4.0.0."
+            " The concrete subclasses in GitPython itself are 'Commit', 'RootModule', 'Submodule', and 'Tree'.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self._traverse(*args, **kwargs)
+
+    def _traverse(
+        self,
+        predicate: Callable[[Union["Traversable", "Blob", TraversedTup], int], bool] = lambda i, d: True,
+        prune: Callable[[Union["Traversable", "Blob", TraversedTup], int], bool] = lambda i, d: False,
+        depth: int = -1,
+        branch_first: bool = True,
+        visit_once: bool = True,
+        ignore_self: int = 1,
+        as_edge: bool = False,
+    ) -> Union[Iterator[Union["Traversable", "Blob"]], Iterator[TraversedTup]]:
+        """Iterator yielding items found when traversing `self`.
+
+        :param predicate:
+            A function ``f(i,d)`` that returns ``False`` if item i at depth ``d`` should
+            not be included in the result.
+
+        :param prune:
+            A function ``f(i,d)`` that returns ``True`` if the search should stop at
+            item ``i`` at depth ``d``. Item ``i`` will not be returned.
+
+        :param depth:
+            Defines at which level the iteration should not go deeper if -1. There is no
+            limit if 0, you would effectively only get `self`, the root of the
+            iteration. If 1, you would only get the first level of
+            predecessors/successors.
+
+        :param branch_first:
+            If ``True``, items will be returned branch first, otherwise depth first.
+
+        :param visit_once:
+            If ``True``, items will only be returned once, although they might be
+            encountered several times. Loops are prevented that way.
+
+        :param ignore_self:
+            If ``True``, `self` will be ignored and automatically pruned from the
+            result. Otherwise it will be the first item to be returned. If `as_edge` is
+            ``True``, the source of the first edge is ``None``.
+
+        :param as_edge:
+            If ``True``, return a pair of items, first being the source, second the
+            destination, i.e. tuple(src, dest) with the edge spanning from source to
+            destination.
+
+        :return:
+            Iterator yielding items found when traversing `self`::
+
+                Commit -> Iterator[Union[Commit, Tuple[Commit, Commit]] Submodule ->
+                Iterator[Submodule, Tuple[Submodule, Submodule]] Tree ->
+                Iterator[Union[Blob, Tree, Submodule,
+                                        Tuple[Union[Submodule, Tree], Union[Blob, Tree,
+                                        Submodule]]]
+
+                ignore_self=True is_edge=True -> Iterator[item] ignore_self=True
+                is_edge=False --> Iterator[item] ignore_self=False is_edge=True ->
+                Iterator[item] | Iterator[Tuple[src, item]] ignore_self=False
+                is_edge=False -> Iterator[Tuple[src, item]]
+        """
+
+        visited = set()
+        stack: Deque[TraverseNT] = deque()
+        stack.append(TraverseNT(0, self, None))  # self is always depth level 0.
+
+        def addToStack(
+            stack: Deque[TraverseNT],
+            src_item: "Traversable",
+            branch_first: bool,
+            depth: int,
+        ) -> None:
+            lst = self._get_intermediate_items(item)
+            if not lst:  # Empty list
+                return
+            if branch_first:
+                stack.extendleft(TraverseNT(depth, i, src_item) for i in lst)
+            else:
+                reviter = (TraverseNT(depth, lst[i], src_item) for i in range(len(lst) - 1, -1, -1))
+                stack.extend(reviter)
+
+        # END addToStack local method
+
+        while stack:
+            d, item, src = stack.pop()  # Depth of item, item, item_source
+
+            if visit_once and item in visited:
+                continue
+
+            if visit_once:
+                visited.add(item)
+
+            rval: Union[TraversedTup, "Traversable", "Blob"]
+            if as_edge:
+                # If as_edge return (src, item) unless rrc is None
+                # (e.g. for first item).
+                rval = (src, item)
+            else:
+                rval = item
+
+            if prune(rval, d):
+                continue
+
+            skipStartItem = ignore_self and (item is self)
+            if not skipStartItem and predicate(rval, d):
+                yield rval
+
+            # Only continue to next level if this is appropriate!
+            next_d = d + 1
+            if depth > -1 and next_d > depth:
+                continue
+
+            addToStack(stack, item, branch_first, next_d)
+        # END for each item on work stack
+
+
+@runtime_checkable
+class Serializable(Protocol):
+    """Defines methods to serialize and deserialize objects from and into a data
+    stream."""
+
+    __slots__ = ()
+
+    # @abstractmethod
+    def _serialize(self, stream: "BytesIO") -> "Serializable":
+        """Serialize the data of this object into the given data stream.
+
+        :note:
+            A serialized object would :meth:`_deserialize` into the same object.
+
+        :param stream:
+            A file-like object.
+
+        :return:
+            self
+        """
+        raise NotImplementedError("To be implemented in subclass")
+
+    # @abstractmethod
+    def _deserialize(self, stream: "BytesIO") -> "Serializable":
+        """Deserialize all information regarding this object from the stream.
+
+        :param stream:
+            A file-like object.
+
+        :return:
+            self
+        """
+        raise NotImplementedError("To be implemented in subclass")
+
+
+class TraversableIterableObj(IterableObj, Traversable):
+    __slots__ = ()
+
+    TIobj_tuple = Tuple[Union[T_TIobj, None], T_TIobj]
+
+    def list_traverse(self: T_TIobj, *args: Any, **kwargs: Any) -> IterableList[T_TIobj]:
+        return super()._list_traverse(*args, **kwargs)
+
+    @overload
+    def traverse(self: T_TIobj) -> Iterator[T_TIobj]: ...
+
+    @overload
+    def traverse(
+        self: T_TIobj,
+        predicate: Callable[[Union[T_TIobj, Tuple[Union[T_TIobj, None], T_TIobj]], int], bool],
+        prune: Callable[[Union[T_TIobj, Tuple[Union[T_TIobj, None], T_TIobj]], int], bool],
+        depth: int,
+        branch_first: bool,
+        visit_once: bool,
+        ignore_self: Literal[True],
+        as_edge: Literal[False],
+    ) -> Iterator[T_TIobj]: ...
+
+    @overload
+    def traverse(
+        self: T_TIobj,
+        predicate: Callable[[Union[T_TIobj, Tuple[Union[T_TIobj, None], T_TIobj]], int], bool],
+        prune: Callable[[Union[T_TIobj, Tuple[Union[T_TIobj, None], T_TIobj]], int], bool],
+        depth: int,
+        branch_first: bool,
+        visit_once: bool,
+        ignore_self: Literal[False],
+        as_edge: Literal[True],
+    ) -> Iterator[Tuple[Union[T_TIobj, None], T_TIobj]]: ...
+
+    @overload
+    def traverse(
+        self: T_TIobj,
+        predicate: Callable[[Union[T_TIobj, TIobj_tuple], int], bool],
+        prune: Callable[[Union[T_TIobj, TIobj_tuple], int], bool],
+        depth: int,
+        branch_first: bool,
+        visit_once: bool,
+        ignore_self: Literal[True],
+        as_edge: Literal[True],
+    ) -> Iterator[Tuple[T_TIobj, T_TIobj]]: ...
+
+    def traverse(
+        self: T_TIobj,
+        predicate: Callable[[Union[T_TIobj, TIobj_tuple], int], bool] = lambda i, d: True,
+        prune: Callable[[Union[T_TIobj, TIobj_tuple], int], bool] = lambda i, d: False,
+        depth: int = -1,
+        branch_first: bool = True,
+        visit_once: bool = True,
+        ignore_self: int = 1,
+        as_edge: bool = False,
+    ) -> Union[Iterator[T_TIobj], Iterator[Tuple[T_TIobj, T_TIobj]], Iterator[TIobj_tuple]]:
+        """For documentation, see :meth:`Traversable._traverse`."""
+
+        ## To typecheck instead of using cast:
+        #
+        # import itertools
+        # from git.types import TypeGuard
+        # def is_commit_traversed(inp: Tuple) -> TypeGuard[Tuple[Iterator[Tuple['Commit', 'Commit']]]]:
+        #     for x in inp[1]:
+        #         if not isinstance(x, tuple) and len(x) != 2:
+        #             if all(isinstance(inner, Commit) for inner in x):
+        #                 continue
+        #     return True
+        #
+        # ret = super(Commit, self).traverse(predicate, prune, depth, branch_first, visit_once, ignore_self, as_edge)
+        # ret_tup = itertools.tee(ret, 2)
+        # assert is_commit_traversed(ret_tup), f"{[type(x) for x in list(ret_tup[0])]}"
+        # return ret_tup[0]
+
+        return cast(
+            Union[Iterator[T_TIobj], Iterator[Tuple[Union[None, T_TIobj], T_TIobj]]],
+            super()._traverse(
+                predicate,  # type: ignore[arg-type]
+                prune,  # type: ignore[arg-type]
+                depth,
+                branch_first,
+                visit_once,
+                ignore_self,
+                as_edge,
+            ),
+        )

.venv/lib/python3.11/site-packages/git/refs/__init__.py

@@ -0,0 +1,21 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+__all__ = [
+    "HEAD",
+    "Head",
+    "RefLog",
+    "RefLogEntry",
+    "Reference",
+    "RemoteReference",
+    "SymbolicReference",
+    "Tag",
+    "TagReference",
+]
+
+from .head import HEAD, Head
+from .log import RefLog, RefLogEntry
+from .reference import Reference
+from .remote import RemoteReference
+from .symbolic import SymbolicReference
+from .tag import Tag, TagReference

.venv/lib/python3.11/site-packages/git/refs/head.py

@@ -0,0 +1,304 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Some ref-based objects.
+
+Note the distinction between the :class:`HEAD` and :class:`Head` classes.
+"""
+
+__all__ = ["HEAD", "Head"]
+
+from git.config import GitConfigParser, SectionConstraint
+from git.exc import GitCommandError
+from git.util import join_path
+
+from .reference import Reference
+from .symbolic import SymbolicReference
+
+# typing ---------------------------------------------------
+
+from typing import Any, Sequence, TYPE_CHECKING, Union
+
+from git.types import Commit_ish, PathLike
+
+if TYPE_CHECKING:
+    from git.objects import Commit
+    from git.refs import RemoteReference
+    from git.repo import Repo
+
+# -------------------------------------------------------------------
+
+
+def strip_quotes(string: str) -> str:
+    if string.startswith('"') and string.endswith('"'):
+        return string[1:-1]
+    return string
+
+
+class HEAD(SymbolicReference):
+    """Special case of a :class:`~git.refs.symbolic.SymbolicReference` representing the
+    repository's HEAD reference."""
+
+    _HEAD_NAME = "HEAD"
+    _ORIG_HEAD_NAME = "ORIG_HEAD"
+
+    __slots__ = ()
+
+    # TODO: This can be removed once SymbolicReference.commit has static type hints.
+    commit: "Commit"
+
+    def __init__(self, repo: "Repo", path: PathLike = _HEAD_NAME) -> None:
+        if path != self._HEAD_NAME:
+            raise ValueError("HEAD instance must point to %r, got %r" % (self._HEAD_NAME, path))
+        super().__init__(repo, path)
+
+    def orig_head(self) -> SymbolicReference:
+        """
+        :return:
+            :class:`~git.refs.symbolic.SymbolicReference` pointing at the ORIG_HEAD,
+            which is maintained to contain the previous value of HEAD.
+        """
+        return SymbolicReference(self.repo, self._ORIG_HEAD_NAME)
+
+    def reset(
+        self,
+        commit: Union[Commit_ish, SymbolicReference, str] = "HEAD",
+        index: bool = True,
+        working_tree: bool = False,
+        paths: Union[PathLike, Sequence[PathLike], None] = None,
+        **kwargs: Any,
+    ) -> "HEAD":
+        """Reset our HEAD to the given commit optionally synchronizing the index and
+        working tree. The reference we refer to will be set to commit as well.
+
+        :param commit:
+            :class:`~git.objects.commit.Commit`, :class:`~git.refs.reference.Reference`,
+            or string identifying a revision we should reset HEAD to.
+
+        :param index:
+            If ``True``, the index will be set to match the given commit.
+            Otherwise it will not be touched.
+
+        :param working_tree:
+            If ``True``, the working tree will be forcefully adjusted to match the given
+            commit, possibly overwriting uncommitted changes without warning.
+            If `working_tree` is ``True``, `index` must be ``True`` as well.
+
+        :param paths:
+            Single path or list of paths relative to the git root directory
+            that are to be reset. This allows to partially reset individual files.
+
+        :param kwargs:
+            Additional arguments passed to :manpage:`git-reset(1)`.
+
+        :return:
+            self
+        """
+        mode: Union[str, None]
+        mode = "--soft"
+        if index:
+            mode = "--mixed"
+
+            # Explicit "--mixed" when passing paths is deprecated since git 1.5.4.
+            # See https://github.com/gitpython-developers/GitPython/discussions/1876.
+            if paths:
+                mode = None
+            # END special case
+        # END handle index
+
+        if working_tree:
+            mode = "--hard"
+            if not index:
+                raise ValueError("Cannot reset the working tree if the index is not reset as well")
+
+        # END working tree handling
+
+        try:
+            self.repo.git.reset(mode, commit, "--", paths, **kwargs)
+        except GitCommandError as e:
+            # git nowadays may use 1 as status to indicate there are still unstaged
+            # modifications after the reset.
+            if e.status != 1:
+                raise
+        # END handle exception
+
+        return self
+
+
+class Head(Reference):
+    """A Head is a named reference to a :class:`~git.objects.commit.Commit`. Every Head
+    instance contains a name and a :class:`~git.objects.commit.Commit` object.
+
+    Examples::
+
+        >>> repo = Repo("/path/to/repo")
+        >>> head = repo.heads[0]
+
+        >>> head.name
+        'master'
+
+        >>> head.commit
+        <git.Commit "1c09f116cbc2cb4100fb6935bb162daa4723f455">
+
+        >>> head.commit.hexsha
+        '1c09f116cbc2cb4100fb6935bb162daa4723f455'
+    """
+
+    _common_path_default = "refs/heads"
+    k_config_remote = "remote"
+    k_config_remote_ref = "merge"  # Branch to merge from remote.
+
+    @classmethod
+    def delete(cls, repo: "Repo", *heads: "Union[Head, str]", force: bool = False, **kwargs: Any) -> None:
+        """Delete the given heads.
+
+        :param force:
+            If ``True``, the heads will be deleted even if they are not yet merged into
+            the main development stream. Default ``False``.
+        """
+        flag = "-d"
+        if force:
+            flag = "-D"
+        repo.git.branch(flag, *heads)
+
+    def set_tracking_branch(self, remote_reference: Union["RemoteReference", None]) -> "Head":
+        """Configure this branch to track the given remote reference. This will
+        alter this branch's configuration accordingly.
+
+        :param remote_reference:
+            The remote reference to track or None to untrack any references.
+
+        :return:
+            self
+        """
+        from .remote import RemoteReference
+
+        if remote_reference is not None and not isinstance(remote_reference, RemoteReference):
+            raise ValueError("Incorrect parameter type: %r" % remote_reference)
+        # END handle type
+
+        with self.config_writer() as writer:
+            if remote_reference is None:
+                writer.remove_option(self.k_config_remote)
+                writer.remove_option(self.k_config_remote_ref)
+                if len(writer.options()) == 0:
+                    writer.remove_section()
+            else:
+                writer.set_value(self.k_config_remote, remote_reference.remote_name)
+                writer.set_value(
+                    self.k_config_remote_ref,
+                    Head.to_full_path(remote_reference.remote_head),
+                )
+
+        return self
+
+    def tracking_branch(self) -> Union["RemoteReference", None]:
+        """
+        :return:
+            The remote reference we are tracking, or ``None`` if we are not a tracking
+            branch.
+        """
+        from .remote import RemoteReference
+
+        reader = self.config_reader()
+        if reader.has_option(self.k_config_remote) and reader.has_option(self.k_config_remote_ref):
+            ref = Head(
+                self.repo,
+                Head.to_full_path(strip_quotes(reader.get_value(self.k_config_remote_ref))),
+            )
+            remote_refpath = RemoteReference.to_full_path(join_path(reader.get_value(self.k_config_remote), ref.name))
+            return RemoteReference(self.repo, remote_refpath)
+        # END handle have tracking branch
+
+        # We are not a tracking branch.
+        return None
+
+    def rename(self, new_path: PathLike, force: bool = False) -> "Head":
+        """Rename self to a new path.
+
+        :param new_path:
+            Either a simple name or a path, e.g. ``new_name`` or ``features/new_name``.
+            The prefix ``refs/heads`` is implied.
+
+        :param force:
+            If ``True``, the rename will succeed even if a head with the target name
+            already exists.
+
+        :return:
+            self
+
+        :note:
+            Respects the ref log, as git commands are used.
+        """
+        flag = "-m"
+        if force:
+            flag = "-M"
+
+        self.repo.git.branch(flag, self, new_path)
+        self.path = "%s/%s" % (self._common_path_default, new_path)
+        return self
+
+    def checkout(self, force: bool = False, **kwargs: Any) -> Union["HEAD", "Head"]:
+        """Check out this head by setting the HEAD to this reference, by updating the
+        index to reflect the tree we point to and by updating the working tree to
+        reflect the latest index.
+
+        The command will fail if changed working tree files would be overwritten.
+
+        :param force:
+            If ``True``, changes to the index and the working tree will be discarded.
+            If ``False``, :exc:`~git.exc.GitCommandError` will be raised in that
+            situation.
+
+        :param kwargs:
+            Additional keyword arguments to be passed to git checkout, e.g.
+            ``b="new_branch"`` to create a new branch at the given spot.
+
+        :return:
+            The active branch after the checkout operation, usually self unless a new
+            branch has been created.
+            If there is no active branch, as the HEAD is now detached, the HEAD
+            reference will be returned instead.
+
+        :note:
+            By default it is only allowed to checkout heads - everything else will leave
+            the HEAD detached which is allowed and possible, but remains a special state
+            that some tools might not be able to handle.
+        """
+        kwargs["f"] = force
+        if kwargs["f"] is False:
+            kwargs.pop("f")
+
+        self.repo.git.checkout(self, **kwargs)
+        if self.repo.head.is_detached:
+            return self.repo.head
+        else:
+            return self.repo.active_branch
+
+    # { Configuration
+    def _config_parser(self, read_only: bool) -> SectionConstraint[GitConfigParser]:
+        if read_only:
+            parser = self.repo.config_reader()
+        else:
+            parser = self.repo.config_writer()
+        # END handle parser instance
+
+        return SectionConstraint(parser, 'branch "%s"' % self.name)
+
+    def config_reader(self) -> SectionConstraint[GitConfigParser]:
+        """
+        :return:
+            A configuration parser instance constrained to only read this instance's
+            values.
+        """
+        return self._config_parser(read_only=True)
+
+    def config_writer(self) -> SectionConstraint[GitConfigParser]:
+        """
+        :return:
+            A configuration writer instance with read-and write access to options of
+            this head.
+        """
+        return self._config_parser(read_only=False)
+
+    # } END configuration

.venv/lib/python3.11/site-packages/git/refs/log.py

@@ -0,0 +1,399 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+__all__ = ["RefLog", "RefLogEntry"]
+
+from mmap import mmap
+import os.path as osp
+import re
+import time as _time
+
+from git.compat import defenc
+from git.objects.util import (
+    Serializable,
+    altz_to_utctz_str,
+    parse_date,
+)
+from git.util import (
+    Actor,
+    LockedFD,
+    LockFile,
+    assure_directory_exists,
+    bin_to_hex,
+    file_contents_ro_filepath,
+    to_native_path,
+)
+
+# typing ------------------------------------------------------------------
+
+from typing import Iterator, List, Tuple, TYPE_CHECKING, Union
+
+from git.types import PathLike
+
+if TYPE_CHECKING:
+    from io import BytesIO
+
+    from git.config import GitConfigParser, SectionConstraint
+    from git.refs import SymbolicReference
+
+# ------------------------------------------------------------------------------
+
+
+class RefLogEntry(Tuple[str, str, Actor, Tuple[int, int], str]):
+    """Named tuple allowing easy access to the revlog data fields."""
+
+    _re_hexsha_only = re.compile(r"^[0-9A-Fa-f]{40}$")
+
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        """Representation of ourselves in git reflog format."""
+        return self.format()
+
+    def format(self) -> str:
+        """:return: A string suitable to be placed in a reflog file."""
+        act = self.actor
+        time = self.time
+        return "{} {} {} <{}> {!s} {}\t{}\n".format(
+            self.oldhexsha,
+            self.newhexsha,
+            act.name,
+            act.email,
+            time[0],
+            altz_to_utctz_str(time[1]),
+            self.message,
+        )
+
+    @property
+    def oldhexsha(self) -> str:
+        """The hexsha to the commit the ref pointed to before the change."""
+        return self[0]
+
+    @property
+    def newhexsha(self) -> str:
+        """The hexsha to the commit the ref now points to, after the change."""
+        return self[1]
+
+    @property
+    def actor(self) -> Actor:
+        """Actor instance, providing access."""
+        return self[2]
+
+    @property
+    def time(self) -> Tuple[int, int]:
+        """Time as tuple:
+
+        * [0] = ``int(time)``
+        * [1] = ``int(timezone_offset)`` in :attr:`time.altzone` format
+        """
+        return self[3]
+
+    @property
+    def message(self) -> str:
+        """Message describing the operation that acted on the reference."""
+        return self[4]
+
+    @classmethod
+    def new(
+        cls,
+        oldhexsha: str,
+        newhexsha: str,
+        actor: Actor,
+        time: int,
+        tz_offset: int,
+        message: str,
+    ) -> "RefLogEntry":  # skipcq: PYL-W0621
+        """:return: New instance of a :class:`RefLogEntry`"""
+        if not isinstance(actor, Actor):
+            raise ValueError("Need actor instance, got %s" % actor)
+        # END check types
+        return RefLogEntry((oldhexsha, newhexsha, actor, (time, tz_offset), message))
+
+    @classmethod
+    def from_line(cls, line: bytes) -> "RefLogEntry":
+        """:return: New :class:`RefLogEntry` instance from the given revlog line.
+
+        :param line:
+            Line bytes without trailing newline
+
+        :raise ValueError:
+            If `line` could not be parsed.
+        """
+        line_str = line.decode(defenc)
+        fields = line_str.split("\t", 1)
+        if len(fields) == 1:
+            info, msg = fields[0], None
+        elif len(fields) == 2:
+            info, msg = fields
+        else:
+            raise ValueError("Line must have up to two TAB-separated fields. Got %s" % repr(line_str))
+        # END handle first split
+
+        oldhexsha = info[:40]
+        newhexsha = info[41:81]
+        for hexsha in (oldhexsha, newhexsha):
+            if not cls._re_hexsha_only.match(hexsha):
+                raise ValueError("Invalid hexsha: %r" % (hexsha,))
+            # END if hexsha re doesn't match
+        # END for each hexsha
+
+        email_end = info.find(">", 82)
+        if email_end == -1:
+            raise ValueError("Missing token: >")
+        # END handle missing end brace
+
+        actor = Actor._from_string(info[82 : email_end + 1])
+        time, tz_offset = parse_date(info[email_end + 2 :])  # skipcq: PYL-W0621
+
+        return RefLogEntry((oldhexsha, newhexsha, actor, (time, tz_offset), msg))
+
+
+class RefLog(List[RefLogEntry], Serializable):
+    R"""A reflog contains :class:`RefLogEntry`\s, each of which defines a certain state
+    of the head in question. Custom query methods allow to retrieve log entries by date
+    or by other criteria.
+
+    Reflog entries are ordered. The first added entry is first in the list. The last
+    entry, i.e. the last change of the head or reference, is last in the list.
+    """
+
+    __slots__ = ("_path",)
+
+    def __new__(cls, filepath: Union[PathLike, None] = None) -> "RefLog":
+        inst = super().__new__(cls)
+        return inst
+
+    def __init__(self, filepath: Union[PathLike, None] = None) -> None:
+        """Initialize this instance with an optional filepath, from which we will
+        initialize our data. The path is also used to write changes back using the
+        :meth:`write` method."""
+        self._path = filepath
+        if filepath is not None:
+            self._read_from_file()
+        # END handle filepath
+
+    def _read_from_file(self) -> None:
+        try:
+            fmap = file_contents_ro_filepath(self._path, stream=True, allow_mmap=True)
+        except OSError:
+            # It is possible and allowed that the file doesn't exist!
+            return
+        # END handle invalid log
+
+        try:
+            self._deserialize(fmap)
+        finally:
+            fmap.close()
+        # END handle closing of handle
+
+    # { Interface
+
+    @classmethod
+    def from_file(cls, filepath: PathLike) -> "RefLog":
+        """
+        :return:
+            A new :class:`RefLog` instance containing all entries from the reflog at the
+            given `filepath`.
+
+        :param filepath:
+            Path to reflog.
+
+        :raise ValueError:
+            If the file could not be read or was corrupted in some way.
+        """
+        return cls(filepath)
+
+    @classmethod
+    def path(cls, ref: "SymbolicReference") -> str:
+        """
+        :return:
+            String to absolute path at which the reflog of the given ref instance would
+            be found. The path is not guaranteed to point to a valid file though.
+
+        :param ref:
+            :class:`~git.refs.symbolic.SymbolicReference` instance
+        """
+        return osp.join(ref.repo.git_dir, "logs", to_native_path(ref.path))
+
+    @classmethod
+    def iter_entries(cls, stream: Union[str, "BytesIO", mmap]) -> Iterator[RefLogEntry]:
+        """
+        :return:
+            Iterator yielding :class:`RefLogEntry` instances, one for each line read
+            from the given stream.
+
+        :param stream:
+            File-like object containing the revlog in its native format or string
+            instance pointing to a file to read.
+        """
+        new_entry = RefLogEntry.from_line
+        if isinstance(stream, str):
+            # Default args return mmap since Python 3.
+            _stream = file_contents_ro_filepath(stream)
+            assert isinstance(_stream, mmap)
+        else:
+            _stream = stream
+        # END handle stream type
+        while True:
+            line = _stream.readline()
+            if not line:
+                return
+            yield new_entry(line.strip())
+        # END endless loop
+
+    @classmethod
+    def entry_at(cls, filepath: PathLike, index: int) -> "RefLogEntry":
+        """
+        :return:
+            :class:`RefLogEntry` at the given index.
+
+        :param filepath:
+            Full path to the index file from which to read the entry.
+
+        :param index:
+            Python list compatible index, i.e. it may be negative to specify an entry
+            counted from the end of the list.
+
+        :raise IndexError:
+            If the entry didn't exist.
+
+        :note:
+            This method is faster as it only parses the entry at index, skipping all
+            other lines. Nonetheless, the whole file has to be read if the index is
+            negative.
+        """
+        with open(filepath, "rb") as fp:
+            if index < 0:
+                return RefLogEntry.from_line(fp.readlines()[index].strip())
+            # Read until index is reached.
+
+            for i in range(index + 1):
+                line = fp.readline()
+                if not line:
+                    raise IndexError(f"Index file ended at line {i + 1}, before given index was reached")
+                # END abort on eof
+            # END handle runup
+
+            return RefLogEntry.from_line(line.strip())
+        # END handle index
+
+    def to_file(self, filepath: PathLike) -> None:
+        """Write the contents of the reflog instance to a file at the given filepath.
+
+        :param filepath:
+            Path to file. Parent directories are assumed to exist.
+        """
+        lfd = LockedFD(filepath)
+        assure_directory_exists(filepath, is_file=True)
+
+        fp = lfd.open(write=True, stream=True)
+        try:
+            self._serialize(fp)
+            lfd.commit()
+        except BaseException:
+            lfd.rollback()
+            raise
+        # END handle change
+
+    @classmethod
+    def append_entry(
+        cls,
+        config_reader: Union[Actor, "GitConfigParser", "SectionConstraint", None],
+        filepath: PathLike,
+        oldbinsha: bytes,
+        newbinsha: bytes,
+        message: str,
+        write: bool = True,
+    ) -> "RefLogEntry":
+        """Append a new log entry to the revlog at filepath.
+
+        :param config_reader:
+            Configuration reader of the repository - used to obtain user information.
+            May also be an :class:`~git.util.Actor` instance identifying the committer
+            directly or ``None``.
+
+        :param filepath:
+            Full path to the log file.
+
+        :param oldbinsha:
+            Binary sha of the previous commit.
+
+        :param newbinsha:
+            Binary sha of the current commit.
+
+        :param message:
+            Message describing the change to the reference.
+
+        :param write:
+            If ``True``, the changes will be written right away.
+            Otherwise the change will not be written.
+
+        :return:
+            :class:`RefLogEntry` objects which was appended to the log.
+
+        :note:
+            As we are append-only, concurrent access is not a problem as we do not
+            interfere with readers.
+        """
+
+        if len(oldbinsha) != 20 or len(newbinsha) != 20:
+            raise ValueError("Shas need to be given in binary format")
+        # END handle sha type
+        assure_directory_exists(filepath, is_file=True)
+        first_line = message.split("\n")[0]
+        if isinstance(config_reader, Actor):
+            committer = config_reader  # mypy thinks this is Actor | Gitconfigparser, but why?
+        else:
+            committer = Actor.committer(config_reader)
+        entry = RefLogEntry(
+            (
+                bin_to_hex(oldbinsha).decode("ascii"),
+                bin_to_hex(newbinsha).decode("ascii"),
+                committer,
+                (int(_time.time()), _time.altzone),
+                first_line,
+            )
+        )
+
+        if write:
+            lf = LockFile(filepath)
+            lf._obtain_lock_or_raise()
+            fd = open(filepath, "ab")
+            try:
+                fd.write(entry.format().encode(defenc))
+            finally:
+                fd.close()
+                lf._release_lock()
+            # END handle write operation
+        return entry
+
+    def write(self) -> "RefLog":
+        """Write this instance's data to the file we are originating from.
+
+        :return:
+            self
+        """
+        if self._path is None:
+            raise ValueError("Instance was not initialized with a path, use to_file(...) instead")
+        # END assert path
+        self.to_file(self._path)
+        return self
+
+    # } END interface
+
+    # { Serializable Interface
+
+    def _serialize(self, stream: "BytesIO") -> "RefLog":
+        write = stream.write
+
+        # Write all entries.
+        for e in self:
+            write(e.format().encode(defenc))
+        # END for each entry
+        return self
+
+    def _deserialize(self, stream: "BytesIO") -> "RefLog":
+        self.extend(self.iter_entries(stream))
+        return self
+
+    # } END serializable interface

.venv/lib/python3.11/site-packages/git/refs/reference.py

@@ -0,0 +1,176 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+__all__ = ["Reference"]
+
+from git.util import IterableObj, LazyMixin
+
+from .symbolic import SymbolicReference, T_References
+
+# typing ------------------------------------------------------------------
+
+from typing import Any, Callable, Iterator, TYPE_CHECKING, Type, Union
+
+from git.types import AnyGitObject, PathLike, _T
+
+if TYPE_CHECKING:
+    from git.repo import Repo
+
+# ------------------------------------------------------------------------------
+
+# { Utilities
+
+
+def require_remote_ref_path(func: Callable[..., _T]) -> Callable[..., _T]:
+    """A decorator raising :exc:`ValueError` if we are not a valid remote, based on the
+    path."""
+
+    def wrapper(self: T_References, *args: Any) -> _T:
+        if not self.is_remote():
+            raise ValueError("ref path does not point to a remote reference: %s" % self.path)
+        return func(self, *args)
+
+    # END wrapper
+    wrapper.__name__ = func.__name__
+    return wrapper
+
+
+# } END utilities
+
+
+class Reference(SymbolicReference, LazyMixin, IterableObj):
+    """A named reference to any object.
+
+    Subclasses may apply restrictions though, e.g., a :class:`~git.refs.head.Head` can
+    only point to commits.
+    """
+
+    __slots__ = ()
+
+    _points_to_commits_only = False
+    _resolve_ref_on_create = True
+    _common_path_default = "refs"
+
+    def __init__(self, repo: "Repo", path: PathLike, check_path: bool = True) -> None:
+        """Initialize this instance.
+
+        :param repo:
+            Our parent repository.
+
+        :param path:
+            Path relative to the ``.git/`` directory pointing to the ref in question,
+            e.g. ``refs/heads/master``.
+
+        :param check_path:
+            If ``False``, you can provide any path.
+            Otherwise the path must start with the default path prefix of this type.
+        """
+        if check_path and not str(path).startswith(self._common_path_default + "/"):
+            raise ValueError(f"Cannot instantiate {self.__class__.__name__!r} from path {path}")
+        self.path: str  # SymbolicReference converts to string at the moment.
+        super().__init__(repo, path)
+
+    def __str__(self) -> str:
+        return self.name
+
+    # { Interface
+
+    # @ReservedAssignment
+    def set_object(
+        self,
+        object: Union[AnyGitObject, "SymbolicReference", str],
+        logmsg: Union[str, None] = None,
+    ) -> "Reference":
+        """Special version which checks if the head-log needs an update as well.
+
+        :return:
+            self
+        """
+        oldbinsha = None
+        if logmsg is not None:
+            head = self.repo.head
+            if not head.is_detached and head.ref == self:
+                oldbinsha = self.commit.binsha
+            # END handle commit retrieval
+        # END handle message is set
+
+        super().set_object(object, logmsg)
+
+        if oldbinsha is not None:
+            # From refs/files-backend.c in git-source:
+            # /*
+            #  * Special hack: If a branch is updated directly and HEAD
+            #  * points to it (may happen on the remote side of a push
+            #  * for example) then logically the HEAD reflog should be
+            #  * updated too.
+            #  * A generic solution implies reverse symref information,
+            #  * but finding all symrefs pointing to the given branch
+            #  * would be rather costly for this rare event (the direct
+            #  * update of a branch) to be worth it.  So let's cheat and
+            #  * check with HEAD only which should cover 99% of all usage
+            #  * scenarios (even 100% of the default ones).
+            #  */
+            self.repo.head.log_append(oldbinsha, logmsg)
+        # END check if the head
+
+        return self
+
+    # NOTE: No need to overwrite properties, as the will only work without a the log.
+
+    @property
+    def name(self) -> str:
+        """
+        :return:
+            (shortest) Name of this reference - it may contain path components
+        """
+        # The first two path tokens can be removed as they are
+        # refs/heads or refs/tags or refs/remotes.
+        tokens = self.path.split("/")
+        if len(tokens) < 3:
+            return self.path  # could be refs/HEAD
+        return "/".join(tokens[2:])
+
+    @classmethod
+    def iter_items(
+        cls: Type[T_References],
+        repo: "Repo",
+        common_path: Union[PathLike, None] = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Iterator[T_References]:
+        """Equivalent to
+        :meth:`SymbolicReference.iter_items <git.refs.symbolic.SymbolicReference.iter_items>`,
+        but will return non-detached references as well."""
+        return cls._iter_items(repo, common_path)
+
+    # } END interface
+
+    # { Remote Interface
+
+    @property
+    @require_remote_ref_path
+    def remote_name(self) -> str:
+        """
+        :return:
+            Name of the remote we are a reference of, such as ``origin`` for a reference
+            named ``origin/master``.
+        """
+        tokens = self.path.split("/")
+        # /refs/remotes/<remote name>/<branch_name>
+        return tokens[2]
+
+    @property
+    @require_remote_ref_path
+    def remote_head(self) -> str:
+        """
+        :return:
+            Name of the remote head itself, e.g. ``master``.
+
+        :note:
+            The returned name is usually not qualified enough to uniquely identify a
+            branch.
+        """
+        tokens = self.path.split("/")
+        return "/".join(tokens[3:])
+
+    # } END remote interface

.venv/lib/python3.11/site-packages/git/refs/remote.py

@@ -0,0 +1,79 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Module implementing a remote object allowing easy access to git remotes."""
+
+__all__ = ["RemoteReference"]
+
+import os
+
+from git.util import join_path
+
+from .head import Head
+
+# typing ------------------------------------------------------------------
+
+from typing import Any, Iterator, NoReturn, TYPE_CHECKING, Union
+
+from git.types import PathLike
+
+if TYPE_CHECKING:
+    from git.remote import Remote
+    from git.repo import Repo
+
+# ------------------------------------------------------------------------------
+
+
+class RemoteReference(Head):
+    """A reference pointing to a remote head."""
+
+    _common_path_default = Head._remote_common_path_default
+
+    @classmethod
+    def iter_items(
+        cls,
+        repo: "Repo",
+        common_path: Union[PathLike, None] = None,
+        remote: Union["Remote", None] = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Iterator["RemoteReference"]:
+        """Iterate remote references, and if given, constrain them to the given remote."""
+        common_path = common_path or cls._common_path_default
+        if remote is not None:
+            common_path = join_path(common_path, str(remote))
+        # END handle remote constraint
+        # super is Reference
+        return super().iter_items(repo, common_path)
+
+    # The Head implementation of delete also accepts strs, but this implementation does
+    # not. mypy doesn't have a way of representing tightening the types of arguments in
+    # subclasses and recommends Any or "type: ignore".
+    # (See: https://github.com/python/typing/issues/241)
+    @classmethod
+    def delete(cls, repo: "Repo", *refs: "RemoteReference", **kwargs: Any) -> None:  # type: ignore[override]
+        """Delete the given remote references.
+
+        :note:
+            `kwargs` are given for comparability with the base class method as we
+            should not narrow the signature.
+        """
+        repo.git.branch("-d", "-r", *refs)
+        # The official deletion method will ignore remote symbolic refs - these are
+        # generally ignored in the refs/ folder. We don't though and delete remainders
+        # manually.
+        for ref in refs:
+            try:
+                os.remove(os.path.join(repo.common_dir, ref.path))
+            except OSError:
+                pass
+            try:
+                os.remove(os.path.join(repo.git_dir, ref.path))
+            except OSError:
+                pass
+        # END for each ref
+
+    @classmethod
+    def create(cls, *args: Any, **kwargs: Any) -> NoReturn:
+        """Raise :exc:`TypeError`. Defined so the ``create`` method is disabled."""
+        raise TypeError("Cannot explicitly create remote references")

.venv/lib/python3.11/site-packages/git/refs/symbolic.py

@@ -0,0 +1,933 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+__all__ = ["SymbolicReference"]
+
+import os
+
+from gitdb.exc import BadName, BadObject
+
+from git.compat import defenc
+from git.objects.base import Object
+from git.objects.commit import Commit
+from git.refs.log import RefLog
+from git.util import (
+    LockedFD,
+    assure_directory_exists,
+    hex_to_bin,
+    join_path,
+    join_path_native,
+    to_native_path_linux,
+)
+
+# typing ------------------------------------------------------------------
+
+from typing import (
+    Any,
+    Iterator,
+    List,
+    TYPE_CHECKING,
+    Tuple,
+    Type,
+    TypeVar,
+    Union,
+    cast,
+)
+
+from git.types import AnyGitObject, PathLike
+
+if TYPE_CHECKING:
+    from git.config import GitConfigParser
+    from git.objects.commit import Actor
+    from git.refs.log import RefLogEntry
+    from git.repo import Repo
+
+
+T_References = TypeVar("T_References", bound="SymbolicReference")
+
+# ------------------------------------------------------------------------------
+
+
+def _git_dir(repo: "Repo", path: Union[PathLike, None]) -> PathLike:
+    """Find the git dir that is appropriate for the path."""
+    name = f"{path}"
+    if name in ["HEAD", "ORIG_HEAD", "FETCH_HEAD", "index", "logs"]:
+        return repo.git_dir
+    return repo.common_dir
+
+
+class SymbolicReference:
+    """Special case of a reference that is symbolic.
+
+    This does not point to a specific commit, but to another
+    :class:`~git.refs.head.Head`, which itself specifies a commit.
+
+    A typical example for a symbolic reference is :class:`~git.refs.head.HEAD`.
+    """
+
+    __slots__ = ("repo", "path")
+
+    _resolve_ref_on_create = False
+    _points_to_commits_only = True
+    _common_path_default = ""
+    _remote_common_path_default = "refs/remotes"
+    _id_attribute_ = "name"
+
+    def __init__(self, repo: "Repo", path: PathLike, check_path: bool = False) -> None:
+        self.repo = repo
+        self.path = path
+
+    def __str__(self) -> str:
+        return str(self.path)
+
+    def __repr__(self) -> str:
+        return '<git.%s "%s">' % (self.__class__.__name__, self.path)
+
+    def __eq__(self, other: object) -> bool:
+        if hasattr(other, "path"):
+            other = cast(SymbolicReference, other)
+            return self.path == other.path
+        return False
+
+    def __ne__(self, other: object) -> bool:
+        return not (self == other)
+
+    def __hash__(self) -> int:
+        return hash(self.path)
+
+    @property
+    def name(self) -> str:
+        """
+        :return:
+            In case of symbolic references, the shortest assumable name is the path
+            itself.
+        """
+        return str(self.path)
+
+    @property
+    def abspath(self) -> PathLike:
+        return join_path_native(_git_dir(self.repo, self.path), self.path)
+
+    @classmethod
+    def _get_packed_refs_path(cls, repo: "Repo") -> str:
+        return os.path.join(repo.common_dir, "packed-refs")
+
+    @classmethod
+    def _iter_packed_refs(cls, repo: "Repo") -> Iterator[Tuple[str, str]]:
+        """Return an iterator yielding pairs of sha1/path pairs (as strings) for the
+        corresponding refs.
+
+        :note:
+            The packed refs file will be kept open as long as we iterate.
+        """
+        try:
+            with open(cls._get_packed_refs_path(repo), "rt", encoding="UTF-8") as fp:
+                for line in fp:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    if line.startswith("#"):
+                        # "# pack-refs with: peeled fully-peeled sorted"
+                        # the git source code shows "peeled",
+                        # "fully-peeled" and "sorted" as the keywords
+                        # that can go on this line, as per comments in git file
+                        # refs/packed-backend.c
+                        # I looked at master on 2017-10-11,
+                        # commit 111ef79afe, after tag v2.15.0-rc1
+                        # from repo https://github.com/git/git.git
+                        if line.startswith("# pack-refs with:") and "peeled" not in line:
+                            raise TypeError("PackingType of packed-Refs not understood: %r" % line)
+                        # END abort if we do not understand the packing scheme
+                        continue
+                    # END parse comment
+
+                    # Skip dereferenced tag object entries - previous line was actual
+                    # tag reference for it.
+                    if line[0] == "^":
+                        continue
+
+                    yield cast(Tuple[str, str], tuple(line.split(" ", 1)))
+                # END for each line
+        except OSError:
+            return None
+        # END no packed-refs file handling
+
+    @classmethod
+    def dereference_recursive(cls, repo: "Repo", ref_path: Union[PathLike, None]) -> str:
+        """
+        :return:
+            hexsha stored in the reference at the given `ref_path`, recursively
+            dereferencing all intermediate references as required
+
+        :param repo:
+            The repository containing the reference at `ref_path`.
+        """
+
+        while True:
+            hexsha, ref_path = cls._get_ref_info(repo, ref_path)
+            if hexsha is not None:
+                return hexsha
+        # END recursive dereferencing
+
+    @staticmethod
+    def _check_ref_name_valid(ref_path: PathLike) -> None:
+        """Check a ref name for validity.
+
+        This is based on the rules described in :manpage:`git-check-ref-format(1)`.
+        """
+        previous: Union[str, None] = None
+        one_before_previous: Union[str, None] = None
+        for c in str(ref_path):
+            if c in " ~^:?*[\\":
+                raise ValueError(
+                    f"Invalid reference '{ref_path}': references cannot contain spaces, tildes (~), carets (^),"
+                    f" colons (:), question marks (?), asterisks (*), open brackets ([) or backslashes (\\)"
+                )
+            elif c == ".":
+                if previous is None or previous == "/":
+                    raise ValueError(
+                        f"Invalid reference '{ref_path}': references cannot start with a period (.) or contain '/.'"
+                    )
+                elif previous == ".":
+                    raise ValueError(f"Invalid reference '{ref_path}': references cannot contain '..'")
+            elif c == "/":
+                if previous == "/":
+                    raise ValueError(f"Invalid reference '{ref_path}': references cannot contain '//'")
+                elif previous is None:
+                    raise ValueError(
+                        f"Invalid reference '{ref_path}': references cannot start with forward slashes '/'"
+                    )
+            elif c == "{" and previous == "@":
+                raise ValueError(f"Invalid reference '{ref_path}': references cannot contain '@{{'")
+            elif ord(c) < 32 or ord(c) == 127:
+                raise ValueError(f"Invalid reference '{ref_path}': references cannot contain ASCII control characters")
+
+            one_before_previous = previous
+            previous = c
+
+        if previous == ".":
+            raise ValueError(f"Invalid reference '{ref_path}': references cannot end with a period (.)")
+        elif previous == "/":
+            raise ValueError(f"Invalid reference '{ref_path}': references cannot end with a forward slash (/)")
+        elif previous == "@" and one_before_previous is None:
+            raise ValueError(f"Invalid reference '{ref_path}': references cannot be '@'")
+        elif any(component.endswith(".lock") for component in str(ref_path).split("/")):
+            raise ValueError(
+                f"Invalid reference '{ref_path}': references cannot have slash-separated components that end with"
+                " '.lock'"
+            )
+
+    @classmethod
+    def _get_ref_info_helper(
+        cls, repo: "Repo", ref_path: Union[PathLike, None]
+    ) -> Union[Tuple[str, None], Tuple[None, str]]:
+        """
+        :return:
+            *(str(sha), str(target_ref_path))*, where:
+
+            * *sha* is of the file at rela_path points to if available, or ``None``.
+            * *target_ref_path* is the reference we point to, or ``None``.
+        """
+        if ref_path:
+            cls._check_ref_name_valid(ref_path)
+
+        tokens: Union[None, List[str], Tuple[str, str]] = None
+        repodir = _git_dir(repo, ref_path)
+        try:
+            with open(os.path.join(repodir, str(ref_path)), "rt", encoding="UTF-8") as fp:
+                value = fp.read().rstrip()
+            # Don't only split on spaces, but on whitespace, which allows to parse lines like:
+            # 60b64ef992065e2600bfef6187a97f92398a9144                branch 'master' of git-server:/path/to/repo
+            tokens = value.split()
+            assert len(tokens) != 0
+        except OSError:
+            # Probably we are just packed. Find our entry in the packed refs file.
+            # NOTE: We are not a symbolic ref if we are in a packed file, as these
+            # are excluded explicitly.
+            for sha, path in cls._iter_packed_refs(repo):
+                if path != ref_path:
+                    continue
+                # sha will be used.
+                tokens = sha, path
+                break
+            # END for each packed ref
+        # END handle packed refs
+        if tokens is None:
+            raise ValueError("Reference at %r does not exist" % ref_path)
+
+        # Is it a reference?
+        if tokens[0] == "ref:":
+            return (None, tokens[1])
+
+        # It's a commit.
+        if repo.re_hexsha_only.match(tokens[0]):
+            return (tokens[0], None)
+
+        raise ValueError("Failed to parse reference information from %r" % ref_path)
+
+    @classmethod
+    def _get_ref_info(cls, repo: "Repo", ref_path: Union[PathLike, None]) -> Union[Tuple[str, None], Tuple[None, str]]:
+        """
+        :return:
+            *(str(sha), str(target_ref_path))*, where:
+
+            * *sha* is of the file at rela_path points to if available, or ``None``.
+            * *target_ref_path* is the reference we point to, or ``None``.
+        """
+        return cls._get_ref_info_helper(repo, ref_path)
+
+    def _get_object(self) -> AnyGitObject:
+        """
+        :return:
+            The object our ref currently refers to. Refs can be cached, they will always
+            point to the actual object as it gets re-created on each query.
+        """
+        # We have to be dynamic here as we may be a tag which can point to anything.
+        # Our path will be resolved to the hexsha which will be used accordingly.
+        return Object.new_from_sha(self.repo, hex_to_bin(self.dereference_recursive(self.repo, self.path)))
+
+    def _get_commit(self) -> "Commit":
+        """
+        :return:
+            :class:`~git.objects.commit.Commit` object we point to. This works for
+            detached and non-detached :class:`SymbolicReference` instances. The symbolic
+            reference will be dereferenced recursively.
+        """
+        obj = self._get_object()
+        if obj.type == "tag":
+            obj = obj.object
+        # END dereference tag
+
+        if obj.type != Commit.type:
+            raise TypeError("Symbolic Reference pointed to object %r, commit was required" % obj)
+        # END handle type
+        return obj
+
+    def set_commit(
+        self,
+        commit: Union[Commit, "SymbolicReference", str],
+        logmsg: Union[str, None] = None,
+    ) -> "SymbolicReference":
+        """Like :meth:`set_object`, but restricts the type of object to be a
+        :class:`~git.objects.commit.Commit`.
+
+        :raise ValueError:
+            If `commit` is not a :class:`~git.objects.commit.Commit` object, nor does it
+            point to a commit.
+
+        :return:
+            self
+        """
+        # Check the type - assume the best if it is a base-string.
+        invalid_type = False
+        if isinstance(commit, Object):
+            invalid_type = commit.type != Commit.type
+        elif isinstance(commit, SymbolicReference):
+            invalid_type = commit.object.type != Commit.type
+        else:
+            try:
+                invalid_type = self.repo.rev_parse(commit).type != Commit.type
+            except (BadObject, BadName) as e:
+                raise ValueError("Invalid object: %s" % commit) from e
+            # END handle exception
+        # END verify type
+
+        if invalid_type:
+            raise ValueError("Need commit, got %r" % commit)
+        # END handle raise
+
+        # We leave strings to the rev-parse method below.
+        self.set_object(commit, logmsg)
+
+        return self
+
+    def set_object(
+        self,
+        object: Union[AnyGitObject, "SymbolicReference", str],
+        logmsg: Union[str, None] = None,
+    ) -> "SymbolicReference":
+        """Set the object we point to, possibly dereference our symbolic reference
+        first. If the reference does not exist, it will be created.
+
+        :param object:
+            A refspec, a :class:`SymbolicReference` or an
+            :class:`~git.objects.base.Object` instance.
+
+            * :class:`SymbolicReference` instances will be dereferenced beforehand to
+              obtain the git object they point to.
+            * :class:`~git.objects.base.Object` instances must represent git objects
+              (:class:`~git.types.AnyGitObject`).
+
+        :param logmsg:
+            If not ``None``, the message will be used in the reflog entry to be written.
+            Otherwise the reflog is not altered.
+
+        :note:
+            Plain :class:`SymbolicReference` instances may not actually point to objects
+            by convention.
+
+        :return:
+            self
+        """
+        if isinstance(object, SymbolicReference):
+            object = object.object  # @ReservedAssignment
+        # END resolve references
+
+        is_detached = True
+        try:
+            is_detached = self.is_detached
+        except ValueError:
+            pass
+        # END handle non-existing ones
+
+        if is_detached:
+            return self.set_reference(object, logmsg)
+
+        # set the commit on our reference
+        return self._get_reference().set_object(object, logmsg)
+
+    @property
+    def commit(self) -> "Commit":
+        """Query or set commits directly"""
+        return self._get_commit()
+
+    @commit.setter
+    def commit(self, commit: Union[Commit, "SymbolicReference", str]) -> "SymbolicReference":
+        return self.set_commit(commit)
+
+    @property
+    def object(self) -> AnyGitObject:
+        """Return the object our ref currently refers to"""
+        return self._get_object()
+
+    @object.setter
+    def object(self, object: Union[AnyGitObject, "SymbolicReference", str]) -> "SymbolicReference":
+        return self.set_object(object)
+
+    def _get_reference(self) -> "SymbolicReference":
+        """
+        :return:
+            :class:`~git.refs.reference.Reference` object we point to
+
+        :raise TypeError:
+            If this symbolic reference is detached, hence it doesn't point to a
+            reference, but to a commit.
+        """
+        sha, target_ref_path = self._get_ref_info(self.repo, self.path)
+        if target_ref_path is None:
+            raise TypeError("%s is a detached symbolic reference as it points to %r" % (self, sha))
+        return self.from_path(self.repo, target_ref_path)
+
+    def set_reference(
+        self,
+        ref: Union[AnyGitObject, "SymbolicReference", str],
+        logmsg: Union[str, None] = None,
+    ) -> "SymbolicReference":
+        """Set ourselves to the given `ref`.
+
+        It will stay a symbol if the `ref` is a :class:`~git.refs.reference.Reference`.
+
+        Otherwise a git object, specified as a :class:`~git.objects.base.Object`
+        instance or refspec, is assumed. If it is valid, this reference will be set to
+        it, which effectively detaches the reference if it was a purely symbolic one.
+
+        :param ref:
+            A :class:`SymbolicReference` instance, an :class:`~git.objects.base.Object`
+            instance (specifically an :class:`~git.types.AnyGitObject`), or a refspec
+            string. Only if the ref is a :class:`SymbolicReference` instance, we will
+            point to it. Everything else is dereferenced to obtain the actual object.
+
+        :param logmsg:
+            If set to a string, the message will be used in the reflog.
+            Otherwise, a reflog entry is not written for the changed reference.
+            The previous commit of the entry will be the commit we point to now.
+
+            See also: :meth:`log_append`
+
+        :return:
+            self
+
+        :note:
+            This symbolic reference will not be dereferenced. For that, see
+            :meth:`set_object`.
+        """
+        write_value = None
+        obj = None
+        if isinstance(ref, SymbolicReference):
+            write_value = "ref: %s" % ref.path
+        elif isinstance(ref, Object):
+            obj = ref
+            write_value = ref.hexsha
+        elif isinstance(ref, str):
+            try:
+                obj = self.repo.rev_parse(ref + "^{}")  # Optionally dereference tags.
+                write_value = obj.hexsha
+            except (BadObject, BadName) as e:
+                raise ValueError("Could not extract object from %s" % ref) from e
+            # END end try string
+        else:
+            raise ValueError("Unrecognized Value: %r" % ref)
+        # END try commit attribute
+
+        # typecheck
+        if obj is not None and self._points_to_commits_only and obj.type != Commit.type:
+            raise TypeError("Require commit, got %r" % obj)
+        # END verify type
+
+        oldbinsha: bytes = b""
+        if logmsg is not None:
+            try:
+                oldbinsha = self.commit.binsha
+            except ValueError:
+                oldbinsha = Commit.NULL_BIN_SHA
+            # END handle non-existing
+        # END retrieve old hexsha
+
+        fpath = self.abspath
+        assure_directory_exists(fpath, is_file=True)
+
+        lfd = LockedFD(fpath)
+        fd = lfd.open(write=True, stream=True)
+        try:
+            fd.write(write_value.encode("utf-8") + b"\n")
+            lfd.commit()
+        except BaseException:
+            lfd.rollback()
+            raise
+        # Adjust the reflog
+        if logmsg is not None:
+            self.log_append(oldbinsha, logmsg)
+
+        return self
+
+    # Aliased reference
+    @property
+    def reference(self) -> "SymbolicReference":
+        return self._get_reference()
+
+    @reference.setter
+    def reference(self, ref: Union[AnyGitObject, "SymbolicReference", str]) -> "SymbolicReference":
+        return self.set_reference(ref)
+
+    ref = reference
+
+    def is_valid(self) -> bool:
+        """
+        :return:
+            ``True`` if the reference is valid, hence it can be read and points to a
+            valid object or reference.
+        """
+        try:
+            self.object  # noqa: B018
+        except (OSError, ValueError):
+            return False
+        else:
+            return True
+
+    @property
+    def is_detached(self) -> bool:
+        """
+        :return:
+            ``True`` if we are a detached reference, hence we point to a specific commit
+            instead to another reference.
+        """
+        try:
+            self.ref  # noqa: B018
+            return False
+        except TypeError:
+            return True
+
+    def log(self) -> "RefLog":
+        """
+        :return:
+            :class:`~git.refs.log.RefLog` for this reference.
+            Its last entry reflects the latest change applied to this reference.
+
+        :note:
+            As the log is parsed every time, its recommended to cache it for use instead
+            of calling this method repeatedly. It should be considered read-only.
+        """
+        return RefLog.from_file(RefLog.path(self))
+
+    def log_append(
+        self,
+        oldbinsha: bytes,
+        message: Union[str, None],
+        newbinsha: Union[bytes, None] = None,
+    ) -> "RefLogEntry":
+        """Append a logentry to the logfile of this ref.
+
+        :param oldbinsha:
+            Binary sha this ref used to point to.
+
+        :param message:
+            A message describing the change.
+
+        :param newbinsha:
+            The sha the ref points to now. If None, our current commit sha will be used.
+
+        :return:
+            The added :class:`~git.refs.log.RefLogEntry` instance.
+        """
+        # NOTE: We use the committer of the currently active commit - this should be
+        # correct to allow overriding the committer on a per-commit level.
+        # See https://github.com/gitpython-developers/GitPython/pull/146.
+        try:
+            committer_or_reader: Union["Actor", "GitConfigParser"] = self.commit.committer
+        except ValueError:
+            committer_or_reader = self.repo.config_reader()
+        # END handle newly cloned repositories
+        if newbinsha is None:
+            newbinsha = self.commit.binsha
+
+        if message is None:
+            message = ""
+
+        return RefLog.append_entry(committer_or_reader, RefLog.path(self), oldbinsha, newbinsha, message)
+
+    def log_entry(self, index: int) -> "RefLogEntry":
+        """
+        :return:
+            :class:`~git.refs.log.RefLogEntry` at the given index
+
+        :param index:
+            Python list compatible positive or negative index.
+
+        :note:
+            This method must read part of the reflog during execution, hence it should
+            be used sparingly, or only if you need just one index. In that case, it will
+            be faster than the :meth:`log` method.
+        """
+        return RefLog.entry_at(RefLog.path(self), index)
+
+    @classmethod
+    def to_full_path(cls, path: Union[PathLike, "SymbolicReference"]) -> PathLike:
+        """
+        :return:
+            String with a full repository-relative path which can be used to initialize
+            a :class:`~git.refs.reference.Reference` instance, for instance by using
+            :meth:`Reference.from_path <git.refs.reference.Reference.from_path>`.
+        """
+        if isinstance(path, SymbolicReference):
+            path = path.path
+        full_ref_path = path
+        if not cls._common_path_default:
+            return full_ref_path
+        if not str(path).startswith(cls._common_path_default + "/"):
+            full_ref_path = "%s/%s" % (cls._common_path_default, path)
+        return full_ref_path
+
+    @classmethod
+    def delete(cls, repo: "Repo", path: PathLike) -> None:
+        """Delete the reference at the given path.
+
+        :param repo:
+            Repository to delete the reference from.
+
+        :param path:
+            Short or full path pointing to the reference, e.g. ``refs/myreference`` or
+            just ``myreference``, hence ``refs/`` is implied.
+            Alternatively the symbolic reference to be deleted.
+        """
+        full_ref_path = cls.to_full_path(path)
+        abs_path = os.path.join(repo.common_dir, full_ref_path)
+        if os.path.exists(abs_path):
+            os.remove(abs_path)
+        else:
+            # Check packed refs.
+            pack_file_path = cls._get_packed_refs_path(repo)
+            try:
+                with open(pack_file_path, "rb") as reader:
+                    new_lines = []
+                    made_change = False
+                    dropped_last_line = False
+                    for line_bytes in reader:
+                        line = line_bytes.decode(defenc)
+                        _, _, line_ref = line.partition(" ")
+                        line_ref = line_ref.strip()
+                        # Keep line if it is a comment or if the ref to delete is not in
+                        # the line.
+                        # If we deleted the last line and this one is a tag-reference
+                        # object, we drop it as well.
+                        if (line.startswith("#") or full_ref_path != line_ref) and (
+                            not dropped_last_line or dropped_last_line and not line.startswith("^")
+                        ):
+                            new_lines.append(line)
+                            dropped_last_line = False
+                            continue
+                        # END skip comments and lines without our path
+
+                        # Drop this line.
+                        made_change = True
+                        dropped_last_line = True
+
+                # Write the new lines.
+                if made_change:
+                    # Binary writing is required, otherwise Windows will open the file
+                    # in text mode and change LF to CRLF!
+                    with open(pack_file_path, "wb") as fd:
+                        fd.writelines(line.encode(defenc) for line in new_lines)
+
+            except OSError:
+                pass  # It didn't exist at all.
+
+        # Delete the reflog.
+        reflog_path = RefLog.path(cls(repo, full_ref_path))
+        if os.path.isfile(reflog_path):
+            os.remove(reflog_path)
+        # END remove reflog
+
+    @classmethod
+    def _create(
+        cls: Type[T_References],
+        repo: "Repo",
+        path: PathLike,
+        resolve: bool,
+        reference: Union["SymbolicReference", str],
+        force: bool,
+        logmsg: Union[str, None] = None,
+    ) -> T_References:
+        """Internal method used to create a new symbolic reference.
+
+        If `resolve` is ``False``, the reference will be taken as is, creating a proper
+        symbolic reference. Otherwise it will be resolved to the corresponding object
+        and a detached symbolic reference will be created instead.
+        """
+        git_dir = _git_dir(repo, path)
+        full_ref_path = cls.to_full_path(path)
+        abs_ref_path = os.path.join(git_dir, full_ref_path)
+
+        # Figure out target data.
+        target = reference
+        if resolve:
+            target = repo.rev_parse(str(reference))
+
+        if not force and os.path.isfile(abs_ref_path):
+            target_data = str(target)
+            if isinstance(target, SymbolicReference):
+                target_data = str(target.path)
+            if not resolve:
+                target_data = "ref: " + target_data
+            with open(abs_ref_path, "rb") as fd:
+                existing_data = fd.read().decode(defenc).strip()
+            if existing_data != target_data:
+                raise OSError(
+                    "Reference at %r does already exist, pointing to %r, requested was %r"
+                    % (full_ref_path, existing_data, target_data)
+                )
+        # END no force handling
+
+        ref = cls(repo, full_ref_path)
+        ref.set_reference(target, logmsg)
+        return ref
+
+    @classmethod
+    def create(
+        cls: Type[T_References],
+        repo: "Repo",
+        path: PathLike,
+        reference: Union["SymbolicReference", str] = "HEAD",
+        logmsg: Union[str, None] = None,
+        force: bool = False,
+        **kwargs: Any,
+    ) -> T_References:
+        """Create a new symbolic reference: a reference pointing to another reference.
+
+        :param repo:
+            Repository to create the reference in.
+
+        :param path:
+            Full path at which the new symbolic reference is supposed to be created at,
+            e.g. ``NEW_HEAD`` or ``symrefs/my_new_symref``.
+
+        :param reference:
+            The reference which the new symbolic reference should point to.
+            If it is a commit-ish, the symbolic ref will be detached.
+
+        :param force:
+            If ``True``, force creation even if a symbolic reference with that name
+            already exists. Raise :exc:`OSError` otherwise.
+
+        :param logmsg:
+            If not ``None``, the message to append to the reflog.
+            If ``None``, no reflog entry is written.
+
+        :return:
+            Newly created symbolic reference
+
+        :raise OSError:
+            If a (Symbolic)Reference with the same name but different contents already
+            exists.
+
+        :note:
+            This does not alter the current HEAD, index or working tree.
+        """
+        return cls._create(repo, path, cls._resolve_ref_on_create, reference, force, logmsg)
+
+    def rename(self, new_path: PathLike, force: bool = False) -> "SymbolicReference":
+        """Rename self to a new path.
+
+        :param new_path:
+            Either a simple name or a full path, e.g. ``new_name`` or
+            ``features/new_name``.
+            The prefix ``refs/`` is implied for references and will be set as needed.
+            In case this is a symbolic ref, there is no implied prefix.
+
+        :param force:
+            If ``True``, the rename will succeed even if a head with the target name
+            already exists. It will be overwritten in that case.
+
+        :return:
+            self
+
+        :raise OSError:
+            If a file at path but with different contents already exists.
+        """
+        new_path = self.to_full_path(new_path)
+        if self.path == new_path:
+            return self
+
+        new_abs_path = os.path.join(_git_dir(self.repo, new_path), new_path)
+        cur_abs_path = os.path.join(_git_dir(self.repo, self.path), self.path)
+        if os.path.isfile(new_abs_path):
+            if not force:
+                # If they point to the same file, it's not an error.
+                with open(new_abs_path, "rb") as fd1:
+                    f1 = fd1.read().strip()
+                with open(cur_abs_path, "rb") as fd2:
+                    f2 = fd2.read().strip()
+                if f1 != f2:
+                    raise OSError("File at path %r already exists" % new_abs_path)
+                # else: We could remove ourselves and use the other one, but...
+                # ...for clarity, we just continue as usual.
+            # END not force handling
+            os.remove(new_abs_path)
+        # END handle existing target file
+
+        dname = os.path.dirname(new_abs_path)
+        if not os.path.isdir(dname):
+            os.makedirs(dname)
+        # END create directory
+
+        os.rename(cur_abs_path, new_abs_path)
+        self.path = new_path
+
+        return self
+
+    @classmethod
+    def _iter_items(
+        cls: Type[T_References], repo: "Repo", common_path: Union[PathLike, None] = None
+    ) -> Iterator[T_References]:
+        if common_path is None:
+            common_path = cls._common_path_default
+        rela_paths = set()
+
+        # Walk loose refs.
+        # Currently we do not follow links.
+        for root, dirs, files in os.walk(join_path_native(repo.common_dir, common_path)):
+            if "refs" not in root.split(os.sep):  # Skip non-refs subfolders.
+                refs_id = [d for d in dirs if d == "refs"]
+                if refs_id:
+                    dirs[0:] = ["refs"]
+            # END prune non-refs folders
+
+            for f in files:
+                if f == "packed-refs":
+                    continue
+                abs_path = to_native_path_linux(join_path(root, f))
+                rela_paths.add(abs_path.replace(to_native_path_linux(repo.common_dir) + "/", ""))
+            # END for each file in root directory
+        # END for each directory to walk
+
+        # Read packed refs.
+        for _sha, rela_path in cls._iter_packed_refs(repo):
+            if rela_path.startswith(str(common_path)):
+                rela_paths.add(rela_path)
+            # END relative path matches common path
+        # END packed refs reading
+
+        # Yield paths in sorted order.
+        for path in sorted(rela_paths):
+            try:
+                yield cls.from_path(repo, path)
+            except ValueError:
+                continue
+        # END for each sorted relative refpath
+
+    @classmethod
+    def iter_items(
+        cls: Type[T_References],
+        repo: "Repo",
+        common_path: Union[PathLike, None] = None,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Iterator[T_References]:
+        """Find all refs in the repository.
+
+        :param repo:
+            The :class:`~git.repo.base.Repo`.
+
+        :param common_path:
+            Optional keyword argument to the path which is to be shared by all returned
+            Ref objects.
+            Defaults to class specific portion if ``None``, ensuring that only refs
+            suitable for the actual class are returned.
+
+        :return:
+            A list of :class:`SymbolicReference`, each guaranteed to be a symbolic ref
+            which is not detached and pointing to a valid ref.
+
+            The list is lexicographically sorted. The returned objects are instances of
+            concrete subclasses, such as :class:`~git.refs.head.Head` or
+            :class:`~git.refs.tag.TagReference`.
+        """
+        return (r for r in cls._iter_items(repo, common_path) if r.__class__ is SymbolicReference or not r.is_detached)
+
+    @classmethod
+    def from_path(cls: Type[T_References], repo: "Repo", path: PathLike) -> T_References:
+        """Make a symbolic reference from a path.
+
+        :param path:
+            Full ``.git``-directory-relative path name to the Reference to instantiate.
+
+        :note:
+            Use :meth:`to_full_path` if you only have a partial path of a known
+            Reference type.
+
+        :return:
+            Instance of type :class:`~git.refs.reference.Reference`,
+            :class:`~git.refs.head.Head`, or :class:`~git.refs.tag.Tag`, depending on
+            the given path.
+        """
+        if not path:
+            raise ValueError("Cannot create Reference from %r" % path)
+
+        # Names like HEAD are inserted after the refs module is imported - we have an
+        # import dependency cycle and don't want to import these names in-function.
+        from . import HEAD, Head, RemoteReference, TagReference, Reference
+
+        for ref_type in (
+            HEAD,
+            Head,
+            RemoteReference,
+            TagReference,
+            Reference,
+            SymbolicReference,
+        ):
+            try:
+                instance: T_References
+                instance = ref_type(repo, path)
+                if instance.__class__ is SymbolicReference and instance.is_detached:
+                    raise ValueError("SymbolicRef was detached, we drop it")
+                else:
+                    return instance
+
+            except ValueError:
+                pass
+            # END exception handling
+        # END for each type to try
+        raise ValueError("Could not find reference type suitable to handle path %r" % path)
+
+    def is_remote(self) -> bool:
+        """:return: True if this symbolic reference points to a remote branch"""
+        return str(self.path).startswith(self._remote_common_path_default + "/")

.venv/lib/python3.11/site-packages/git/refs/tag.py

@@ -0,0 +1,155 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Provides a :class:`~git.refs.reference.Reference`-based type for lightweight tags.
+
+This defines the :class:`TagReference` class (and its alias :class:`Tag`), which
+represents lightweight tags. For annotated tags (which are git objects), see the
+:mod:`git.objects.tag` module.
+"""
+
+__all__ = ["TagReference", "Tag"]
+
+from .reference import Reference
+
+# typing ------------------------------------------------------------------
+
+from typing import Any, TYPE_CHECKING, Type, Union
+
+from git.types import AnyGitObject, PathLike
+
+if TYPE_CHECKING:
+    from git.objects import Commit, TagObject
+    from git.refs import SymbolicReference
+    from git.repo import Repo
+
+# ------------------------------------------------------------------------------
+
+
+class TagReference(Reference):
+    """A lightweight tag reference which either points to a commit, a tag object or any
+    other object. In the latter case additional information, like the signature or the
+    tag-creator, is available.
+
+    This tag object will always point to a commit object, but may carry additional
+    information in a tag object::
+
+     tagref = TagReference.list_items(repo)[0]
+     print(tagref.commit.message)
+     if tagref.tag is not None:
+        print(tagref.tag.message)
+    """
+
+    __slots__ = ()
+
+    _common_default = "tags"
+    _common_path_default = Reference._common_path_default + "/" + _common_default
+
+    @property
+    def commit(self) -> "Commit":  # type: ignore[override]  # LazyMixin has unrelated commit method
+        """:return: Commit object the tag ref points to
+
+        :raise ValueError:
+            If the tag points to a tree or blob.
+        """
+        obj = self.object
+        while obj.type != "commit":
+            if obj.type == "tag":
+                # It is a tag object which carries the commit as an object - we can point to anything.
+                obj = obj.object
+            else:
+                raise ValueError(
+                    (
+                        "Cannot resolve commit as tag %s points to a %s object - "
+                        + "use the `.object` property instead to access it"
+                    )
+                    % (self, obj.type)
+                )
+        return obj
+
+    @property
+    def tag(self) -> Union["TagObject", None]:
+        """
+        :return:
+            Tag object this tag ref points to, or ``None`` in case we are a lightweight
+            tag
+        """
+        obj = self.object
+        if obj.type == "tag":
+            return obj
+        return None
+
+    # Make object read-only. It should be reasonably hard to adjust an existing tag.
+    @property
+    def object(self) -> AnyGitObject:  # type: ignore[override]
+        return Reference._get_object(self)
+
+    @classmethod
+    def create(
+        cls: Type["TagReference"],
+        repo: "Repo",
+        path: PathLike,
+        reference: Union[str, "SymbolicReference"] = "HEAD",
+        logmsg: Union[str, None] = None,
+        force: bool = False,
+        **kwargs: Any,
+    ) -> "TagReference":
+        """Create a new tag reference.
+
+        :param repo:
+            The :class:`~git.repo.base.Repo` to create the tag in.
+
+        :param path:
+            The name of the tag, e.g. ``1.0`` or ``releases/1.0``.
+            The prefix ``refs/tags`` is implied.
+
+        :param reference:
+            A reference to the :class:`~git.objects.base.Object` you want to tag.
+            The referenced object can be a commit, tree, or blob.
+
+        :param logmsg:
+            If not ``None``, the message will be used in your tag object. This will also
+            create an additional tag object that allows to obtain that information,
+            e.g.::
+
+                tagref.tag.message
+
+        :param message:
+            Synonym for the `logmsg` parameter. Included for backwards compatibility.
+            `logmsg` takes precedence if both are passed.
+
+        :param force:
+            If ``True``, force creation of a tag even though that tag already exists.
+
+        :param kwargs:
+            Additional keyword arguments to be passed to :manpage:`git-tag(1)`.
+
+        :return:
+            A new :class:`TagReference`.
+        """
+        if "ref" in kwargs and kwargs["ref"]:
+            reference = kwargs["ref"]
+
+        if "message" in kwargs and kwargs["message"]:
+            kwargs["m"] = kwargs["message"]
+            del kwargs["message"]
+
+        if logmsg:
+            kwargs["m"] = logmsg
+
+        if force:
+            kwargs["f"] = True
+
+        args = (path, reference)
+
+        repo.git.tag(*args, **kwargs)
+        return TagReference(repo, "%s/%s" % (cls._common_path_default, path))
+
+    @classmethod
+    def delete(cls, repo: "Repo", *tags: "TagReference") -> None:  # type: ignore[override]
+        """Delete the given existing tag or tags."""
+        repo.git.tag("-d", *tags)
+
+
+# Provide an alias.
+Tag = TagReference

.venv/lib/python3.11/site-packages/git/remote.py

@@ -0,0 +1,1248 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Module implementing a remote object allowing easy access to git remotes."""
+
+__all__ = ["RemoteProgress", "PushInfo", "FetchInfo", "Remote"]
+
+import contextlib
+import logging
+import re
+
+from git.cmd import Git, handle_process_output
+from git.compat import defenc, force_text
+from git.config import GitConfigParser, SectionConstraint, cp
+from git.exc import GitCommandError
+from git.refs import Head, Reference, RemoteReference, SymbolicReference, TagReference
+from git.util import (
+    CallableRemoteProgress,
+    IterableList,
+    IterableObj,
+    LazyMixin,
+    RemoteProgress,
+    join_path,
+)
+
+# typing-------------------------------------------------------
+
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    Iterator,
+    List,
+    NoReturn,
+    Optional,
+    Sequence,
+    TYPE_CHECKING,
+    Type,
+    Union,
+    cast,
+    overload,
+)
+
+from git.types import AnyGitObject, Literal, PathLike
+
+if TYPE_CHECKING:
+    from git.objects.commit import Commit
+    from git.objects.submodule.base import UpdateProgress
+    from git.repo.base import Repo
+
+flagKeyLiteral = Literal[" ", "!", "+", "-", "*", "=", "t", "?"]
+
+# -------------------------------------------------------------
+
+_logger = logging.getLogger(__name__)
+
+# { Utilities
+
+
+def add_progress(
+    kwargs: Any,
+    git: Git,
+    progress: Union[RemoteProgress, "UpdateProgress", Callable[..., RemoteProgress], None],
+) -> Any:
+    """Add the ``--progress`` flag to the given `kwargs` dict if supported by the git
+    command.
+
+    :note:
+        If the actual progress in the given progress instance is not given, we do not
+        request any progress.
+
+    :return:
+        Possibly altered `kwargs`
+    """
+    if progress is not None:
+        v = git.version_info[:2]
+        if v >= (1, 7):
+            kwargs["progress"] = True
+        # END handle --progress
+    # END handle progress
+    return kwargs
+
+
+# } END utilities
+
+
+@overload
+def to_progress_instance(progress: None) -> RemoteProgress: ...
+
+
+@overload
+def to_progress_instance(progress: Callable[..., Any]) -> CallableRemoteProgress: ...
+
+
+@overload
+def to_progress_instance(progress: RemoteProgress) -> RemoteProgress: ...
+
+
+def to_progress_instance(
+    progress: Union[Callable[..., Any], RemoteProgress, None],
+) -> Union[RemoteProgress, CallableRemoteProgress]:
+    """Given the `progress` return a suitable object derived from
+    :class:`~git.util.RemoteProgress`."""
+    # New API only needs progress as a function.
+    if callable(progress):
+        return CallableRemoteProgress(progress)
+
+    # Where None is passed create a parser that eats the progress.
+    elif progress is None:
+        return RemoteProgress()
+
+    # Assume its the old API with an instance of RemoteProgress.
+    return progress
+
+
+class PushInfo(IterableObj):
+    """
+    Carries information about the result of a push operation of a single head::
+
+        info = remote.push()[0]
+        info.flags          # bitflags providing more information about the result
+        info.local_ref      # Reference pointing to the local reference that was pushed
+                            # It is None if the ref was deleted.
+        info.remote_ref_string # path to the remote reference located on the remote side
+        info.remote_ref # Remote Reference on the local side corresponding to
+                        # the remote_ref_string. It can be a TagReference as well.
+        info.old_commit # commit at which the remote_ref was standing before we pushed
+                        # it to local_ref.commit. Will be None if an error was indicated
+        info.summary    # summary line providing human readable english text about the push
+    """
+
+    __slots__ = (
+        "local_ref",
+        "remote_ref_string",
+        "flags",
+        "_old_commit_sha",
+        "_remote",
+        "summary",
+    )
+
+    _id_attribute_ = "pushinfo"
+
+    (
+        NEW_TAG,
+        NEW_HEAD,
+        NO_MATCH,
+        REJECTED,
+        REMOTE_REJECTED,
+        REMOTE_FAILURE,
+        DELETED,
+        FORCED_UPDATE,
+        FAST_FORWARD,
+        UP_TO_DATE,
+        ERROR,
+    ) = [1 << x for x in range(11)]
+
+    _flag_map = {
+        "X": NO_MATCH,
+        "-": DELETED,
+        "*": 0,
+        "+": FORCED_UPDATE,
+        " ": FAST_FORWARD,
+        "=": UP_TO_DATE,
+        "!": ERROR,
+    }
+
+    def __init__(
+        self,
+        flags: int,
+        local_ref: Union[SymbolicReference, None],
+        remote_ref_string: str,
+        remote: "Remote",
+        old_commit: Optional[str] = None,
+        summary: str = "",
+    ) -> None:
+        """Initialize a new instance.
+
+        local_ref: HEAD | Head | RemoteReference | TagReference | Reference | SymbolicReference | None
+        """
+        self.flags = flags
+        self.local_ref = local_ref
+        self.remote_ref_string = remote_ref_string
+        self._remote = remote
+        self._old_commit_sha = old_commit
+        self.summary = summary
+
+    @property
+    def old_commit(self) -> Union["Commit", None]:
+        return self._old_commit_sha and self._remote.repo.commit(self._old_commit_sha) or None
+
+    @property
+    def remote_ref(self) -> Union[RemoteReference, TagReference]:
+        """
+        :return:
+            Remote :class:`~git.refs.reference.Reference` or
+            :class:`~git.refs.tag.TagReference` in the local repository corresponding to
+            the :attr:`remote_ref_string` kept in this instance.
+        """
+        # Translate heads to a local remote. Tags stay as they are.
+        if self.remote_ref_string.startswith("refs/tags"):
+            return TagReference(self._remote.repo, self.remote_ref_string)
+        elif self.remote_ref_string.startswith("refs/heads"):
+            remote_ref = Reference(self._remote.repo, self.remote_ref_string)
+            return RemoteReference(
+                self._remote.repo,
+                "refs/remotes/%s/%s" % (str(self._remote), remote_ref.name),
+            )
+        else:
+            raise ValueError("Could not handle remote ref: %r" % self.remote_ref_string)
+        # END
+
+    @classmethod
+    def _from_line(cls, remote: "Remote", line: str) -> "PushInfo":
+        """Create a new :class:`PushInfo` instance as parsed from line which is expected
+        to be like refs/heads/master:refs/heads/master 05d2687..1d0568e as bytes."""
+        control_character, from_to, summary = line.split("\t", 3)
+        flags = 0
+
+        # Control character handling
+        try:
+            flags |= cls._flag_map[control_character]
+        except KeyError as e:
+            raise ValueError("Control character %r unknown as parsed from line %r" % (control_character, line)) from e
+        # END handle control character
+
+        # from_to handling
+        from_ref_string, to_ref_string = from_to.split(":")
+        if flags & cls.DELETED:
+            from_ref: Union[SymbolicReference, None] = None
+        else:
+            if from_ref_string == "(delete)":
+                from_ref = None
+            else:
+                from_ref = Reference.from_path(remote.repo, from_ref_string)
+
+        # Commit handling, could be message or commit info
+        old_commit: Optional[str] = None
+        if summary.startswith("["):
+            if "[rejected]" in summary:
+                flags |= cls.REJECTED
+            elif "[remote rejected]" in summary:
+                flags |= cls.REMOTE_REJECTED
+            elif "[remote failure]" in summary:
+                flags |= cls.REMOTE_FAILURE
+            elif "[no match]" in summary:
+                flags |= cls.ERROR
+            elif "[new tag]" in summary:
+                flags |= cls.NEW_TAG
+            elif "[new branch]" in summary:
+                flags |= cls.NEW_HEAD
+            # `uptodate` encoded in control character
+        else:
+            # Fast-forward or forced update - was encoded in control character,
+            # but we parse the old and new commit.
+            split_token = "..."
+            if control_character == " ":
+                split_token = ".."
+            old_sha, _new_sha = summary.split(" ")[0].split(split_token)
+            # Have to use constructor here as the sha usually is abbreviated.
+            old_commit = old_sha
+        # END message handling
+
+        return PushInfo(flags, from_ref, to_ref_string, remote, old_commit, summary)
+
+    @classmethod
+    def iter_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> NoReturn:  # -> Iterator['PushInfo']:
+        raise NotImplementedError
+
+
+class PushInfoList(IterableList[PushInfo]):
+    """:class:`~git.util.IterableList` of :class:`PushInfo` objects."""
+
+    def __new__(cls) -> "PushInfoList":
+        return cast(PushInfoList, IterableList.__new__(cls, "push_infos"))
+
+    def __init__(self) -> None:
+        super().__init__("push_infos")
+        self.error: Optional[Exception] = None
+
+    def raise_if_error(self) -> None:
+        """Raise an exception if any ref failed to push."""
+        if self.error:
+            raise self.error
+
+
+class FetchInfo(IterableObj):
+    """
+    Carries information about the results of a fetch operation of a single head::
+
+     info = remote.fetch()[0]
+     info.ref           # Symbolic Reference or RemoteReference to the changed
+                        # remote head or FETCH_HEAD
+     info.flags         # additional flags to be & with enumeration members,
+                        # i.e. info.flags & info.REJECTED
+                        # is 0 if ref is SymbolicReference
+     info.note          # additional notes given by git-fetch intended for the user
+     info.old_commit    # if info.flags & info.FORCED_UPDATE|info.FAST_FORWARD,
+                        # field is set to the previous location of ref, otherwise None
+     info.remote_ref_path # The path from which we fetched on the remote. It's the remote's version of our info.ref
+    """
+
+    __slots__ = ("ref", "old_commit", "flags", "note", "remote_ref_path")
+
+    _id_attribute_ = "fetchinfo"
+
+    (
+        NEW_TAG,
+        NEW_HEAD,
+        HEAD_UPTODATE,
+        TAG_UPDATE,
+        REJECTED,
+        FORCED_UPDATE,
+        FAST_FORWARD,
+        ERROR,
+    ) = [1 << x for x in range(8)]
+
+    _re_fetch_result = re.compile(r"^ *(?:.{0,3})(.) (\[[\w \.$@]+\]|[\w\.$@]+) +(.+) -> ([^ ]+)(    \(.*\)?$)?")
+
+    _flag_map: Dict[flagKeyLiteral, int] = {
+        "!": ERROR,
+        "+": FORCED_UPDATE,
+        "*": 0,
+        "=": HEAD_UPTODATE,
+        " ": FAST_FORWARD,
+        "-": TAG_UPDATE,
+    }
+
+    @classmethod
+    def refresh(cls) -> Literal[True]:
+        """Update information about which :manpage:`git-fetch(1)` flags are supported
+        by the git executable being used.
+
+        Called by the :func:`git.refresh` function in the top level ``__init__``.
+        """
+        # Clear the old values in _flag_map.
+        with contextlib.suppress(KeyError):
+            del cls._flag_map["t"]
+        with contextlib.suppress(KeyError):
+            del cls._flag_map["-"]
+
+        # Set the value given the git version.
+        if Git().version_info[:2] >= (2, 10):
+            cls._flag_map["t"] = cls.TAG_UPDATE
+        else:
+            cls._flag_map["-"] = cls.TAG_UPDATE
+
+        return True
+
+    def __init__(
+        self,
+        ref: SymbolicReference,
+        flags: int,
+        note: str = "",
+        old_commit: Union[AnyGitObject, None] = None,
+        remote_ref_path: Optional[PathLike] = None,
+    ) -> None:
+        """Initialize a new instance."""
+        self.ref = ref
+        self.flags = flags
+        self.note = note
+        self.old_commit = old_commit
+        self.remote_ref_path = remote_ref_path
+
+    def __str__(self) -> str:
+        return self.name
+
+    @property
+    def name(self) -> str:
+        """:return: Name of our remote ref"""
+        return self.ref.name
+
+    @property
+    def commit(self) -> "Commit":
+        """:return: Commit of our remote ref"""
+        return self.ref.commit
+
+    @classmethod
+    def _from_line(cls, repo: "Repo", line: str, fetch_line: str) -> "FetchInfo":
+        """Parse information from the given line as returned by ``git-fetch -v`` and
+        return a new :class:`FetchInfo` object representing this information.
+
+        We can handle a line as follows::
+
+            %c %-*s %-*s -> %s%s
+
+        Where ``c`` is either a space, ``!``, ``+``, ``-``, ``*``, or ``=``:
+
+        - '!' means error
+        - '+' means success forcing update
+        - '-' means a tag was updated
+        - '*' means birth of new branch or tag
+        - '=' means the head was up to date (and not moved)
+        - ' ' means a fast-forward
+
+        `fetch_line` is the corresponding line from FETCH_HEAD, like::
+
+            acb0fa8b94ef421ad60c8507b634759a472cd56c    not-for-merge   branch '0.1.7RC' of /tmp/tmpya0vairemote_repo
+        """
+        match = cls._re_fetch_result.match(line)
+        if match is None:
+            raise ValueError("Failed to parse line: %r" % line)
+
+        # Parse lines.
+        remote_local_ref_str: str
+        (
+            control_character,
+            operation,
+            local_remote_ref,
+            remote_local_ref_str,
+            note,
+        ) = match.groups()
+        control_character = cast(flagKeyLiteral, control_character)
+        try:
+            _new_hex_sha, _fetch_operation, fetch_note = fetch_line.split("\t")
+            ref_type_name, fetch_note = fetch_note.split(" ", 1)
+        except ValueError as e:  # unpack error
+            raise ValueError("Failed to parse FETCH_HEAD line: %r" % fetch_line) from e
+
+        # Parse flags from control_character.
+        flags = 0
+        try:
+            flags |= cls._flag_map[control_character]
+        except KeyError as e:
+            raise ValueError("Control character %r unknown as parsed from line %r" % (control_character, line)) from e
+        # END control char exception handling
+
+        # Parse operation string for more info.
+        # This makes no sense for symbolic refs, but we parse it anyway.
+        old_commit: Union[AnyGitObject, None] = None
+        is_tag_operation = False
+        if "rejected" in operation:
+            flags |= cls.REJECTED
+        if "new tag" in operation:
+            flags |= cls.NEW_TAG
+            is_tag_operation = True
+        if "tag update" in operation:
+            flags |= cls.TAG_UPDATE
+            is_tag_operation = True
+        if "new branch" in operation:
+            flags |= cls.NEW_HEAD
+        if "..." in operation or ".." in operation:
+            split_token = "..."
+            if control_character == " ":
+                split_token = split_token[:-1]
+            old_commit = repo.rev_parse(operation.split(split_token)[0])
+        # END handle refspec
+
+        # Handle FETCH_HEAD and figure out ref type.
+        # If we do not specify a target branch like master:refs/remotes/origin/master,
+        # the fetch result is stored in FETCH_HEAD which destroys the rule we usually
+        # have. In that case we use a symbolic reference which is detached.
+        ref_type: Optional[Type[SymbolicReference]] = None
+        if remote_local_ref_str == "FETCH_HEAD":
+            ref_type = SymbolicReference
+        elif ref_type_name == "tag" or is_tag_operation:
+            # The ref_type_name can be branch, whereas we are still seeing a tag
+            # operation. It happens during testing, which is based on actual git
+            # operations.
+            ref_type = TagReference
+        elif ref_type_name in ("remote-tracking", "branch"):
+            # Note: remote-tracking is just the first part of the
+            # 'remote-tracking branch' token. We don't parse it correctly, but it's
+            # enough to know what to do, and it's new in git 1.7something.
+            ref_type = RemoteReference
+        elif "/" in ref_type_name:
+            # If the fetch spec look something like '+refs/pull/*:refs/heads/pull/*',
+            # and is thus pretty much anything the user wants, we will have trouble
+            # determining what's going on. For now, we assume the local ref is a Head.
+            ref_type = Head
+        else:
+            raise TypeError("Cannot handle reference type: %r" % ref_type_name)
+        # END handle ref type
+
+        # Create ref instance.
+        if ref_type is SymbolicReference:
+            remote_local_ref = ref_type(repo, "FETCH_HEAD")
+        else:
+            # Determine prefix. Tags are usually pulled into refs/tags; they may have
+            # subdirectories. It is not clear sometimes where exactly the item is,
+            # unless we have an absolute path as indicated by the 'ref/' prefix.
+            # Otherwise even a tag could be in refs/remotes, which is when it will have
+            # the 'tags/' subdirectory in its path. We don't want to test for actual
+            # existence, but try to figure everything out analytically.
+            ref_path: Optional[PathLike] = None
+            remote_local_ref_str = remote_local_ref_str.strip()
+
+            if remote_local_ref_str.startswith(Reference._common_path_default + "/"):
+                # Always use actual type if we get absolute paths. This will always be
+                # the case if something is fetched outside of refs/remotes (if its not a
+                # tag).
+                ref_path = remote_local_ref_str
+                if ref_type is not TagReference and not remote_local_ref_str.startswith(
+                    RemoteReference._common_path_default + "/"
+                ):
+                    ref_type = Reference
+                # END downgrade remote reference
+            elif ref_type is TagReference and "tags/" in remote_local_ref_str:
+                # Even though it's a tag, it is located in refs/remotes.
+                ref_path = join_path(RemoteReference._common_path_default, remote_local_ref_str)
+            else:
+                ref_path = join_path(ref_type._common_path_default, remote_local_ref_str)
+            # END obtain refpath
+
+            # Even though the path could be within the git conventions, we make sure we
+            # respect whatever the user wanted, and disabled path checking.
+            remote_local_ref = ref_type(repo, ref_path, check_path=False)
+        # END create ref instance
+
+        note = (note and note.strip()) or ""
+
+        return cls(remote_local_ref, flags, note, old_commit, local_remote_ref)
+
+    @classmethod
+    def iter_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> NoReturn:  # -> Iterator['FetchInfo']:
+        raise NotImplementedError
+
+
+class Remote(LazyMixin, IterableObj):
+    """Provides easy read and write access to a git remote.
+
+    Everything not part of this interface is considered an option for the current
+    remote, allowing constructs like ``remote.pushurl`` to query the pushurl.
+
+    :note:
+        When querying configuration, the configuration accessor will be cached to speed
+        up subsequent accesses.
+    """
+
+    __slots__ = ("repo", "name", "_config_reader")
+
+    _id_attribute_ = "name"
+
+    unsafe_git_fetch_options = [
+        # This option allows users to execute arbitrary commands.
+        # https://git-scm.com/docs/git-fetch#Documentation/git-fetch.txt---upload-packltupload-packgt
+        "--upload-pack",
+    ]
+    unsafe_git_pull_options = [
+        # This option allows users to execute arbitrary commands.
+        # https://git-scm.com/docs/git-pull#Documentation/git-pull.txt---upload-packltupload-packgt
+        "--upload-pack"
+    ]
+    unsafe_git_push_options = [
+        # This option allows users to execute arbitrary commands.
+        # https://git-scm.com/docs/git-push#Documentation/git-push.txt---execltgit-receive-packgt
+        "--receive-pack",
+        "--exec",
+    ]
+
+    url: str  # Obtained dynamically from _config_reader. See __getattr__ below.
+    """The URL configured for the remote."""
+
+    def __init__(self, repo: "Repo", name: str) -> None:
+        """Initialize a remote instance.
+
+        :param repo:
+            The repository we are a remote of.
+
+        :param name:
+            The name of the remote, e.g. ``origin``.
+        """
+        self.repo = repo
+        self.name = name
+
+    def __getattr__(self, attr: str) -> Any:
+        """Allows to call this instance like ``remote.special(*args, **kwargs)`` to
+        call ``git remote special self.name``."""
+        if attr == "_config_reader":
+            return super().__getattr__(attr)
+
+        # Sometimes, probably due to a bug in Python itself, we are being called even
+        # though a slot of the same name exists.
+        try:
+            return self._config_reader.get(attr)
+        except cp.NoOptionError:
+            return super().__getattr__(attr)
+        # END handle exception
+
+    def _config_section_name(self) -> str:
+        return 'remote "%s"' % self.name
+
+    def _set_cache_(self, attr: str) -> None:
+        if attr == "_config_reader":
+            # NOTE: This is cached as __getattr__ is overridden to return remote config
+            # values implicitly, such as in print(r.pushurl).
+            self._config_reader = SectionConstraint(
+                self.repo.config_reader("repository"),
+                self._config_section_name(),
+            )
+        else:
+            super()._set_cache_(attr)
+
+    def __str__(self) -> str:
+        return self.name
+
+    def __repr__(self) -> str:
+        return '<git.%s "%s">' % (self.__class__.__name__, self.name)
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, type(self)) and self.name == other.name
+
+    def __ne__(self, other: object) -> bool:
+        return not (self == other)
+
+    def __hash__(self) -> int:
+        return hash(self.name)
+
+    def exists(self) -> bool:
+        """
+        :return:
+            ``True`` if this is a valid, existing remote.
+            Valid remotes have an entry in the repository's configuration.
+        """
+        try:
+            self.config_reader.get("url")
+            return True
+        except cp.NoOptionError:
+            # We have the section at least...
+            return True
+        except cp.NoSectionError:
+            return False
+
+    @classmethod
+    def iter_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> Iterator["Remote"]:
+        """:return: Iterator yielding :class:`Remote` objects of the given repository"""
+        for section in repo.config_reader("repository").sections():
+            if not section.startswith("remote "):
+                continue
+            lbound = section.find('"')
+            rbound = section.rfind('"')
+            if lbound == -1 or rbound == -1:
+                raise ValueError("Remote-Section has invalid format: %r" % section)
+            yield Remote(repo, section[lbound + 1 : rbound])
+        # END for each configuration section
+
+    def set_url(
+        self, new_url: str, old_url: Optional[str] = None, allow_unsafe_protocols: bool = False, **kwargs: Any
+    ) -> "Remote":
+        """Configure URLs on current remote (cf. command ``git remote set-url``).
+
+        This command manages URLs on the remote.
+
+        :param new_url:
+            String being the URL to add as an extra remote URL.
+
+        :param old_url:
+            When set, replaces this URL with `new_url` for the remote.
+
+        :param allow_unsafe_protocols:
+            Allow unsafe protocols to be used, like ``ext``.
+
+        :return:
+            self
+        """
+        if not allow_unsafe_protocols:
+            Git.check_unsafe_protocols(new_url)
+        scmd = "set-url"
+        kwargs["insert_kwargs_after"] = scmd
+        if old_url:
+            self.repo.git.remote(scmd, "--", self.name, new_url, old_url, **kwargs)
+        else:
+            self.repo.git.remote(scmd, "--", self.name, new_url, **kwargs)
+        return self
+
+    def add_url(self, url: str, allow_unsafe_protocols: bool = False, **kwargs: Any) -> "Remote":
+        """Adds a new url on current remote (special case of ``git remote set-url``).
+
+        This command adds new URLs to a given remote, making it possible to have
+        multiple URLs for a single remote.
+
+        :param url:
+            String being the URL to add as an extra remote URL.
+
+        :param allow_unsafe_protocols:
+            Allow unsafe protocols to be used, like ``ext``.
+
+        :return:
+            self
+        """
+        return self.set_url(url, add=True, allow_unsafe_protocols=allow_unsafe_protocols)
+
+    def delete_url(self, url: str, **kwargs: Any) -> "Remote":
+        """Deletes a new url on current remote (special case of ``git remote set-url``).
+
+        This command deletes new URLs to a given remote, making it possible to have
+        multiple URLs for a single remote.
+
+        :param url:
+            String being the URL to delete from the remote.
+
+        :return:
+            self
+        """
+        return self.set_url(url, delete=True)
+
+    @property
+    def urls(self) -> Iterator[str]:
+        """:return: Iterator yielding all configured URL targets on a remote as strings"""
+        try:
+            remote_details = self.repo.git.remote("get-url", "--all", self.name)
+            assert isinstance(remote_details, str)
+            for line in remote_details.split("\n"):
+                yield line
+        except GitCommandError as ex:
+            ## We are on git < 2.7 (i.e TravisCI as of Oct-2016),
+            #  so `get-utl` command does not exist yet!
+            #    see: https://github.com/gitpython-developers/GitPython/pull/528#issuecomment-252976319
+            #    and: http://stackoverflow.com/a/32991784/548792
+            #
+            if "Unknown subcommand: get-url" in str(ex):
+                try:
+                    remote_details = self.repo.git.remote("show", self.name)
+                    assert isinstance(remote_details, str)
+                    for line in remote_details.split("\n"):
+                        if "  Push  URL:" in line:
+                            yield line.split(": ")[-1]
+                except GitCommandError as _ex:
+                    if any(msg in str(_ex) for msg in ["correct access rights", "cannot run ssh"]):
+                        # If ssh is not setup to access this repository, see issue 694.
+                        remote_details = self.repo.git.config("--get-all", "remote.%s.url" % self.name)
+                        assert isinstance(remote_details, str)
+                        for line in remote_details.split("\n"):
+                            yield line
+                    else:
+                        raise _ex
+            else:
+                raise ex
+
+    @property
+    def refs(self) -> IterableList[RemoteReference]:
+        """
+        :return:
+            :class:`~git.util.IterableList` of :class:`~git.refs.remote.RemoteReference`
+            objects.
+
+            It is prefixed, allowing you to omit the remote path portion, e.g.::
+
+                remote.refs.master  # yields RemoteReference('/refs/remotes/origin/master')
+        """
+        out_refs: IterableList[RemoteReference] = IterableList(RemoteReference._id_attribute_, "%s/" % self.name)
+        out_refs.extend(RemoteReference.list_items(self.repo, remote=self.name))
+        return out_refs
+
+    @property
+    def stale_refs(self) -> IterableList[Reference]:
+        """
+        :return:
+            :class:`~git.util.IterableList` of :class:`~git.refs.remote.RemoteReference`
+            objects that do not have a corresponding head in the remote reference
+            anymore as they have been deleted on the remote side, but are still
+            available locally.
+
+            The :class:`~git.util.IterableList` is prefixed, hence the 'origin' must be
+            omitted. See :attr:`refs` property for an example.
+
+            To make things more complicated, it can be possible for the list to include
+            other kinds of references, for example, tag references, if these are stale
+            as well. This is a fix for the issue described here:
+            https://github.com/gitpython-developers/GitPython/issues/260
+        """
+        out_refs: IterableList[Reference] = IterableList(RemoteReference._id_attribute_, "%s/" % self.name)
+        for line in self.repo.git.remote("prune", "--dry-run", self).splitlines()[2:]:
+            # expecting
+            # * [would prune] origin/new_branch
+            token = " * [would prune] "
+            if not line.startswith(token):
+                continue
+            ref_name = line.replace(token, "")
+            # Sometimes, paths start with a full ref name, like refs/tags/foo. See #260.
+            if ref_name.startswith(Reference._common_path_default + "/"):
+                out_refs.append(Reference.from_path(self.repo, ref_name))
+            else:
+                fqhn = "%s/%s" % (RemoteReference._common_path_default, ref_name)
+                out_refs.append(RemoteReference(self.repo, fqhn))
+            # END special case handling
+        # END for each line
+        return out_refs
+
+    @classmethod
+    def create(cls, repo: "Repo", name: str, url: str, allow_unsafe_protocols: bool = False, **kwargs: Any) -> "Remote":
+        """Create a new remote to the given repository.
+
+        :param repo:
+            Repository instance that is to receive the new remote.
+
+        :param name:
+            Desired name of the remote.
+
+        :param url:
+            URL which corresponds to the remote's name.
+
+        :param allow_unsafe_protocols:
+            Allow unsafe protocols to be used, like ``ext``.
+
+        :param kwargs:
+            Additional arguments to be passed to the ``git remote add`` command.
+
+        :return:
+            New :class:`Remote` instance
+
+        :raise git.exc.GitCommandError:
+            In case an origin with that name already exists.
+        """
+        scmd = "add"
+        kwargs["insert_kwargs_after"] = scmd
+        url = Git.polish_url(url)
+        if not allow_unsafe_protocols:
+            Git.check_unsafe_protocols(url)
+        repo.git.remote(scmd, "--", name, url, **kwargs)
+        return cls(repo, name)
+
+    # `add` is an alias.
+    @classmethod
+    def add(cls, repo: "Repo", name: str, url: str, **kwargs: Any) -> "Remote":
+        return cls.create(repo, name, url, **kwargs)
+
+    @classmethod
+    def remove(cls, repo: "Repo", name: str) -> str:
+        """Remove the remote with the given name.
+
+        :return:
+            The passed remote name to remove
+        """
+        repo.git.remote("rm", name)
+        if isinstance(name, cls):
+            name._clear_cache()
+        return name
+
+    @classmethod
+    def rm(cls, repo: "Repo", name: str) -> str:
+        """Alias of remove.
+        Remove the remote with the given name.
+
+        :return:
+            The passed remote name to remove
+        """
+        return cls.remove(repo, name)
+
+    def rename(self, new_name: str) -> "Remote":
+        """Rename self to the given `new_name`.
+
+        :return:
+            self
+        """
+        if self.name == new_name:
+            return self
+
+        self.repo.git.remote("rename", self.name, new_name)
+        self.name = new_name
+        self._clear_cache()
+
+        return self
+
+    def update(self, **kwargs: Any) -> "Remote":
+        """Fetch all changes for this remote, including new branches which will be
+        forced in (in case your local remote branch is not part the new remote branch's
+        ancestry anymore).
+
+        :param kwargs:
+            Additional arguments passed to ``git remote update``.
+
+        :return:
+            self
+        """
+        scmd = "update"
+        kwargs["insert_kwargs_after"] = scmd
+        self.repo.git.remote(scmd, self.name, **kwargs)
+        return self
+
+    def _get_fetch_info_from_stderr(
+        self,
+        proc: "Git.AutoInterrupt",
+        progress: Union[Callable[..., Any], RemoteProgress, None],
+        kill_after_timeout: Union[None, float] = None,
+    ) -> IterableList["FetchInfo"]:
+        progress = to_progress_instance(progress)
+
+        # Skip first line as it is some remote info we are not interested in.
+        output: IterableList["FetchInfo"] = IterableList("name")
+
+        # Lines which are no progress are fetch info lines.
+        # This also waits for the command to finish.
+        # Skip some progress lines that don't provide relevant information.
+        fetch_info_lines = []
+        # Basically we want all fetch info lines which appear to be in regular form, and
+        # thus have a command character. Everything else we ignore.
+        cmds = set(FetchInfo._flag_map.keys())
+
+        progress_handler = progress.new_message_handler()
+        handle_process_output(
+            proc,
+            None,
+            progress_handler,
+            finalizer=None,
+            decode_streams=False,
+            kill_after_timeout=kill_after_timeout,
+        )
+
+        stderr_text = progress.error_lines and "\n".join(progress.error_lines) or ""
+        proc.wait(stderr=stderr_text)
+        if stderr_text:
+            _logger.warning("Error lines received while fetching: %s", stderr_text)
+
+        for line in progress.other_lines:
+            line = force_text(line)
+            for cmd in cmds:
+                if len(line) > 1 and line[0] == " " and line[1] == cmd:
+                    fetch_info_lines.append(line)
+                    continue
+
+        # Read head information.
+        fetch_head = SymbolicReference(self.repo, "FETCH_HEAD")
+        with open(fetch_head.abspath, "rb") as fp:
+            fetch_head_info = [line.decode(defenc) for line in fp.readlines()]
+
+        l_fil = len(fetch_info_lines)
+        l_fhi = len(fetch_head_info)
+        if l_fil != l_fhi:
+            msg = "Fetch head lines do not match lines provided via progress information\n"
+            msg += "length of progress lines %i should be equal to lines in FETCH_HEAD file %i\n"
+            msg += "Will ignore extra progress lines or fetch head lines."
+            msg %= (l_fil, l_fhi)
+            _logger.debug(msg)
+            _logger.debug(b"info lines: " + str(fetch_info_lines).encode("UTF-8"))
+            _logger.debug(b"head info: " + str(fetch_head_info).encode("UTF-8"))
+            if l_fil < l_fhi:
+                fetch_head_info = fetch_head_info[:l_fil]
+            else:
+                fetch_info_lines = fetch_info_lines[:l_fhi]
+            # END truncate correct list
+        # END sanity check + sanitization
+
+        for err_line, fetch_line in zip(fetch_info_lines, fetch_head_info):
+            try:
+                output.append(FetchInfo._from_line(self.repo, err_line, fetch_line))
+            except ValueError as exc:
+                _logger.debug("Caught error while parsing line: %s", exc)
+                _logger.warning("Git informed while fetching: %s", err_line.strip())
+        return output
+
+    def _get_push_info(
+        self,
+        proc: "Git.AutoInterrupt",
+        progress: Union[Callable[..., Any], RemoteProgress, None],
+        kill_after_timeout: Union[None, float] = None,
+    ) -> PushInfoList:
+        progress = to_progress_instance(progress)
+
+        # Read progress information from stderr.
+        # We hope stdout can hold all the data, it should...
+        # Read the lines manually as it will use carriage returns between the messages
+        # to override the previous one. This is why we read the bytes manually.
+        progress_handler = progress.new_message_handler()
+        output: PushInfoList = PushInfoList()
+
+        def stdout_handler(line: str) -> None:
+            try:
+                output.append(PushInfo._from_line(self, line))
+            except ValueError:
+                # If an error happens, additional info is given which we parse below.
+                pass
+
+        handle_process_output(
+            proc,
+            stdout_handler,
+            progress_handler,
+            finalizer=None,
+            decode_streams=False,
+            kill_after_timeout=kill_after_timeout,
+        )
+        stderr_text = progress.error_lines and "\n".join(progress.error_lines) or ""
+        try:
+            proc.wait(stderr=stderr_text)
+        except Exception as e:
+            # This is different than fetch (which fails if there is any stderr
+            # even if there is an output).
+            if not output:
+                raise
+            elif stderr_text:
+                _logger.warning("Error lines received while fetching: %s", stderr_text)
+                output.error = e
+
+        return output
+
+    def _assert_refspec(self) -> None:
+        """Turns out we can't deal with remotes if the refspec is missing."""
+        config = self.config_reader
+        unset = "placeholder"
+        try:
+            if config.get_value("fetch", default=unset) is unset:
+                msg = "Remote '%s' has no refspec set.\n"
+                msg += "You can set it as follows:"
+                msg += " 'git config --add \"remote.%s.fetch +refs/heads/*:refs/heads/*\"'."
+                raise AssertionError(msg % (self.name, self.name))
+        finally:
+            config.release()
+
+    def fetch(
+        self,
+        refspec: Union[str, List[str], None] = None,
+        progress: Union[RemoteProgress, None, "UpdateProgress"] = None,
+        verbose: bool = True,
+        kill_after_timeout: Union[None, float] = None,
+        allow_unsafe_protocols: bool = False,
+        allow_unsafe_options: bool = False,
+        **kwargs: Any,
+    ) -> IterableList[FetchInfo]:
+        """Fetch the latest changes for this remote.
+
+        :param refspec:
+            A "refspec" is used by fetch and push to describe the mapping
+            between remote ref and local ref. They are combined with a colon in
+            the format ``<src>:<dst>``, preceded by an optional plus sign, ``+``.
+            For example: ``git fetch $URL refs/heads/master:refs/heads/origin`` means
+            "grab the master branch head from the $URL and store it as my origin
+            branch head". And ``git push $URL refs/heads/master:refs/heads/to-upstream``
+            means "publish my master branch head as to-upstream branch at $URL".
+            See also :manpage:`git-push(1)`.
+
+            Taken from the git manual, :manpage:`gitglossary(7)`.
+
+            Fetch supports multiple refspecs (as the underlying :manpage:`git-fetch(1)`
+            does) - supplying a list rather than a string for 'refspec' will make use of
+            this facility.
+
+        :param progress:
+            See the :meth:`push` method.
+
+        :param verbose:
+            Boolean for verbose output.
+
+        :param kill_after_timeout:
+            To specify a timeout in seconds for the git command, after which the process
+            should be killed. It is set to ``None`` by default.
+
+        :param allow_unsafe_protocols:
+            Allow unsafe protocols to be used, like ``ext``.
+
+        :param allow_unsafe_options:
+            Allow unsafe options to be used, like ``--upload-pack``.
+
+        :param kwargs:
+            Additional arguments to be passed to :manpage:`git-fetch(1)`.
+
+        :return:
+            IterableList(FetchInfo, ...) list of :class:`FetchInfo` instances providing
+            detailed information about the fetch results
+
+        :note:
+            As fetch does not provide progress information to non-ttys, we cannot make
+            it available here unfortunately as in the :meth:`push` method.
+        """
+        if refspec is None:
+            # No argument refspec, then ensure the repo's config has a fetch refspec.
+            self._assert_refspec()
+
+        kwargs = add_progress(kwargs, self.repo.git, progress)
+        if isinstance(refspec, list):
+            args: Sequence[Optional[str]] = refspec
+        else:
+            args = [refspec]
+
+        if not allow_unsafe_protocols:
+            for ref in args:
+                if ref:
+                    Git.check_unsafe_protocols(ref)
+
+        if not allow_unsafe_options:
+            Git.check_unsafe_options(options=list(kwargs.keys()), unsafe_options=self.unsafe_git_fetch_options)
+
+        proc = self.repo.git.fetch(
+            "--", self, *args, as_process=True, with_stdout=False, universal_newlines=True, v=verbose, **kwargs
+        )
+        res = self._get_fetch_info_from_stderr(proc, progress, kill_after_timeout=kill_after_timeout)
+        if hasattr(self.repo.odb, "update_cache"):
+            self.repo.odb.update_cache()
+        return res
+
+    def pull(
+        self,
+        refspec: Union[str, List[str], None] = None,
+        progress: Union[RemoteProgress, "UpdateProgress", None] = None,
+        kill_after_timeout: Union[None, float] = None,
+        allow_unsafe_protocols: bool = False,
+        allow_unsafe_options: bool = False,
+        **kwargs: Any,
+    ) -> IterableList[FetchInfo]:
+        """Pull changes from the given branch, being the same as a fetch followed by a
+        merge of branch with your local branch.
+
+        :param refspec:
+            See :meth:`fetch` method.
+
+        :param progress:
+            See :meth:`push` method.
+
+        :param kill_after_timeout:
+            See :meth:`fetch` method.
+
+        :param allow_unsafe_protocols:
+            Allow unsafe protocols to be used, like ``ext``.
+
+        :param allow_unsafe_options:
+            Allow unsafe options to be used, like ``--upload-pack``.
+
+        :param kwargs:
+            Additional arguments to be passed to :manpage:`git-pull(1)`.
+
+        :return:
+            Please see :meth:`fetch` method.
+        """
+        if refspec is None:
+            # No argument refspec, then ensure the repo's config has a fetch refspec.
+            self._assert_refspec()
+        kwargs = add_progress(kwargs, self.repo.git, progress)
+
+        refspec = Git._unpack_args(refspec or [])
+        if not allow_unsafe_protocols:
+            for ref in refspec:
+                Git.check_unsafe_protocols(ref)
+
+        if not allow_unsafe_options:
+            Git.check_unsafe_options(options=list(kwargs.keys()), unsafe_options=self.unsafe_git_pull_options)
+
+        proc = self.repo.git.pull(
+            "--", self, refspec, with_stdout=False, as_process=True, universal_newlines=True, v=True, **kwargs
+        )
+        res = self._get_fetch_info_from_stderr(proc, progress, kill_after_timeout=kill_after_timeout)
+        if hasattr(self.repo.odb, "update_cache"):
+            self.repo.odb.update_cache()
+        return res
+
+    def push(
+        self,
+        refspec: Union[str, List[str], None] = None,
+        progress: Union[RemoteProgress, "UpdateProgress", Callable[..., RemoteProgress], None] = None,
+        kill_after_timeout: Union[None, float] = None,
+        allow_unsafe_protocols: bool = False,
+        allow_unsafe_options: bool = False,
+        **kwargs: Any,
+    ) -> PushInfoList:
+        """Push changes from source branch in refspec to target branch in refspec.
+
+        :param refspec:
+            See :meth:`fetch` method.
+
+        :param progress:
+            Can take one of many value types:
+
+            * ``None``, to discard progress information.
+            * A function (callable) that is called with the progress information.
+              Signature: ``progress(op_code, cur_count, max_count=None, message='')``.
+              See :meth:`RemoteProgress.update <git.util.RemoteProgress.update>` for a
+              description of all arguments given to the function.
+            * An instance of a class derived from :class:`~git.util.RemoteProgress` that
+              overrides the
+              :meth:`RemoteProgress.update <git.util.RemoteProgress.update>` method.
+
+        :note:
+            No further progress information is returned after push returns.
+
+        :param kill_after_timeout:
+            To specify a timeout in seconds for the git command, after which the process
+            should be killed. It is set to ``None`` by default.
+
+        :param allow_unsafe_protocols:
+            Allow unsafe protocols to be used, like ``ext``.
+
+        :param allow_unsafe_options:
+            Allow unsafe options to be used, like ``--receive-pack``.
+
+        :param kwargs:
+            Additional arguments to be passed to :manpage:`git-push(1)`.
+
+        :return:
+            A :class:`PushInfoList` object, where each list member represents an
+            individual head which had been updated on the remote side.
+
+            If the push contains rejected heads, these will have the
+            :const:`PushInfo.ERROR` bit set in their flags.
+
+            If the operation fails completely, the length of the returned
+            :class:`PushInfoList` will be 0.
+
+            Call :meth:`~PushInfoList.raise_if_error` on the returned object to raise on
+            any failure.
+        """
+        kwargs = add_progress(kwargs, self.repo.git, progress)
+
+        refspec = Git._unpack_args(refspec or [])
+        if not allow_unsafe_protocols:
+            for ref in refspec:
+                Git.check_unsafe_protocols(ref)
+
+        if not allow_unsafe_options:
+            Git.check_unsafe_options(options=list(kwargs.keys()), unsafe_options=self.unsafe_git_push_options)
+
+        proc = self.repo.git.push(
+            "--",
+            self,
+            refspec,
+            porcelain=True,
+            as_process=True,
+            universal_newlines=True,
+            kill_after_timeout=kill_after_timeout,
+            **kwargs,
+        )
+        return self._get_push_info(proc, progress, kill_after_timeout=kill_after_timeout)
+
+    @property
+    def config_reader(self) -> SectionConstraint[GitConfigParser]:
+        """
+        :return:
+            :class:`~git.config.GitConfigParser` compatible object able to read options
+            for only our remote. Hence you may simply type ``config.get("pushurl")`` to
+            obtain the information.
+        """
+        return self._config_reader
+
+    def _clear_cache(self) -> None:
+        try:
+            del self._config_reader
+        except AttributeError:
+            pass
+        # END handle exception
+
+    @property
+    def config_writer(self) -> SectionConstraint:
+        """
+        :return:
+            :class:`~git.config.GitConfigParser`-compatible object able to write options
+            for this remote.
+
+        :note:
+            You can only own one writer at a time - delete it to release the
+            configuration file and make it usable by others.
+
+            To assure consistent results, you should only query options through the
+            writer. Once you are done writing, you are free to use the config reader
+            once again.
+        """
+        writer = self.repo.config_writer()
+
+        # Clear our cache to ensure we re-read the possibly changed configuration.
+        self._clear_cache()
+        return SectionConstraint(writer, self._config_section_name())

.venv/lib/python3.11/site-packages/git/repo/__init__.py

@@ -0,0 +1,8 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""Initialize the repo package."""
+
+__all__ = ["Repo"]
+
+from .base import Repo

.venv/lib/python3.11/site-packages/git/repo/base.py

@@ -0,0 +1,1638 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+from __future__ import annotations
+
+__all__ = ["Repo"]
+
+import gc
+import logging
+import os
+import os.path as osp
+from pathlib import Path
+import re
+import shlex
+import sys
+import warnings
+
+import gitdb
+from gitdb.db.loose import LooseObjectDB
+from gitdb.exc import BadObject
+
+from git.cmd import Git, handle_process_output
+from git.compat import defenc, safe_decode
+from git.config import GitConfigParser
+from git.db import GitCmdObjectDB
+from git.exc import (
+    GitCommandError,
+    InvalidGitRepositoryError,
+    NoSuchPathError,
+)
+from git.index import IndexFile
+from git.objects import Submodule, RootModule, Commit
+from git.refs import HEAD, Head, Reference, TagReference
+from git.remote import Remote, add_progress, to_progress_instance
+from git.util import (
+    Actor,
+    cygpath,
+    expand_path,
+    finalize_process,
+    hex_to_bin,
+    remove_password_if_present,
+)
+
+from .fun import (
+    find_submodule_git_dir,
+    find_worktree_git_dir,
+    is_git_dir,
+    rev_parse,
+    touch,
+)
+
+# typing ------------------------------------------------------
+
+from git.types import (
+    CallableProgress,
+    Commit_ish,
+    Lit_config_levels,
+    PathLike,
+    TBD,
+    Tree_ish,
+    assert_never,
+)
+from typing import (
+    Any,
+    BinaryIO,
+    Callable,
+    Dict,
+    Iterator,
+    List,
+    Mapping,
+    NamedTuple,
+    Optional,
+    Sequence,
+    TYPE_CHECKING,
+    TextIO,
+    Tuple,
+    Type,
+    Union,
+    cast,
+)
+
+from git.types import ConfigLevels_Tup, TypedDict
+
+if TYPE_CHECKING:
+    from git.objects import Tree
+    from git.objects.submodule.base import UpdateProgress
+    from git.refs.symbolic import SymbolicReference
+    from git.remote import RemoteProgress
+    from git.util import IterableList
+
+# -----------------------------------------------------------
+
+_logger = logging.getLogger(__name__)
+
+
+class BlameEntry(NamedTuple):
+    commit: Dict[str, Commit]
+    linenos: range
+    orig_path: Optional[str]
+    orig_linenos: range
+
+
+class Repo:
+    """Represents a git repository and allows you to query references, create commit
+    information, generate diffs, create and clone repositories, and query the log.
+
+    The following attributes are worth using:
+
+    * :attr:`working_dir` is the working directory of the git command, which is the
+      working tree directory if available or the ``.git`` directory in case of bare
+      repositories.
+
+    * :attr:`working_tree_dir` is the working tree directory, but will return ``None``
+      if we are a bare repository.
+
+    * :attr:`git_dir` is the ``.git`` repository directory, which is always set.
+    """
+
+    DAEMON_EXPORT_FILE = "git-daemon-export-ok"
+
+    # Must exist, or  __del__  will fail in case we raise on `__init__()`.
+    git = cast("Git", None)
+
+    working_dir: PathLike
+    """The working directory of the git command."""
+
+    _working_tree_dir: Optional[PathLike] = None
+
+    git_dir: PathLike
+    """The ``.git`` repository directory."""
+
+    _common_dir: PathLike = ""
+
+    # Precompiled regex
+    re_whitespace = re.compile(r"\s+")
+    re_hexsha_only = re.compile(r"^[0-9A-Fa-f]{40}$")
+    re_hexsha_shortened = re.compile(r"^[0-9A-Fa-f]{4,40}$")
+    re_envvars = re.compile(r"(\$(\{\s?)?[a-zA-Z_]\w*(\}\s?)?|%\s?[a-zA-Z_]\w*\s?%)")
+    re_author_committer_start = re.compile(r"^(author|committer)")
+    re_tab_full_line = re.compile(r"^\t(.*)$")
+
+    unsafe_git_clone_options = [
+        # Executes arbitrary commands:
+        "--upload-pack",
+        "-u",
+        # Can override configuration variables that execute arbitrary commands:
+        "--config",
+        "-c",
+    ]
+    """Options to :manpage:`git-clone(1)` that allow arbitrary commands to be executed.
+
+    The ``--upload-pack``/``-u`` option allows users to execute arbitrary commands
+    directly:
+    https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---upload-packltupload-packgt
+
+    The ``--config``/``-c`` option allows users to override configuration variables like
+    ``protocol.allow`` and ``core.gitProxy`` to execute arbitrary commands:
+    https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---configltkeygtltvaluegt
+    """
+
+    # Invariants
+    config_level: ConfigLevels_Tup = ("system", "user", "global", "repository")
+    """Represents the configuration level of a configuration file."""
+
+    # Subclass configuration
+    GitCommandWrapperType = Git
+    """Subclasses may easily bring in their own custom types by placing a constructor or
+    type here."""
+
+    def __init__(
+        self,
+        path: Optional[PathLike] = None,
+        odbt: Type[LooseObjectDB] = GitCmdObjectDB,
+        search_parent_directories: bool = False,
+        expand_vars: bool = True,
+    ) -> None:
+        R"""Create a new :class:`Repo` instance.
+
+        :param path:
+            The path to either the worktree directory or the .git directory itself::
+
+                repo = Repo("/Users/mtrier/Development/git-python")
+                repo = Repo("/Users/mtrier/Development/git-python.git")
+                repo = Repo("~/Development/git-python.git")
+                repo = Repo("$REPOSITORIES/Development/git-python.git")
+                repo = Repo(R"C:\Users\mtrier\Development\git-python\.git")
+
+            - In *Cygwin*, `path` may be a ``cygdrive/...`` prefixed path.
+            - If `path` is ``None`` or an empty string, :envvar:`GIT_DIR` is used. If
+              that environment variable is absent or empty, the current directory is
+              used.
+
+        :param odbt:
+            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.
+
+        :param search_parent_directories:
+            If ``True``, all parent directories will be searched for a valid repo as
+            well.
+
+            Please note that this was the default behaviour in older versions of
+            GitPython, which is considered a bug though.
+
+        :raise git.exc.InvalidGitRepositoryError:
+
+        :raise git.exc.NoSuchPathError:
+
+        :return:
+            :class:`Repo`
+        """
+
+        epath = path or os.getenv("GIT_DIR")
+        if not epath:
+            epath = os.getcwd()
+        if Git.is_cygwin():
+            # Given how the tests are written, this seems more likely to catch Cygwin
+            # git used from Windows than Windows git used from Cygwin. Therefore
+            # changing to Cygwin-style paths is the relevant operation.
+            epath = cygpath(str(epath))
+
+        epath = epath or path or os.getcwd()
+        if not isinstance(epath, str):
+            epath = str(epath)
+        if expand_vars and re.search(self.re_envvars, epath):
+            warnings.warn(
+                "The use of environment variables in paths is deprecated"
+                + "\nfor security reasons and may be removed in the future!!",
+                stacklevel=1,
+            )
+        epath = expand_path(epath, expand_vars)
+        if epath is not None:
+            if not os.path.exists(epath):
+                raise NoSuchPathError(epath)
+
+        # Walk up the path to find the `.git` dir.
+        curpath = epath
+        git_dir = None
+        while curpath:
+            # ABOUT osp.NORMPATH
+            # It's important to normalize the paths, as submodules will otherwise
+            # initialize their repo instances with paths that depend on path-portions
+            # that will not exist after being removed. It's just cleaner.
+            if is_git_dir(curpath):
+                git_dir = curpath
+                # from man git-config : core.worktree
+                # Set the path to the root of the working tree. If GIT_COMMON_DIR
+                # environment variable is set, core.worktree is ignored and not used for
+                # determining the root of working tree. This can be overridden by the
+                # GIT_WORK_TREE environment variable. The value can be an absolute path
+                # or relative to the path to the .git directory, which is either
+                # specified by GIT_DIR, or automatically discovered. If GIT_DIR is
+                # specified but none of GIT_WORK_TREE and core.worktree is specified,
+                # the current working directory is regarded as the top level of your
+                # working tree.
+                self._working_tree_dir = os.path.dirname(git_dir)
+                if os.environ.get("GIT_COMMON_DIR") is None:
+                    gitconf = self._config_reader("repository", git_dir)
+                    if gitconf.has_option("core", "worktree"):
+                        self._working_tree_dir = gitconf.get("core", "worktree")
+                if "GIT_WORK_TREE" in os.environ:
+                    self._working_tree_dir = os.getenv("GIT_WORK_TREE")
+                break
+
+            dotgit = osp.join(curpath, ".git")
+            sm_gitpath = find_submodule_git_dir(dotgit)
+            if sm_gitpath is not None:
+                git_dir = osp.normpath(sm_gitpath)
+
+            sm_gitpath = find_submodule_git_dir(dotgit)
+            if sm_gitpath is None:
+                sm_gitpath = find_worktree_git_dir(dotgit)
+
+            if sm_gitpath is not None:
+                git_dir = expand_path(sm_gitpath, expand_vars)
+                self._working_tree_dir = curpath
+                break
+
+            if not search_parent_directories:
+                break
+            curpath, tail = osp.split(curpath)
+            if not tail:
+                break
+        # END while curpath
+
+        if git_dir is None:
+            raise InvalidGitRepositoryError(epath)
+        self.git_dir = git_dir
+
+        self._bare = False
+        try:
+            self._bare = self.config_reader("repository").getboolean("core", "bare")
+        except Exception:
+            # Let's not assume the option exists, although it should.
+            pass
+
+        try:
+            common_dir = (Path(self.git_dir) / "commondir").read_text().splitlines()[0].strip()
+            self._common_dir = osp.join(self.git_dir, common_dir)
+        except OSError:
+            self._common_dir = ""
+
+        # Adjust the working directory in case we are actually bare - we didn't know
+        # that in the first place.
+        if self._bare:
+            self._working_tree_dir = None
+        # END working dir handling
+
+        self.working_dir: PathLike = self._working_tree_dir or self.common_dir
+        self.git = self.GitCommandWrapperType(self.working_dir)
+
+        # Special handling, in special times.
+        rootpath = osp.join(self.common_dir, "objects")
+        if issubclass(odbt, GitCmdObjectDB):
+            self.odb = odbt(rootpath, self.git)
+        else:
+            self.odb = odbt(rootpath)
+
+    def __enter__(self) -> "Repo":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def __del__(self) -> None:
+        try:
+            self.close()
+        except Exception:
+            pass
+
+    def close(self) -> None:
+        if self.git:
+            self.git.clear_cache()
+            # Tempfiles objects on Windows are holding references to open files until
+            # they are collected by the garbage collector, thus preventing deletion.
+            # TODO: Find these references and ensure they are closed and deleted
+            # synchronously rather than forcing a gc collection.
+            if sys.platform == "win32":
+                gc.collect()
+            gitdb.util.mman.collect()
+            if sys.platform == "win32":
+                gc.collect()
+
+    def __eq__(self, rhs: object) -> bool:
+        if isinstance(rhs, Repo):
+            return self.git_dir == rhs.git_dir
+        return False
+
+    def __ne__(self, rhs: object) -> bool:
+        return not self.__eq__(rhs)
+
+    def __hash__(self) -> int:
+        return hash(self.git_dir)
+
+    @property
+    def description(self) -> str:
+        """The project's description"""
+        filename = osp.join(self.git_dir, "description")
+        with open(filename, "rb") as fp:
+            return fp.read().rstrip().decode(defenc)
+
+    @description.setter
+    def description(self, descr: str) -> None:
+        filename = osp.join(self.git_dir, "description")
+        with open(filename, "wb") as fp:
+            fp.write((descr + "\n").encode(defenc))
+
+    @property
+    def working_tree_dir(self) -> Optional[PathLike]:
+        """
+        :return:
+            The working tree directory of our git repository.
+            If this is a bare repository, ``None`` is returned.
+        """
+        return self._working_tree_dir
+
+    @property
+    def common_dir(self) -> PathLike:
+        """
+        :return:
+            The git dir that holds everything except possibly HEAD, FETCH_HEAD,
+            ORIG_HEAD, COMMIT_EDITMSG, index, and logs/.
+        """
+        return self._common_dir or self.git_dir
+
+    @property
+    def bare(self) -> bool:
+        """:return: ``True`` if the repository is bare"""
+        return self._bare
+
+    @property
+    def heads(self) -> "IterableList[Head]":
+        """A list of :class:`~git.refs.head.Head` objects representing the branch heads
+        in this repo.
+
+        :return:
+            ``git.IterableList(Head, ...)``
+        """
+        return Head.list_items(self)
+
+    @property
+    def branches(self) -> "IterableList[Head]":
+        """Alias for heads.
+        A list of :class:`~git.refs.head.Head` objects representing the branch heads
+        in this repo.
+
+        :return:
+            ``git.IterableList(Head, ...)``
+        """
+        return self.heads
+
+    @property
+    def references(self) -> "IterableList[Reference]":
+        """A list of :class:`~git.refs.reference.Reference` objects representing tags,
+        heads and remote references.
+
+        :return:
+            ``git.IterableList(Reference, ...)``
+        """
+        return Reference.list_items(self)
+
+    @property
+    def refs(self) -> "IterableList[Reference]":
+        """Alias for references.
+        A list of :class:`~git.refs.reference.Reference` objects representing tags,
+        heads and remote references.
+
+        :return:
+            ``git.IterableList(Reference, ...)``
+        """
+        return self.references
+
+    @property
+    def index(self) -> "IndexFile":
+        """
+        :return:
+            A :class:`~git.index.base.IndexFile` representing this repository's index.
+
+        :note:
+            This property can be expensive, as the returned
+            :class:`~git.index.base.IndexFile` will be reinitialized.
+            It is recommended to reuse the object.
+        """
+        return IndexFile(self)
+
+    @property
+    def head(self) -> "HEAD":
+        """
+        :return:
+            :class:`~git.refs.head.HEAD` object pointing to the current head reference
+        """
+        return HEAD(self, "HEAD")
+
+    @property
+    def remotes(self) -> "IterableList[Remote]":
+        """A list of :class:`~git.remote.Remote` objects allowing to access and
+        manipulate remotes.
+
+        :return:
+            ``git.IterableList(Remote, ...)``
+        """
+        return Remote.list_items(self)
+
+    def remote(self, name: str = "origin") -> "Remote":
+        """:return: The remote with the specified name
+
+        :raise ValueError:
+            If no remote with such a name exists.
+        """
+        r = Remote(self, name)
+        if not r.exists():
+            raise ValueError("Remote named '%s' didn't exist" % name)
+        return r
+
+    # { Submodules
+
+    @property
+    def submodules(self) -> "IterableList[Submodule]":
+        """
+        :return:
+            git.IterableList(Submodule, ...) of direct submodules available from the
+            current head
+        """
+        return Submodule.list_items(self)
+
+    def submodule(self, name: str) -> "Submodule":
+        """:return: The submodule with the given name
+
+        :raise ValueError:
+            If no such submodule exists.
+        """
+        try:
+            return self.submodules[name]
+        except IndexError as e:
+            raise ValueError("Didn't find submodule named %r" % name) from e
+        # END exception handling
+
+    def create_submodule(self, *args: Any, **kwargs: Any) -> Submodule:
+        """Create a new submodule.
+
+        :note:
+            For a description of the applicable parameters, see the documentation of
+            :meth:`Submodule.add <git.objects.submodule.base.Submodule.add>`.
+
+        :return:
+            The created submodule.
+        """
+        return Submodule.add(self, *args, **kwargs)
+
+    def iter_submodules(self, *args: Any, **kwargs: Any) -> Iterator[Submodule]:
+        """An iterator yielding Submodule instances.
+
+        See the :class:`~git.objects.util.Traversable` interface for a description of `args`
+        and `kwargs`.
+
+        :return:
+            Iterator
+        """
+        return RootModule(self).traverse(*args, **kwargs)
+
+    def submodule_update(self, *args: Any, **kwargs: Any) -> Iterator[Submodule]:
+        """Update the submodules, keeping the repository consistent as it will
+        take the previous state into consideration.
+
+        :note:
+            For more information, please see the documentation of
+            :meth:`RootModule.update <git.objects.submodule.root.RootModule.update>`.
+        """
+        return RootModule(self).update(*args, **kwargs)
+
+    # }END submodules
+
+    @property
+    def tags(self) -> "IterableList[TagReference]":
+        """A list of :class:`~git.refs.tag.TagReference` objects that are available in
+        this repo.
+
+        :return:
+            ``git.IterableList(TagReference, ...)``
+        """
+        return TagReference.list_items(self)
+
+    def tag(self, path: PathLike) -> TagReference:
+        """
+        :return:
+            :class:`~git.refs.tag.TagReference` object, reference pointing to a
+            :class:`~git.objects.commit.Commit` or tag
+
+        :param path:
+            Path to the tag reference, e.g. ``0.1.5`` or ``tags/0.1.5``.
+        """
+        full_path = self._to_full_tag_path(path)
+        return TagReference(self, full_path)
+
+    @staticmethod
+    def _to_full_tag_path(path: PathLike) -> str:
+        path_str = str(path)
+        if path_str.startswith(TagReference._common_path_default + "/"):
+            return path_str
+        if path_str.startswith(TagReference._common_default + "/"):
+            return Reference._common_path_default + "/" + path_str
+        else:
+            return TagReference._common_path_default + "/" + path_str
+
+    def create_head(
+        self,
+        path: PathLike,
+        commit: Union["SymbolicReference", "str"] = "HEAD",
+        force: bool = False,
+        logmsg: Optional[str] = None,
+    ) -> "Head":
+        """Create a new head within the repository.
+
+        :note:
+            For more documentation, please see the
+            :meth:`Head.create <git.refs.head.Head.create>` method.
+
+        :return:
+            Newly created :class:`~git.refs.head.Head` Reference.
+        """
+        return Head.create(self, path, commit, logmsg, force)
+
+    def delete_head(self, *heads: "Union[str, Head]", **kwargs: Any) -> None:
+        """Delete the given heads.
+
+        :param kwargs:
+            Additional keyword arguments to be passed to :manpage:`git-branch(1)`.
+        """
+        return Head.delete(self, *heads, **kwargs)
+
+    def create_tag(
+        self,
+        path: PathLike,
+        ref: Union[str, "SymbolicReference"] = "HEAD",
+        message: Optional[str] = None,
+        force: bool = False,
+        **kwargs: Any,
+    ) -> TagReference:
+        """Create a new tag reference.
+
+        :note:
+            For more documentation, please see the
+            :meth:`TagReference.create <git.refs.tag.TagReference.create>` method.
+
+        :return:
+            :class:`~git.refs.tag.TagReference` object
+        """
+        return TagReference.create(self, path, ref, message, force, **kwargs)
+
+    def delete_tag(self, *tags: TagReference) -> None:
+        """Delete the given tag references."""
+        return TagReference.delete(self, *tags)
+
+    def create_remote(self, name: str, url: str, **kwargs: Any) -> Remote:
+        """Create a new remote.
+
+        For more information, please see the documentation of the
+        :meth:`Remote.create <git.remote.Remote.create>` method.
+
+        :return:
+            :class:`~git.remote.Remote` reference
+        """
+        return Remote.create(self, name, url, **kwargs)
+
+    def delete_remote(self, remote: "Remote") -> str:
+        """Delete the given remote."""
+        return Remote.remove(self, remote)
+
+    def _get_config_path(self, config_level: Lit_config_levels, git_dir: Optional[PathLike] = None) -> str:
+        if git_dir is None:
+            git_dir = self.git_dir
+        # We do not support an absolute path of the gitconfig on Windows.
+        # Use the global config instead.
+        if sys.platform == "win32" and config_level == "system":
+            config_level = "global"
+
+        if config_level == "system":
+            return "/etc/gitconfig"
+        elif config_level == "user":
+            config_home = os.environ.get("XDG_CONFIG_HOME") or osp.join(os.environ.get("HOME", "~"), ".config")
+            return osp.normpath(osp.expanduser(osp.join(config_home, "git", "config")))
+        elif config_level == "global":
+            return osp.normpath(osp.expanduser("~/.gitconfig"))
+        elif config_level == "repository":
+            repo_dir = self._common_dir or git_dir
+            if not repo_dir:
+                raise NotADirectoryError
+            else:
+                return osp.normpath(osp.join(repo_dir, "config"))
+        else:
+            assert_never(  # type: ignore[unreachable]
+                config_level,
+                ValueError(f"Invalid configuration level: {config_level!r}"),
+            )
+
+    def config_reader(
+        self,
+        config_level: Optional[Lit_config_levels] = None,
+    ) -> GitConfigParser:
+        """
+        :return:
+            :class:`~git.config.GitConfigParser` allowing to read the full git
+            configuration, but not to write it.
+
+            The configuration will include values from the system, user and repository
+            configuration files.
+
+        :param config_level:
+            For possible values, see the :meth:`config_writer` method. If ``None``, all
+            applicable levels will be used. Specify a level in case you know which file
+            you wish to read to prevent reading multiple files.
+
+        :note:
+            On Windows, system configuration cannot currently be read as the path is
+            unknown, instead the global path will be used.
+        """
+        return self._config_reader(config_level=config_level)
+
+    def _config_reader(
+        self,
+        config_level: Optional[Lit_config_levels] = None,
+        git_dir: Optional[PathLike] = None,
+    ) -> GitConfigParser:
+        if config_level is None:
+            files = [
+                self._get_config_path(cast(Lit_config_levels, f), git_dir)
+                for f in self.config_level
+                if cast(Lit_config_levels, f)
+            ]
+        else:
+            files = [self._get_config_path(config_level, git_dir)]
+        return GitConfigParser(files, read_only=True, repo=self)
+
+    def config_writer(self, config_level: Lit_config_levels = "repository") -> GitConfigParser:
+        """
+        :return:
+            A :class:`~git.config.GitConfigParser` allowing to write values of the
+            specified configuration file level. Config writers should be retrieved, used
+            to change the configuration, and written right away as they will lock the
+            configuration file in question and prevent other's to write it.
+
+        :param config_level:
+            One of the following values:
+
+            * ``"system"`` = system wide configuration file
+            * ``"global"`` = user level configuration file
+            * ``"`repository"`` = configuration file for this repository only
+        """
+        return GitConfigParser(self._get_config_path(config_level), read_only=False, repo=self, merge_includes=False)
+
+    def commit(self, rev: Union[str, Commit_ish, None] = None) -> Commit:
+        """The :class:`~git.objects.commit.Commit` object for the specified revision.
+
+        :param rev:
+            Revision specifier, see :manpage:`git-rev-parse(1)` for viable options.
+
+        :return:
+            :class:`~git.objects.commit.Commit`
+        """
+        if rev is None:
+            return self.head.commit
+        return self.rev_parse(str(rev) + "^0")
+
+    def iter_trees(self, *args: Any, **kwargs: Any) -> Iterator["Tree"]:
+        """:return: Iterator yielding :class:`~git.objects.tree.Tree` objects
+
+        :note:
+            Accepts all arguments known to the :meth:`iter_commits` method.
+        """
+        return (c.tree for c in self.iter_commits(*args, **kwargs))
+
+    def tree(self, rev: Union[Tree_ish, str, None] = None) -> "Tree":
+        """The :class:`~git.objects.tree.Tree` object for the given tree-ish revision.
+
+        Examples::
+
+              repo.tree(repo.heads[0])
+
+        :param rev:
+            A revision pointing to a Treeish (being a commit or tree).
+
+        :return:
+            :class:`~git.objects.tree.Tree`
+
+        :note:
+            If you need a non-root level tree, find it by iterating the root tree.
+            Otherwise it cannot know about its path relative to the repository root and
+            subsequent operations might have unexpected results.
+        """
+        if rev is None:
+            return self.head.commit.tree
+        return self.rev_parse(str(rev) + "^{tree}")
+
+    def iter_commits(
+        self,
+        rev: Union[str, Commit, "SymbolicReference", None] = None,
+        paths: Union[PathLike, Sequence[PathLike]] = "",
+        **kwargs: Any,
+    ) -> Iterator[Commit]:
+        """An iterator of :class:`~git.objects.commit.Commit` objects representing the
+        history of a given ref/commit.
+
+        :param rev:
+            Revision specifier, see :manpage:`git-rev-parse(1)` for viable options.
+            If ``None``, the active branch will be used.
+
+        :param paths:
+            An optional path or a list of paths. If set, only commits that include the
+            path or paths will be returned.
+
+        :param kwargs:
+            Arguments to be passed to :manpage:`git-rev-list(1)`.
+            Common ones are ``max_count`` and ``skip``.
+
+        :note:
+            To receive only commits between two named revisions, use the
+            ``"revA...revB"`` revision specifier.
+
+        :return:
+            Iterator of :class:`~git.objects.commit.Commit` objects
+        """
+        if rev is None:
+            rev = self.head.commit
+
+        return Commit.iter_items(self, rev, paths, **kwargs)
+
+    def merge_base(self, *rev: TBD, **kwargs: Any) -> List[Commit]:
+        R"""Find the closest common ancestor for the given revision
+        (:class:`~git.objects.commit.Commit`\s, :class:`~git.refs.tag.Tag`\s,
+        :class:`~git.refs.reference.Reference`\s, etc.).
+
+        :param rev:
+            At least two revs to find the common ancestor for.
+
+        :param kwargs:
+            Additional arguments to be passed to the ``repo.git.merge_base()`` command
+            which does all the work.
+
+        :return:
+            A list of :class:`~git.objects.commit.Commit` objects. If ``--all`` was
+            not passed as a keyword argument, the list will have at max one
+            :class:`~git.objects.commit.Commit`, or is empty if no common merge base
+            exists.
+
+        :raise ValueError:
+            If fewer than two revisions are provided.
+        """
+        if len(rev) < 2:
+            raise ValueError("Please specify at least two revs, got only %i" % len(rev))
+        # END handle input
+
+        res: List[Commit] = []
+        try:
+            lines: List[str] = self.git.merge_base(*rev, **kwargs).splitlines()
+        except GitCommandError as err:
+            if err.status == 128:
+                raise
+            # END handle invalid rev
+            # Status code 1 is returned if there is no merge-base.
+            # (See: https://github.com/git/git/blob/v2.44.0/builtin/merge-base.c#L19)
+            return res
+        # END exception handling
+
+        for line in lines:
+            res.append(self.commit(line))
+        # END for each merge-base
+
+        return res
+
+    def is_ancestor(self, ancestor_rev: Commit, rev: Commit) -> bool:
+        """Check if a commit is an ancestor of another.
+
+        :param ancestor_rev:
+            Rev which should be an ancestor.
+
+        :param rev:
+            Rev to test against `ancestor_rev`.
+
+        :return:
+            ``True`` if `ancestor_rev` is an ancestor to `rev`.
+        """
+        try:
+            self.git.merge_base(ancestor_rev, rev, is_ancestor=True)
+        except GitCommandError as err:
+            if err.status == 1:
+                return False
+            raise
+        return True
+
+    def is_valid_object(self, sha: str, object_type: Union[str, None] = None) -> bool:
+        try:
+            complete_sha = self.odb.partial_to_complete_sha_hex(sha)
+            object_info = self.odb.info(complete_sha)
+            if object_type:
+                if object_info.type == object_type.encode():
+                    return True
+                else:
+                    _logger.debug(
+                        "Commit hash points to an object of type '%s'. Requested were objects of type '%s'",
+                        object_info.type.decode(),
+                        object_type,
+                    )
+                    return False
+            else:
+                return True
+        except BadObject:
+            _logger.debug("Commit hash is invalid.")
+            return False
+
+    def _get_daemon_export(self) -> bool:
+        if self.git_dir:
+            filename = osp.join(self.git_dir, self.DAEMON_EXPORT_FILE)
+        return osp.exists(filename)
+
+    def _set_daemon_export(self, value: object) -> None:
+        if self.git_dir:
+            filename = osp.join(self.git_dir, self.DAEMON_EXPORT_FILE)
+        fileexists = osp.exists(filename)
+        if value and not fileexists:
+            touch(filename)
+        elif not value and fileexists:
+            os.unlink(filename)
+
+    @property
+    def daemon_export(self) -> bool:
+        """If True, git-daemon may export this repository"""
+        return self._get_daemon_export()
+
+    @daemon_export.setter
+    def daemon_export(self, value: object) -> None:
+        self._set_daemon_export(value)
+
+    def _get_alternates(self) -> List[str]:
+        """The list of alternates for this repo from which objects can be retrieved.
+
+        :return:
+            List of strings being pathnames of alternates
+        """
+        if self.git_dir:
+            alternates_path = osp.join(self.git_dir, "objects", "info", "alternates")
+
+        if osp.exists(alternates_path):
+            with open(alternates_path, "rb") as f:
+                alts = f.read().decode(defenc)
+            return alts.strip().splitlines()
+        return []
+
+    def _set_alternates(self, alts: List[str]) -> None:
+        """Set the alternates.
+
+        :param alts:
+            The array of string paths representing the alternates at which git should
+            look for objects, i.e. ``/home/user/repo/.git/objects``.
+
+        :raise git.exc.NoSuchPathError:
+
+        :note:
+            The method does not check for the existence of the paths in `alts`, as the
+            caller is responsible.
+        """
+        alternates_path = osp.join(self.common_dir, "objects", "info", "alternates")
+        if not alts:
+            if osp.isfile(alternates_path):
+                os.remove(alternates_path)
+        else:
+            with open(alternates_path, "wb") as f:
+                f.write("\n".join(alts).encode(defenc))
+
+    @property
+    def alternates(self) -> List[str]:
+        """Retrieve a list of alternates paths or set a list paths to be used as alternates"""
+        return self._get_alternates()
+
+    @alternates.setter
+    def alternates(self, alts: List[str]) -> None:
+        self._set_alternates(alts)
+
+    def is_dirty(
+        self,
+        index: bool = True,
+        working_tree: bool = True,
+        untracked_files: bool = False,
+        submodules: bool = True,
+        path: Optional[PathLike] = None,
+    ) -> bool:
+        """
+        :return:
+            ``True`` if the repository is considered dirty. By default it will react
+            like a :manpage:`git-status(1)` without untracked files, hence it is dirty
+            if the index or the working copy have changes.
+        """
+        if self._bare:
+            # Bare repositories with no associated working directory are
+            # always considered to be clean.
+            return False
+
+        # Start from the one which is fastest to evaluate.
+        default_args = ["--abbrev=40", "--full-index", "--raw"]
+        if not submodules:
+            default_args.append("--ignore-submodules")
+        if path:
+            default_args.extend(["--", str(path)])
+        if index:
+            # diff index against HEAD.
+            if osp.isfile(self.index.path) and len(self.git.diff("--cached", *default_args)):
+                return True
+        # END index handling
+        if working_tree:
+            # diff index against working tree.
+            if len(self.git.diff(*default_args)):
+                return True
+        # END working tree handling
+        if untracked_files:
+            if len(self._get_untracked_files(path, ignore_submodules=not submodules)):
+                return True
+        # END untracked files
+        return False
+
+    @property
+    def untracked_files(self) -> List[str]:
+        """
+        :return:
+            list(str,...)
+
+            Files currently untracked as they have not been staged yet. Paths are
+            relative to the current working directory of the git command.
+
+        :note:
+            Ignored files will not appear here, i.e. files mentioned in ``.gitignore``.
+
+        :note:
+            This property is expensive, as no cache is involved. To process the result,
+            please consider caching it yourself.
+        """
+        return self._get_untracked_files()
+
+    def _get_untracked_files(self, *args: Any, **kwargs: Any) -> List[str]:
+        # Make sure we get all files, not only untracked directories.
+        proc = self.git.status(*args, porcelain=True, untracked_files=True, as_process=True, **kwargs)
+        # Untracked files prefix in porcelain mode
+        prefix = "?? "
+        untracked_files = []
+        for line in proc.stdout:
+            line = line.decode(defenc)
+            if not line.startswith(prefix):
+                continue
+            filename = line[len(prefix) :].rstrip("\n")
+            # Special characters are escaped
+            if filename[0] == filename[-1] == '"':
+                filename = filename[1:-1]
+                # WHATEVER ... it's a mess, but works for me
+                filename = filename.encode("ascii").decode("unicode_escape").encode("latin1").decode(defenc)
+            untracked_files.append(filename)
+        finalize_process(proc)
+        return untracked_files
+
+    def ignored(self, *paths: PathLike) -> List[str]:
+        """Checks if paths are ignored via ``.gitignore``.
+
+        This does so using the :manpage:`git-check-ignore(1)` method.
+
+        :param paths:
+            List of paths to check whether they are ignored or not.
+
+        :return:
+            Subset of those paths which are ignored
+        """
+        try:
+            proc: str = self.git.check_ignore(*paths)
+        except GitCommandError as err:
+            if err.status == 1:
+                # If return code is 1, this means none of the items in *paths are
+                # ignored by Git, so return an empty list.
+                return []
+            else:
+                # Raise the exception on all other return codes.
+                raise
+
+        return proc.replace("\\\\", "\\").replace('"', "").split("\n")
+
+    @property
+    def active_branch(self) -> Head:
+        """The name of the currently active branch.
+
+        :raise TypeError:
+            If HEAD is detached.
+
+        :return:
+            :class:`~git.refs.head.Head` to the active branch
+        """
+        # reveal_type(self.head.reference)  # => Reference
+        return self.head.reference
+
+    def blame_incremental(self, rev: str | HEAD | None, file: str, **kwargs: Any) -> Iterator["BlameEntry"]:
+        """Iterator for blame information for the given file at the given revision.
+
+        Unlike :meth:`blame`, this does not return the actual file's contents, only a
+        stream of :class:`BlameEntry` tuples.
+
+        :param rev:
+            Revision specifier. If ``None``, the blame will include all the latest
+            uncommitted changes. Otherwise, anything successfully parsed by
+            :manpage:`git-rev-parse(1)` is a valid option.
+
+        :return:
+            Lazy iterator of :class:`BlameEntry` tuples, where the commit indicates the
+            commit to blame for the line, and range indicates a span of line numbers in
+            the resulting file.
+
+        If you combine all line number ranges outputted by this command, you should get
+        a continuous range spanning all line numbers in the file.
+        """
+
+        data: bytes = self.git.blame(rev, "--", file, p=True, incremental=True, stdout_as_string=False, **kwargs)
+        commits: Dict[bytes, Commit] = {}
+
+        stream = (line for line in data.split(b"\n") if line)
+        while True:
+            try:
+                # When exhausted, causes a StopIteration, terminating this function.
+                line = next(stream)
+            except StopIteration:
+                return
+            split_line = line.split()
+            hexsha, orig_lineno_b, lineno_b, num_lines_b = split_line
+            lineno = int(lineno_b)
+            num_lines = int(num_lines_b)
+            orig_lineno = int(orig_lineno_b)
+            if hexsha not in commits:
+                # Now read the next few lines and build up a dict of properties for this
+                # commit.
+                props: Dict[bytes, bytes] = {}
+                while True:
+                    try:
+                        line = next(stream)
+                    except StopIteration:
+                        return
+                    if line == b"boundary":
+                        # "boundary" indicates a root commit and occurs instead of the
+                        # "previous" tag.
+                        continue
+
+                    tag, value = line.split(b" ", 1)
+                    props[tag] = value
+                    if tag == b"filename":
+                        # "filename" formally terminates the entry for --incremental.
+                        orig_filename = value
+                        break
+
+                c = Commit(
+                    self,
+                    hex_to_bin(hexsha),
+                    author=Actor(
+                        safe_decode(props[b"author"]),
+                        safe_decode(props[b"author-mail"].lstrip(b"<").rstrip(b">")),
+                    ),
+                    authored_date=int(props[b"author-time"]),
+                    committer=Actor(
+                        safe_decode(props[b"committer"]),
+                        safe_decode(props[b"committer-mail"].lstrip(b"<").rstrip(b">")),
+                    ),
+                    committed_date=int(props[b"committer-time"]),
+                )
+                commits[hexsha] = c
+            else:
+                # Discard all lines until we find "filename" which is guaranteed to be
+                # the last line.
+                while True:
+                    try:
+                        # Will fail if we reach the EOF unexpectedly.
+                        line = next(stream)
+                    except StopIteration:
+                        return
+                    tag, value = line.split(b" ", 1)
+                    if tag == b"filename":
+                        orig_filename = value
+                        break
+
+            yield BlameEntry(
+                commits[hexsha],
+                range(lineno, lineno + num_lines),
+                safe_decode(orig_filename),
+                range(orig_lineno, orig_lineno + num_lines),
+            )
+
+    def blame(
+        self,
+        rev: Union[str, HEAD, None],
+        file: str,
+        incremental: bool = False,
+        rev_opts: Optional[List[str]] = None,
+        **kwargs: Any,
+    ) -> List[List[Commit | List[str | bytes] | None]] | Iterator[BlameEntry] | None:
+        """The blame information for the given file at the given revision.
+
+        :param rev:
+            Revision specifier. If ``None``, the blame will include all the latest
+            uncommitted changes. Otherwise, anything successfully parsed by
+            :manpage:`git-rev-parse(1)` is a valid option.
+
+        :return:
+            list: [git.Commit, list: [<line>]]
+
+            A list of lists associating a :class:`~git.objects.commit.Commit` object
+            with a list of lines that changed within the given commit. The
+            :class:`~git.objects.commit.Commit` objects will be given in order of
+            appearance.
+        """
+        if incremental:
+            return self.blame_incremental(rev, file, **kwargs)
+        rev_opts = rev_opts or []
+        data: bytes = self.git.blame(rev, *rev_opts, "--", file, p=True, stdout_as_string=False, **kwargs)
+        commits: Dict[str, Commit] = {}
+        blames: List[List[Commit | List[str | bytes] | None]] = []
+
+        class InfoTD(TypedDict, total=False):
+            sha: str
+            id: str
+            filename: str
+            summary: str
+            author: str
+            author_email: str
+            author_date: int
+            committer: str
+            committer_email: str
+            committer_date: int
+
+        info: InfoTD = {}
+
+        keepends = True
+        for line_bytes in data.splitlines(keepends):
+            try:
+                line_str = line_bytes.rstrip().decode(defenc)
+            except UnicodeDecodeError:
+                firstpart = ""
+                parts = []
+                is_binary = True
+            else:
+                # As we don't have an idea when the binary data ends, as it could
+                # contain multiple newlines in the process. So we rely on being able to
+                # decode to tell us what it is. This can absolutely fail even on text
+                # files, but even if it does, we should be fine treating it as binary
+                # instead.
+                parts = self.re_whitespace.split(line_str, 1)
+                firstpart = parts[0]
+                is_binary = False
+            # END handle decode of line
+
+            if self.re_hexsha_only.search(firstpart):
+                # handles
+                # 634396b2f541a9f2d58b00be1a07f0c358b999b3 1 1 7        - indicates blame-data start
+                # 634396b2f541a9f2d58b00be1a07f0c358b999b3 2 2          - indicates
+                # another line of blame with the same data
+                digits = parts[-1].split(" ")
+                if len(digits) == 3:
+                    info = {"id": firstpart}
+                    blames.append([None, []])
+                elif info["id"] != firstpart:
+                    info = {"id": firstpart}
+                    blames.append([commits.get(firstpart), []])
+                # END blame data initialization
+            else:
+                m = self.re_author_committer_start.search(firstpart)
+                if m:
+                    # handles:
+                    # author Tom Preston-Werner
+                    # author-mail <tom@mojombo.com>
+                    # author-time 1192271832
+                    # author-tz -0700
+                    # committer Tom Preston-Werner
+                    # committer-mail <tom@mojombo.com>
+                    # committer-time 1192271832
+                    # committer-tz -0700  - IGNORED BY US
+                    role = m.group(0)
+                    if role == "author":
+                        if firstpart.endswith("-mail"):
+                            info["author_email"] = parts[-1]
+                        elif firstpart.endswith("-time"):
+                            info["author_date"] = int(parts[-1])
+                        elif role == firstpart:
+                            info["author"] = parts[-1]
+                    elif role == "committer":
+                        if firstpart.endswith("-mail"):
+                            info["committer_email"] = parts[-1]
+                        elif firstpart.endswith("-time"):
+                            info["committer_date"] = int(parts[-1])
+                        elif role == firstpart:
+                            info["committer"] = parts[-1]
+                    # END distinguish mail,time,name
+                else:
+                    # handle
+                    # filename lib/grit.rb
+                    # summary add Blob
+                    # <and rest>
+                    if firstpart.startswith("filename"):
+                        info["filename"] = parts[-1]
+                    elif firstpart.startswith("summary"):
+                        info["summary"] = parts[-1]
+                    elif firstpart == "":
+                        if info:
+                            sha = info["id"]
+                            c = commits.get(sha)
+                            if c is None:
+                                c = Commit(
+                                    self,
+                                    hex_to_bin(sha),
+                                    author=Actor._from_string(f"{info['author']} {info['author_email']}"),
+                                    authored_date=info["author_date"],
+                                    committer=Actor._from_string(f"{info['committer']} {info['committer_email']}"),
+                                    committed_date=info["committer_date"],
+                                )
+                                commits[sha] = c
+                            blames[-1][0] = c
+                            # END if commit objects needs initial creation
+
+                            if blames[-1][1] is not None:
+                                line: str | bytes
+                                if not is_binary:
+                                    if line_str and line_str[0] == "\t":
+                                        line_str = line_str[1:]
+                                    line = line_str
+                                else:
+                                    line = line_bytes
+                                    # NOTE: We are actually parsing lines out of binary
+                                    # data, which can lead to the binary being split up
+                                    # along the newline separator. We will append this
+                                    # to the blame we are currently looking at, even
+                                    # though it should be concatenated with the last
+                                    # line we have seen.
+                                blames[-1][1].append(line)
+
+                            info = {"id": sha}
+                        # END if we collected commit info
+                    # END distinguish filename,summary,rest
+                # END distinguish author|committer vs filename,summary,rest
+            # END distinguish hexsha vs other information
+        return blames
+
+    @classmethod
+    def init(
+        cls,
+        path: Union[PathLike, None] = None,
+        mkdir: bool = True,
+        odbt: Type[GitCmdObjectDB] = GitCmdObjectDB,
+        expand_vars: bool = True,
+        **kwargs: Any,
+    ) -> "Repo":
+        """Initialize a git repository at the given path if specified.
+
+        :param path:
+            The full path to the repo (traditionally ends with ``/<name>.git``). Or
+            ``None``, in which case the repository will be created in the current
+            working directory.
+
+        :param mkdir:
+            If specified, will create the repository directory if it doesn't already
+            exist. Creates the directory with a mode=0755.
+            Only effective if a path is explicitly given.
+
+        :param odbt:
+            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.
+
+        :param expand_vars:
+            If specified, environment variables will not be escaped. This can lead to
+            information disclosure, allowing attackers to access the contents of
+            environment variables.
+
+        :param kwargs:
+            Keyword arguments serving as additional options to the
+            :manpage:`git-init(1)` command.
+
+        :return:
+            :class:`Repo` (the newly created repo)
+        """
+        if path:
+            path = expand_path(path, expand_vars)
+        if mkdir and path and not osp.exists(path):
+            os.makedirs(path, 0o755)
+
+        # git command automatically chdir into the directory
+        git = cls.GitCommandWrapperType(path)
+        git.init(**kwargs)
+        return cls(path, odbt=odbt)
+
+    @classmethod
+    def _clone(
+        cls,
+        git: "Git",
+        url: PathLike,
+        path: PathLike,
+        odb_default_type: Type[GitCmdObjectDB],
+        progress: Union["RemoteProgress", "UpdateProgress", Callable[..., "RemoteProgress"], None] = None,
+        multi_options: Optional[List[str]] = None,
+        allow_unsafe_protocols: bool = False,
+        allow_unsafe_options: bool = False,
+        **kwargs: Any,
+    ) -> "Repo":
+        odbt = kwargs.pop("odbt", odb_default_type)
+
+        # When pathlib.Path or other class-based path is passed
+        if not isinstance(path, str):
+            path = str(path)
+
+        ## A bug win cygwin's Git, when `--bare` or `--separate-git-dir`
+        #  it prepends the cwd or(?) the `url` into the `path, so::
+        #        git clone --bare  /cygwin/d/foo.git  C:\\Work
+        #  becomes::
+        #        git clone --bare  /cygwin/d/foo.git  /cygwin/d/C:\\Work
+        #
+        clone_path = Git.polish_url(path) if Git.is_cygwin() and "bare" in kwargs else path
+        sep_dir = kwargs.get("separate_git_dir")
+        if sep_dir:
+            kwargs["separate_git_dir"] = Git.polish_url(sep_dir)
+        multi = None
+        if multi_options:
+            multi = shlex.split(" ".join(multi_options))
+
+        if not allow_unsafe_protocols:
+            Git.check_unsafe_protocols(str(url))
+        if not allow_unsafe_options:
+            Git.check_unsafe_options(options=list(kwargs.keys()), unsafe_options=cls.unsafe_git_clone_options)
+        if not allow_unsafe_options and multi_options:
+            Git.check_unsafe_options(options=multi_options, unsafe_options=cls.unsafe_git_clone_options)
+
+        proc = git.clone(
+            multi,
+            "--",
+            Git.polish_url(str(url)),
+            clone_path,
+            with_extended_output=True,
+            as_process=True,
+            v=True,
+            universal_newlines=True,
+            **add_progress(kwargs, git, progress),
+        )
+        if progress:
+            handle_process_output(
+                proc,
+                None,
+                to_progress_instance(progress).new_message_handler(),
+                finalize_process,
+                decode_streams=False,
+            )
+        else:
+            (stdout, stderr) = proc.communicate()
+            cmdline = getattr(proc, "args", "")
+            cmdline = remove_password_if_present(cmdline)
+
+            _logger.debug("Cmd(%s)'s unused stdout: %s", cmdline, stdout)
+            finalize_process(proc, stderr=stderr)
+
+        # Our git command could have a different working dir than our actual
+        # environment, hence we prepend its working dir if required.
+        if not osp.isabs(path):
+            path = osp.join(git._working_dir, path) if git._working_dir is not None else path
+
+        repo = cls(path, odbt=odbt)
+
+        # Retain env values that were passed to _clone().
+        repo.git.update_environment(**git.environment())
+
+        # Adjust remotes - there may be operating systems which use backslashes, These
+        # might be given as initial paths, but when handling the config file that
+        # contains the remote from which we were clones, git stops liking it as it will
+        # escape the backslashes. Hence we undo the escaping just to be sure.
+        if repo.remotes:
+            with repo.remotes[0].config_writer as writer:
+                writer.set_value("url", Git.polish_url(repo.remotes[0].url))
+        # END handle remote repo
+        return repo
+
+    def clone(
+        self,
+        path: PathLike,
+        progress: Optional[CallableProgress] = None,
+        multi_options: Optional[List[str]] = None,
+        allow_unsafe_protocols: bool = False,
+        allow_unsafe_options: bool = False,
+        **kwargs: Any,
+    ) -> "Repo":
+        """Create a clone from this repository.
+
+        :param path:
+            The full path of the new repo (traditionally ends with ``./<name>.git``).
+
+        :param progress:
+            See :meth:`Remote.push <git.remote.Remote.push>`.
+
+        :param multi_options:
+            A list of :manpage:`git-clone(1)` options that can be provided multiple
+            times.
+
+            One option per list item which is passed exactly as specified to clone.
+            For example::
+
+                [
+                    "--config core.filemode=false",
+                    "--config core.ignorecase",
+                    "--recurse-submodule=repo1_path",
+                    "--recurse-submodule=repo2_path",
+                ]
+
+        :param allow_unsafe_protocols:
+            Allow unsafe protocols to be used, like ``ext``.
+
+        :param allow_unsafe_options:
+            Allow unsafe options to be used, like ``--upload-pack``.
+
+        :param kwargs:
+            * ``odbt`` = ObjectDatabase Type, allowing to determine the object database
+              implementation used by the returned :class:`Repo` instance.
+            * All remaining keyword arguments are given to the :manpage:`git-clone(1)`
+              command.
+
+        :return:
+            :class:`Repo` (the newly cloned repo)
+        """
+        return self._clone(
+            self.git,
+            self.common_dir,
+            path,
+            type(self.odb),
+            progress,
+            multi_options,
+            allow_unsafe_protocols=allow_unsafe_protocols,
+            allow_unsafe_options=allow_unsafe_options,
+            **kwargs,
+        )
+
+    @classmethod
+    def clone_from(
+        cls,
+        url: PathLike,
+        to_path: PathLike,
+        progress: CallableProgress = None,
+        env: Optional[Mapping[str, str]] = None,
+        multi_options: Optional[List[str]] = None,
+        allow_unsafe_protocols: bool = False,
+        allow_unsafe_options: bool = False,
+        **kwargs: Any,
+    ) -> "Repo":
+        """Create a clone from the given URL.
+
+        :param url:
+            Valid git url, see: https://git-scm.com/docs/git-clone#URLS
+
+        :param to_path:
+            Path to which the repository should be cloned to.
+
+        :param progress:
+            See :meth:`Remote.push <git.remote.Remote.push>`.
+
+        :param env:
+            Optional dictionary containing the desired environment variables.
+
+            Note: Provided variables will be used to update the execution environment
+            for ``git``. If some variable is not specified in `env` and is defined in
+            :attr:`os.environ`, value from :attr:`os.environ` will be used. If you want
+            to unset some variable, consider providing empty string as its value.
+
+        :param multi_options:
+            See the :meth:`clone` method.
+
+        :param allow_unsafe_protocols:
+            Allow unsafe protocols to be used, like ``ext``.
+
+        :param allow_unsafe_options:
+            Allow unsafe options to be used, like ``--upload-pack``.
+
+        :param kwargs:
+            See the :meth:`clone` method.
+
+        :return:
+            :class:`Repo` instance pointing to the cloned directory.
+        """
+        git = cls.GitCommandWrapperType(os.getcwd())
+        if env is not None:
+            git.update_environment(**env)
+        return cls._clone(
+            git,
+            url,
+            to_path,
+            GitCmdObjectDB,
+            progress,
+            multi_options,
+            allow_unsafe_protocols=allow_unsafe_protocols,
+            allow_unsafe_options=allow_unsafe_options,
+            **kwargs,
+        )
+
+    def archive(
+        self,
+        ostream: Union[TextIO, BinaryIO],
+        treeish: Optional[str] = None,
+        prefix: Optional[str] = None,
+        **kwargs: Any,
+    ) -> Repo:
+        """Archive the tree at the given revision.
+
+        :param ostream:
+            File-compatible stream object to which the archive will be written as bytes.
+
+        :param treeish:
+            The treeish name/id, defaults to active branch.
+
+        :param prefix:
+            The optional prefix to prepend to each filename in the archive.
+
+        :param kwargs:
+            Additional arguments passed to :manpage:`git-archive(1)`:
+
+            * Use the ``format`` argument to define the kind of format. Use specialized
+              ostreams to write any format supported by Python.
+            * You may specify the special ``path`` keyword, which may either be a
+              repository-relative path to a directory or file to place into the archive,
+              or a list or tuple of multiple paths.
+
+        :raise git.exc.GitCommandError:
+            If something went wrong.
+
+        :return:
+            self
+        """
+        if treeish is None:
+            treeish = self.head.commit
+        if prefix and "prefix" not in kwargs:
+            kwargs["prefix"] = prefix
+        kwargs["output_stream"] = ostream
+        path = kwargs.pop("path", [])
+        path = cast(Union[PathLike, List[PathLike], Tuple[PathLike, ...]], path)
+        if not isinstance(path, (tuple, list)):
+            path = [path]
+        # END ensure paths is list (or tuple)
+        self.git.archive("--", treeish, *path, **kwargs)
+        return self
+
+    def has_separate_working_tree(self) -> bool:
+        """
+        :return:
+            True if our :attr:`git_dir` is not at the root of our
+            :attr:`working_tree_dir`, but a ``.git`` file with a platform-agnostic
+            symbolic link. Our :attr:`git_dir` will be wherever the ``.git`` file points
+            to.
+
+        :note:
+            Bare repositories will always return ``False`` here.
+        """
+        if self.bare:
+            return False
+        if self.working_tree_dir:
+            return osp.isfile(osp.join(self.working_tree_dir, ".git"))
+        else:
+            return False  # Or raise Error?
+
+    rev_parse = rev_parse
+
+    def __repr__(self) -> str:
+        clazz = self.__class__
+        return "<%s.%s %r>" % (clazz.__module__, clazz.__name__, self.git_dir)
+
+    def currently_rebasing_on(self) -> Commit | None:
+        """
+        :return:
+            The commit which is currently being replayed while rebasing.
+
+            ``None`` if we are not currently rebasing.
+        """
+        if self.git_dir:
+            rebase_head_file = osp.join(self.git_dir, "REBASE_HEAD")
+        if not osp.isfile(rebase_head_file):
+            return None
+        with open(rebase_head_file, "rt") as f:
+            content = f.readline().strip()
+        return self.commit(content)

.venv/lib/python3.11/site-packages/git/repo/fun.py

@@ -0,0 +1,425 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+"""General repository-related functions."""
+
+from __future__ import annotations
+
+__all__ = [
+    "rev_parse",
+    "is_git_dir",
+    "touch",
+    "find_submodule_git_dir",
+    "name_to_object",
+    "short_to_long",
+    "deref_tag",
+    "to_commit",
+    "find_worktree_git_dir",
+]
+
+import os
+import os.path as osp
+from pathlib import Path
+import stat
+from string import digits
+
+from gitdb.exc import BadName, BadObject
+
+from git.cmd import Git
+from git.exc import WorkTreeRepositoryUnsupported
+from git.objects import Object
+from git.refs import SymbolicReference
+from git.util import cygpath, bin_to_hex, hex_to_bin
+
+# Typing ----------------------------------------------------------------------
+
+from typing import Optional, TYPE_CHECKING, Union, cast, overload
+
+from git.types import AnyGitObject, Literal, PathLike
+
+if TYPE_CHECKING:
+    from git.db import GitCmdObjectDB
+    from git.objects import Commit, TagObject
+    from git.refs.reference import Reference
+    from git.refs.tag import Tag
+
+    from .base import Repo
+
+# ----------------------------------------------------------------------------
+
+
+def touch(filename: str) -> str:
+    with open(filename, "ab"):
+        pass
+    return filename
+
+
+def is_git_dir(d: PathLike) -> bool:
+    """This is taken from the git setup.c:is_git_directory function.
+
+    :raise git.exc.WorkTreeRepositoryUnsupported:
+        If it sees a worktree directory. It's quite hacky to do that here, but at least
+        clearly indicates that we don't support it. There is the unlikely danger to
+        throw if we see directories which just look like a worktree dir, but are none.
+    """
+    if osp.isdir(d):
+        if (osp.isdir(osp.join(d, "objects")) or "GIT_OBJECT_DIRECTORY" in os.environ) and osp.isdir(
+            osp.join(d, "refs")
+        ):
+            headref = osp.join(d, "HEAD")
+            return osp.isfile(headref) or (osp.islink(headref) and os.readlink(headref).startswith("refs"))
+        elif (
+            osp.isfile(osp.join(d, "gitdir"))
+            and osp.isfile(osp.join(d, "commondir"))
+            and osp.isfile(osp.join(d, "gitfile"))
+        ):
+            raise WorkTreeRepositoryUnsupported(d)
+    return False
+
+
+def find_worktree_git_dir(dotgit: PathLike) -> Optional[str]:
+    """Search for a gitdir for this worktree."""
+    try:
+        statbuf = os.stat(dotgit)
+    except OSError:
+        return None
+    if not stat.S_ISREG(statbuf.st_mode):
+        return None
+
+    try:
+        lines = Path(dotgit).read_text().splitlines()
+        for key, value in [line.strip().split(": ") for line in lines]:
+            if key == "gitdir":
+                return value
+    except ValueError:
+        pass
+    return None
+
+
+def find_submodule_git_dir(d: PathLike) -> Optional[PathLike]:
+    """Search for a submodule repo."""
+    if is_git_dir(d):
+        return d
+
+    try:
+        with open(d) as fp:
+            content = fp.read().rstrip()
+    except IOError:
+        # It's probably not a file.
+        pass
+    else:
+        if content.startswith("gitdir: "):
+            path = content[8:]
+
+            if Git.is_cygwin():
+                # Cygwin creates submodules prefixed with `/cygdrive/...`.
+                # Cygwin git understands Cygwin paths much better than Windows ones.
+                # Also the Cygwin tests are assuming Cygwin paths.
+                path = cygpath(path)
+            if not osp.isabs(path):
+                path = osp.normpath(osp.join(osp.dirname(d), path))
+            return find_submodule_git_dir(path)
+    # END handle exception
+    return None
+
+
+def short_to_long(odb: "GitCmdObjectDB", hexsha: str) -> Optional[bytes]:
+    """
+    :return:
+        Long hexadecimal sha1 from the given less than 40 byte hexsha, or ``None`` if no
+        candidate could be found.
+
+    :param hexsha:
+        hexsha with less than 40 bytes.
+    """
+    try:
+        return bin_to_hex(odb.partial_to_complete_sha_hex(hexsha))
+    except BadObject:
+        return None
+    # END exception handling
+
+
+@overload
+def name_to_object(repo: "Repo", name: str, return_ref: Literal[False] = ...) -> AnyGitObject: ...
+
+
+@overload
+def name_to_object(repo: "Repo", name: str, return_ref: Literal[True]) -> Union[AnyGitObject, SymbolicReference]: ...
+
+
+def name_to_object(repo: "Repo", name: str, return_ref: bool = False) -> Union[AnyGitObject, SymbolicReference]:
+    """
+    :return:
+        Object specified by the given name - hexshas (short and long) as well as
+        references are supported.
+
+    :param return_ref:
+        If ``True``, and name specifies a reference, we will return the reference
+        instead of the object. Otherwise it will raise :exc:`~gitdb.exc.BadObject` or
+        :exc:`~gitdb.exc.BadName`.
+    """
+    hexsha: Union[None, str, bytes] = None
+
+    # Is it a hexsha? Try the most common ones, which is 7 to 40.
+    if repo.re_hexsha_shortened.match(name):
+        if len(name) != 40:
+            # Find long sha for short sha.
+            hexsha = short_to_long(repo.odb, name)
+        else:
+            hexsha = name
+        # END handle short shas
+    # END find sha if it matches
+
+    # If we couldn't find an object for what seemed to be a short hexsha, try to find it
+    # as reference anyway, it could be named 'aaa' for instance.
+    if hexsha is None:
+        for base in (
+            "%s",
+            "refs/%s",
+            "refs/tags/%s",
+            "refs/heads/%s",
+            "refs/remotes/%s",
+            "refs/remotes/%s/HEAD",
+        ):
+            try:
+                hexsha = SymbolicReference.dereference_recursive(repo, base % name)
+                if return_ref:
+                    return SymbolicReference(repo, base % name)
+                # END handle symbolic ref
+                break
+            except ValueError:
+                pass
+        # END for each base
+    # END handle hexsha
+
+    # Didn't find any ref, this is an error.
+    if return_ref:
+        raise BadObject("Couldn't find reference named %r" % name)
+    # END handle return ref
+
+    # Tried everything ? fail.
+    if hexsha is None:
+        raise BadName(name)
+    # END assert hexsha was found
+
+    return Object.new_from_sha(repo, hex_to_bin(hexsha))
+
+
+def deref_tag(tag: "Tag") -> AnyGitObject:
+    """Recursively dereference a tag and return the resulting object."""
+    while True:
+        try:
+            tag = tag.object
+        except AttributeError:
+            break
+    # END dereference tag
+    return tag
+
+
+def to_commit(obj: Object) -> "Commit":
+    """Convert the given object to a commit if possible and return it."""
+    if obj.type == "tag":
+        obj = deref_tag(obj)
+
+    if obj.type != "commit":
+        raise ValueError("Cannot convert object %r to type commit" % obj)
+    # END verify type
+    return obj
+
+
+def rev_parse(repo: "Repo", rev: str) -> AnyGitObject:
+    """Parse a revision string. Like :manpage:`git-rev-parse(1)`.
+
+    :return:
+        `~git.objects.base.Object` at the given revision.
+
+        This may be any type of git object:
+
+        * :class:`Commit <git.objects.commit.Commit>`
+        * :class:`TagObject <git.objects.tag.TagObject>`
+        * :class:`Tree <git.objects.tree.Tree>`
+        * :class:`Blob <git.objects.blob.Blob>`
+
+    :param rev:
+        :manpage:`git-rev-parse(1)`-compatible revision specification as string.
+        Please see :manpage:`git-rev-parse(1)` for details.
+
+    :raise gitdb.exc.BadObject:
+        If the given revision could not be found.
+
+    :raise ValueError:
+        If `rev` couldn't be parsed.
+
+    :raise IndexError:
+        If an invalid reflog index is specified.
+    """
+    # Are we in colon search mode?
+    if rev.startswith(":/"):
+        # Colon search mode
+        raise NotImplementedError("commit by message search (regex)")
+    # END handle search
+
+    obj: Optional[AnyGitObject] = None
+    ref = None
+    output_type = "commit"
+    start = 0
+    parsed_to = 0
+    lr = len(rev)
+    while start < lr:
+        if rev[start] not in "^~:@":
+            start += 1
+            continue
+        # END handle start
+
+        token = rev[start]
+
+        if obj is None:
+            # token is a rev name.
+            if start == 0:
+                ref = repo.head.ref
+            else:
+                if token == "@":
+                    ref = cast("Reference", name_to_object(repo, rev[:start], return_ref=True))
+                else:
+                    obj = name_to_object(repo, rev[:start])
+                # END handle token
+            # END handle refname
+        else:
+            if ref is not None:
+                obj = cast("Commit", ref.commit)
+            # END handle ref
+        # END initialize obj on first token
+
+        start += 1
+
+        # Try to parse {type}.
+        if start < lr and rev[start] == "{":
+            end = rev.find("}", start)
+            if end == -1:
+                raise ValueError("Missing closing brace to define type in %s" % rev)
+            output_type = rev[start + 1 : end]  # Exclude brace.
+
+            # Handle type.
+            if output_type == "commit":
+                obj = cast("TagObject", obj)
+                if obj and obj.type == "tag":
+                    obj = deref_tag(obj)
+                else:
+                    # Cannot do anything for non-tags.
+                    pass
+                # END handle tag
+            elif output_type == "tree":
+                try:
+                    obj = cast(AnyGitObject, obj)
+                    obj = to_commit(obj).tree
+                except (AttributeError, ValueError):
+                    pass  # Error raised later.
+                # END exception handling
+            elif output_type in ("", "blob"):
+                obj = cast("TagObject", obj)
+                if obj and obj.type == "tag":
+                    obj = deref_tag(obj)
+                else:
+                    # Cannot do anything for non-tags.
+                    pass
+                # END handle tag
+            elif token == "@":
+                # try single int
+                assert ref is not None, "Require Reference to access reflog"
+                revlog_index = None
+                try:
+                    # Transform reversed index into the format of our revlog.
+                    revlog_index = -(int(output_type) + 1)
+                except ValueError as e:
+                    # TODO: Try to parse the other date options, using parse_date maybe.
+                    raise NotImplementedError("Support for additional @{...} modes not implemented") from e
+                # END handle revlog index
+
+                try:
+                    entry = ref.log_entry(revlog_index)
+                except IndexError as e:
+                    raise IndexError("Invalid revlog index: %i" % revlog_index) from e
+                # END handle index out of bound
+
+                obj = Object.new_from_sha(repo, hex_to_bin(entry.newhexsha))
+
+                # Make it pass the following checks.
+                output_type = ""
+            else:
+                raise ValueError("Invalid output type: %s ( in %s )" % (output_type, rev))
+            # END handle output type
+
+            # Empty output types don't require any specific type, its just about
+            # dereferencing tags.
+            if output_type and obj and obj.type != output_type:
+                raise ValueError("Could not accommodate requested object type %r, got %s" % (output_type, obj.type))
+            # END verify output type
+
+            start = end + 1  # Skip brace.
+            parsed_to = start
+            continue
+        # END parse type
+
+        # Try to parse a number.
+        num = 0
+        if token != ":":
+            found_digit = False
+            while start < lr:
+                if rev[start] in digits:
+                    num = num * 10 + int(rev[start])
+                    start += 1
+                    found_digit = True
+                else:
+                    break
+                # END handle number
+            # END number parse loop
+
+            # No explicit number given, 1 is the default. It could be 0 though.
+            if not found_digit:
+                num = 1
+            # END set default num
+        # END number parsing only if non-blob mode
+
+        parsed_to = start
+        # Handle hierarchy walk.
+        try:
+            obj = cast(AnyGitObject, obj)
+            if token == "~":
+                obj = to_commit(obj)
+                for _ in range(num):
+                    obj = obj.parents[0]
+                # END for each history item to walk
+            elif token == "^":
+                obj = to_commit(obj)
+                # Must be n'th parent.
+                if num:
+                    obj = obj.parents[num - 1]
+            elif token == ":":
+                if obj.type != "tree":
+                    obj = obj.tree
+                # END get tree type
+                obj = obj[rev[start:]]
+                parsed_to = lr
+            else:
+                raise ValueError("Invalid token: %r" % token)
+            # END end handle tag
+        except (IndexError, AttributeError) as e:
+            raise BadName(
+                f"Invalid revision spec '{rev}' - not enough parent commits to reach '{token}{int(num)}'"
+            ) from e
+        # END exception handling
+    # END parse loop
+
+    # Still no obj? It's probably a simple name.
+    if obj is None:
+        obj = name_to_object(repo, rev)
+        parsed_to = lr
+    # END handle simple name
+
+    if obj is None:
+        raise ValueError("Revision specifier could not be parsed: %s" % rev)
+
+    if parsed_to != lr:
+        raise ValueError("Didn't consume complete rev spec %s, consumed part: %s" % (rev, rev[:parsed_to]))
+
+    return obj

.venv/lib/python3.11/site-packages/git/types.py

@@ -0,0 +1,285 @@
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+import os
+import sys
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    List,
+    NoReturn,
+    Optional,
+    Sequence as Sequence,
+    Tuple,
+    TYPE_CHECKING,
+    Type,
+    TypeVar,
+    Union,
+)
+import warnings
+
+if sys.version_info >= (3, 8):
+    from typing import (
+        Literal,
+        Protocol,
+        SupportsIndex as SupportsIndex,
+        TypedDict,
+        runtime_checkable,
+    )
+else:
+    from typing_extensions import (
+        Literal,
+        Protocol,
+        SupportsIndex as SupportsIndex,
+        TypedDict,
+        runtime_checkable,
+    )
+
+if TYPE_CHECKING:
+    from git.objects import Commit, Tree, TagObject, Blob
+    from git.repo import Repo
+
+PathLike = Union[str, "os.PathLike[str]"]
+"""A :class:`str` (Unicode) based file or directory path."""
+
+TBD = Any
+"""Alias of :class:`~typing.Any`, when a type hint is meant to become more specific."""
+
+_T = TypeVar("_T")
+"""Type variable used internally in GitPython."""
+
+AnyGitObject = Union["Commit", "Tree", "TagObject", "Blob"]
+"""Union of the :class:`~git.objects.base.Object`-based types that represent actual git
+object types.
+
+As noted in :class:`~git.objects.base.Object`, which has further details, these are:
+
+* :class:`Blob <git.objects.blob.Blob>`
+* :class:`Tree <git.objects.tree.Tree>`
+* :class:`Commit <git.objects.commit.Commit>`
+* :class:`TagObject <git.objects.tag.TagObject>`
+
+Those GitPython classes represent the four git object types, per
+:manpage:`gitglossary(7)`:
+
+* "blob": https://git-scm.com/docs/gitglossary#def_blob_object
+* "tree object": https://git-scm.com/docs/gitglossary#def_tree_object
+* "commit object": https://git-scm.com/docs/gitglossary#def_commit_object
+* "tag object": https://git-scm.com/docs/gitglossary#def_tag_object
+
+For more general information on git objects and their types as git understands them:
+
+* "object": https://git-scm.com/docs/gitglossary#def_object
+* "object type": https://git-scm.com/docs/gitglossary#def_object_type
+
+:note:
+    See also the :class:`Tree_ish` and :class:`Commit_ish` unions.
+"""
+
+Tree_ish = Union["Commit", "Tree", "TagObject"]
+"""Union of :class:`~git.objects.base.Object`-based types that are typically tree-ish.
+
+See :manpage:`gitglossary(7)` on "tree-ish":
+https://git-scm.com/docs/gitglossary#def_tree-ish
+
+:note:
+    :class:`~git.objects.tree.Tree` and :class:`~git.objects.commit.Commit` are the
+    classes whose instances are all tree-ish. This union includes them, but also
+    :class:`~git.objects.tag.TagObject`, only **most** of whose instances are tree-ish.
+    Whether a particular :class:`~git.objects.tag.TagObject` peels (recursively
+    dereferences) to a tree or commit, rather than a blob, can in general only be known
+    at runtime. In practice, git tag objects are nearly always used for tagging commits,
+    and such tags are tree-ish because commits are tree-ish.
+
+:note:
+    See also the :class:`AnyGitObject` union of all four classes corresponding to git
+    object types.
+"""
+
+Commit_ish = Union["Commit", "TagObject"]
+"""Union of :class:`~git.objects.base.Object`-based types that are typically commit-ish.
+
+See :manpage:`gitglossary(7)` on "commit-ish":
+https://git-scm.com/docs/gitglossary#def_commit-ish
+
+:note:
+    :class:`~git.objects.commit.Commit` is the only class whose instances are all
+    commit-ish. This union type includes :class:`~git.objects.commit.Commit`, but also
+    :class:`~git.objects.tag.TagObject`, only **most** of whose instances are
+    commit-ish. Whether a particular :class:`~git.objects.tag.TagObject` peels
+    (recursively dereferences) to a commit, rather than a tree or blob, can in general
+    only be known at runtime. In practice, git tag objects are nearly always used for
+    tagging commits, and such tags are of course commit-ish.
+
+:note:
+    See also the :class:`AnyGitObject` union of all four classes corresponding to git
+    object types.
+"""
+
+GitObjectTypeString = Literal["commit", "tag", "blob", "tree"]
+"""Literal strings identifying git object types and the
+:class:`~git.objects.base.Object`-based types that represent them.
+
+See the :attr:`Object.type <git.objects.base.Object.type>` attribute. These are its
+values in :class:`~git.objects.base.Object` subclasses that represent git objects. These
+literals therefore correspond to the types in the :class:`AnyGitObject` union.
+
+These are the same strings git itself uses to identify its four object types.
+See :manpage:`gitglossary(7)` on "object type":
+https://git-scm.com/docs/gitglossary#def_object_type
+"""
+
+Lit_commit_ish: Type[Literal["commit", "tag"]]
+"""Deprecated. Type of literal strings identifying typically-commitish git object types.
+
+Prior to a bugfix, this type had been defined more broadly. Any usage is in practice
+ambiguous and likely to be incorrect. This type has therefore been made a static type
+error to appear in annotations. It is preserved, with a deprecated status, to avoid
+introducing runtime errors in code that refers to it, but it should not be used.
+
+Instead of this type:
+
+* For the type of the string literals associated with :class:`Commit_ish`, use
+  ``Literal["commit", "tag"]`` or create a new type alias for it. That is equivalent to
+  this type as currently defined (but usable in statically checked type annotations).
+
+* For the type of all four string literals associated with :class:`AnyGitObject`, use
+  :class:`GitObjectTypeString`. That is equivalent to the old definition of this type
+  prior to the bugfix (and is also usable in statically checked type annotations).
+"""
+
+
+def _getattr(name: str) -> Any:
+    if name != "Lit_commit_ish":
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+    warnings.warn(
+        "Lit_commit_ish is deprecated. It is currently defined as "
+        '`Literal["commit", "tag"]`, which should be used in its place if desired. It '
+        'had previously been defined as `Literal["commit", "tag", "blob", "tree"]`, '
+        "covering all four git object type strings including those that are never "
+        "commit-ish. For that, use the GitObjectTypeString type instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return Literal["commit", "tag"]
+
+
+if not TYPE_CHECKING:  # Preserve static checking for undefined/misspelled attributes.
+    __getattr__ = _getattr
+
+
+def __dir__() -> List[str]:
+    return [*globals(), "Lit_commit_ish"]
+
+
+# Config_levels ---------------------------------------------------------
+
+Lit_config_levels = Literal["system", "global", "user", "repository"]
+"""Type of literal strings naming git configuration levels.
+
+These strings relate to which file a git configuration variable is in.
+"""
+
+ConfigLevels_Tup = Tuple[Literal["system"], Literal["user"], Literal["global"], Literal["repository"]]
+"""Static type of a tuple of the four strings representing configuration levels."""
+
+# Progress parameter type alias -----------------------------------------
+
+CallableProgress = Optional[Callable[[int, Union[str, float], Union[str, float, None], str], None]]
+"""General type of a function or other callable used as a progress reporter for cloning.
+
+This is the type of a function or other callable that reports the progress of a clone,
+when passed as a ``progress`` argument to :meth:`Repo.clone <git.repo.base.Repo.clone>`
+or :meth:`Repo.clone_from <git.repo.base.Repo.clone_from>`.
+
+:note:
+    Those :meth:`~git.repo.base.Repo.clone` and :meth:`~git.repo.base.Repo.clone_from`
+    methods also accept :meth:`~git.util.RemoteProgress` instances, including instances
+    of its :meth:`~git.util.CallableRemoteProgress` subclass.
+
+:note:
+    Unlike objects that match this type, :meth:`~git.util.RemoteProgress` instances are
+    not directly callable, not even when they are instances of
+    :meth:`~git.util.CallableRemoteProgress`, which wraps a callable and forwards
+    information to it but is not itself callable.
+
+:note:
+    This type also allows ``None``, for cloning without reporting progress.
+"""
+
+# -----------------------------------------------------------------------------------
+
+
+def assert_never(inp: NoReturn, raise_error: bool = True, exc: Union[Exception, None] = None) -> None:
+    """For use in exhaustive checking of a literal or enum in if/else chains.
+
+    A call to this function should only be reached if not all members are handled, or if
+    an attempt is made to pass non-members through the chain.
+
+    :param inp:
+        If all members are handled, the argument for `inp` will have the
+        :class:`~typing.Never`/:class:`~typing.NoReturn` type.
+        Otherwise, the type will mismatch and cause a mypy error.
+
+    :param raise_error:
+        If ``True``, will also raise :exc:`ValueError` with a general
+        "unhandled literal" message, or the exception object passed as `exc`.
+
+    :param exc:
+        It not ``None``, this should be an already-constructed exception object, to be
+        raised if `raise_error` is ``True``.
+    """
+    if raise_error:
+        if exc is None:
+            raise ValueError(f"An unhandled literal ({inp!r}) in an if/else chain was found")
+        else:
+            raise exc
+
+
+class Files_TD(TypedDict):
+    """Dictionary with stat counts for the diff of a particular file.
+
+    For the :class:`~git.util.Stats.files` attribute of :class:`~git.util.Stats`
+    objects.
+    """
+
+    insertions: int
+    deletions: int
+    lines: int
+    change_type: str
+
+
+class Total_TD(TypedDict):
+    """Dictionary with total stats from any number of files.
+
+    For the :class:`~git.util.Stats.total` attribute of :class:`~git.util.Stats`
+    objects.
+    """
+
+    insertions: int
+    deletions: int
+    lines: int
+    files: int
+
+
+class HSH_TD(TypedDict):
+    """Dictionary carrying the same information as a :class:`~git.util.Stats` object."""
+
+    total: Total_TD
+    files: Dict[PathLike, Files_TD]
+
+
+@runtime_checkable
+class Has_Repo(Protocol):
+    """Protocol for having a :attr:`repo` attribute, the repository to operate on."""
+
+    repo: "Repo"
+
+
+@runtime_checkable
+class Has_id_attribute(Protocol):
+    """Protocol for having :attr:`_id_attribute_` used in iteration and traversal."""
+
+    _id_attribute_: str

.venv/lib/python3.11/site-packages/git/util.py

@@ -0,0 +1,1350 @@
+# Copyright (C) 2008, 2009 Michael Trier (mtrier@gmail.com) and contributors
+#
+# This module is part of GitPython and is released under the
+# 3-Clause BSD License: https://opensource.org/license/bsd-3-clause/
+
+import sys
+
+__all__ = [
+    "stream_copy",
+    "join_path",
+    "to_native_path_linux",
+    "join_path_native",
+    "Stats",
+    "IndexFileSHA1Writer",
+    "IterableObj",
+    "IterableList",
+    "BlockingLockFile",
+    "LockFile",
+    "Actor",
+    "get_user_id",
+    "assure_directory_exists",
+    "RemoteProgress",
+    "CallableRemoteProgress",
+    "rmtree",
+    "unbare_repo",
+    "HIDE_WINDOWS_KNOWN_ERRORS",
+]
+
+if sys.platform == "win32":
+    __all__.append("to_native_path_windows")
+
+from abc import abstractmethod
+import contextlib
+from functools import wraps
+import getpass
+import logging
+import os
+import os.path as osp
+import pathlib
+import platform
+import re
+import shutil
+import stat
+import subprocess
+import time
+from urllib.parse import urlsplit, urlunsplit
+import warnings
+
+# NOTE: Unused imports can be improved now that CI testing has fully resumed. Some of
+# these be used indirectly through other GitPython modules, which avoids having to write
+# gitdb all the time in their imports. They are not in __all__, at least currently,
+# because they could be removed or changed at any time, and so should not be considered
+# conceptually public to code outside GitPython. Linters of course do not like it.
+from gitdb.util import (
+    LazyMixin,  # noqa: F401
+    LockedFD,  # noqa: F401
+    bin_to_hex,  # noqa: F401
+    file_contents_ro,  # noqa: F401
+    file_contents_ro_filepath,  # noqa: F401
+    hex_to_bin,  # noqa: F401
+    make_sha,
+    to_bin_sha,  # noqa: F401
+    to_hex_sha,  # noqa: F401
+)
+
+# typing ---------------------------------------------------------
+
+from typing import (
+    Any,
+    AnyStr,
+    BinaryIO,
+    Callable,
+    Dict,
+    Generator,
+    IO,
+    Iterator,
+    List,
+    Optional,
+    Pattern,
+    Sequence,
+    Tuple,
+    TYPE_CHECKING,
+    TypeVar,
+    Union,
+    cast,
+    overload,
+)
+
+if TYPE_CHECKING:
+    from git.cmd import Git
+    from git.config import GitConfigParser, SectionConstraint
+    from git.remote import Remote
+    from git.repo.base import Repo
+
+from git.types import (
+    Files_TD,
+    Has_id_attribute,
+    HSH_TD,
+    Literal,
+    PathLike,
+    Protocol,
+    SupportsIndex,
+    Total_TD,
+    runtime_checkable,
+)
+
+# ---------------------------------------------------------------------
+
+T_IterableObj = TypeVar("T_IterableObj", bound=Union["IterableObj", "Has_id_attribute"], covariant=True)
+# So IterableList[Head] is subtype of IterableList[IterableObj].
+
+_logger = logging.getLogger(__name__)
+
+
+def _read_env_flag(name: str, default: bool) -> bool:
+    """Read a boolean flag from an environment variable.
+
+    :return:
+        The flag, or the `default` value if absent or ambiguous.
+    """
+    try:
+        value = os.environ[name]
+    except KeyError:
+        return default
+
+    _logger.warning(
+        "The %s environment variable is deprecated. Its effect has never been documented and changes without warning.",
+        name,
+    )
+
+    adjusted_value = value.strip().lower()
+
+    if adjusted_value in {"", "0", "false", "no"}:
+        return False
+    if adjusted_value in {"1", "true", "yes"}:
+        return True
+    _logger.warning("%s has unrecognized value %r, treating as %r.", name, value, default)
+    return default
+
+
+def _read_win_env_flag(name: str, default: bool) -> bool:
+    """Read a boolean flag from an environment variable on Windows.
+
+    :return:
+        On Windows, the flag, or the `default` value if absent or ambiguous.
+        On all other operating systems, ``False``.
+
+    :note:
+        This only accesses the environment on Windows.
+    """
+    return sys.platform == "win32" and _read_env_flag(name, default)
+
+
+#: We need an easy way to see if Appveyor TCs start failing,
+#: so the errors marked with this var are considered "acknowledged" ones, awaiting remedy,
+#: till then, we wish to hide them.
+HIDE_WINDOWS_KNOWN_ERRORS = _read_win_env_flag("HIDE_WINDOWS_KNOWN_ERRORS", True)
+HIDE_WINDOWS_FREEZE_ERRORS = _read_win_env_flag("HIDE_WINDOWS_FREEZE_ERRORS", True)
+
+# { Utility Methods
+
+T = TypeVar("T")
+
+
+def unbare_repo(func: Callable[..., T]) -> Callable[..., T]:
+    """Methods with this decorator raise :exc:`~git.exc.InvalidGitRepositoryError` if
+    they encounter a bare repository."""
+
+    from .exc import InvalidGitRepositoryError
+
+    @wraps(func)
+    def wrapper(self: "Remote", *args: Any, **kwargs: Any) -> T:
+        if self.repo.bare:
+            raise InvalidGitRepositoryError("Method '%s' cannot operate on bare repositories" % func.__name__)
+        # END bare method
+        return func(self, *args, **kwargs)
+
+    # END wrapper
+
+    return wrapper
+
+
+@contextlib.contextmanager
+def cwd(new_dir: PathLike) -> Generator[PathLike, None, None]:
+    """Context manager to temporarily change directory.
+
+    This is similar to :func:`contextlib.chdir` introduced in Python 3.11, but the
+    context manager object returned by a single call to this function is not reentrant.
+    """
+    old_dir = os.getcwd()
+    os.chdir(new_dir)
+    try:
+        yield new_dir
+    finally:
+        os.chdir(old_dir)
+
+
+@contextlib.contextmanager
+def patch_env(name: str, value: str) -> Generator[None, None, None]:
+    """Context manager to temporarily patch an environment variable."""
+    old_value = os.getenv(name)
+    os.environ[name] = value
+    try:
+        yield
+    finally:
+        if old_value is None:
+            del os.environ[name]
+        else:
+            os.environ[name] = old_value
+
+
+def rmtree(path: PathLike) -> None:
+    """Remove the given directory tree recursively.
+
+    :note:
+        We use :func:`shutil.rmtree` but adjust its behaviour to see whether files that
+        couldn't be deleted are read-only. Windows will not remove them in that case.
+    """
+
+    def handler(function: Callable, path: PathLike, _excinfo: Any) -> None:
+        """Callback for :func:`shutil.rmtree`.
+
+        This works as either a ``onexc`` or ``onerror`` style callback.
+        """
+        # Is the error an access error?
+        os.chmod(path, stat.S_IWUSR)
+
+        try:
+            function(path)
+        except PermissionError as ex:
+            if HIDE_WINDOWS_KNOWN_ERRORS:
+                from unittest import SkipTest
+
+                raise SkipTest(f"FIXME: fails with: PermissionError\n  {ex}") from ex
+            raise
+
+    if sys.platform != "win32":
+        shutil.rmtree(path)
+    elif sys.version_info >= (3, 12):
+        shutil.rmtree(path, onexc=handler)
+    else:
+        shutil.rmtree(path, onerror=handler)
+
+
+def rmfile(path: PathLike) -> None:
+    """Ensure file deleted also on *Windows* where read-only files need special
+    treatment."""
+    if osp.isfile(path):
+        if sys.platform == "win32":
+            os.chmod(path, 0o777)
+        os.remove(path)
+
+
+def stream_copy(source: BinaryIO, destination: BinaryIO, chunk_size: int = 512 * 1024) -> int:
+    """Copy all data from the `source` stream into the `destination` stream in chunks
+    of size `chunk_size`.
+
+    :return:
+        Number of bytes written
+    """
+    br = 0
+    while True:
+        chunk = source.read(chunk_size)
+        destination.write(chunk)
+        br += len(chunk)
+        if len(chunk) < chunk_size:
+            break
+    # END reading output stream
+    return br
+
+
+def join_path(a: PathLike, *p: PathLike) -> PathLike:
+    R"""Join path tokens together similar to osp.join, but always use ``/`` instead of
+    possibly ``\`` on Windows."""
+    path = str(a)
+    for b in p:
+        b = str(b)
+        if not b:
+            continue
+        if b.startswith("/"):
+            path += b[1:]
+        elif path == "" or path.endswith("/"):
+            path += b
+        else:
+            path += "/" + b
+    # END for each path token to add
+    return path
+
+
+if sys.platform == "win32":
+
+    def to_native_path_windows(path: PathLike) -> PathLike:
+        path = str(path)
+        return path.replace("/", "\\")
+
+    def to_native_path_linux(path: PathLike) -> str:
+        path = str(path)
+        return path.replace("\\", "/")
+
+    to_native_path = to_native_path_windows
+else:
+    # No need for any work on Linux.
+    def to_native_path_linux(path: PathLike) -> str:
+        return str(path)
+
+    to_native_path = to_native_path_linux
+
+
+def join_path_native(a: PathLike, *p: PathLike) -> PathLike:
+    R"""Like :func:`join_path`, but makes sure an OS native path is returned.
+
+    This is only needed to play it safe on Windows and to ensure nice paths that only
+    use ``\``.
+    """
+    return to_native_path(join_path(a, *p))
+
+
+def assure_directory_exists(path: PathLike, is_file: bool = False) -> bool:
+    """Make sure that the directory pointed to by path exists.
+
+    :param is_file:
+        If ``True``, `path` is assumed to be a file and handled correctly.
+        Otherwise it must be a directory.
+
+    :return:
+        ``True`` if the directory was created, ``False`` if it already existed.
+    """
+    if is_file:
+        path = osp.dirname(path)
+    # END handle file
+    if not osp.isdir(path):
+        os.makedirs(path, exist_ok=True)
+        return True
+    return False
+
+
+def _get_exe_extensions() -> Sequence[str]:
+    PATHEXT = os.environ.get("PATHEXT", None)
+    if PATHEXT:
+        return tuple(p.upper() for p in PATHEXT.split(os.pathsep))
+    elif sys.platform == "win32":
+        return (".BAT", ".COM", ".EXE")
+    else:
+        return ()
+
+
+def py_where(program: str, path: Optional[PathLike] = None) -> List[str]:
+    """Perform a path search to assist :func:`is_cygwin_git`.
+
+    This is not robust for general use. It is an implementation detail of
+    :func:`is_cygwin_git`. When a search following all shell rules is needed,
+    :func:`shutil.which` can be used instead.
+
+    :note:
+        Neither this function nor :func:`shutil.which` will predict the effect of an
+        executable search on a native Windows system due to a :class:`subprocess.Popen`
+        call without ``shell=True``, because shell and non-shell executable search on
+        Windows differ considerably.
+    """
+    # From: http://stackoverflow.com/a/377028/548792
+    winprog_exts = _get_exe_extensions()
+
+    def is_exec(fpath: str) -> bool:
+        return (
+            osp.isfile(fpath)
+            and os.access(fpath, os.X_OK)
+            and (
+                sys.platform != "win32" or not winprog_exts or any(fpath.upper().endswith(ext) for ext in winprog_exts)
+            )
+        )
+
+    progs = []
+    if not path:
+        path = os.environ["PATH"]
+    for folder in str(path).split(os.pathsep):
+        folder = folder.strip('"')
+        if folder:
+            exe_path = osp.join(folder, program)
+            for f in [exe_path] + ["%s%s" % (exe_path, e) for e in winprog_exts]:
+                if is_exec(f):
+                    progs.append(f)
+    return progs
+
+
+def _cygexpath(drive: Optional[str], path: str) -> str:
+    if osp.isabs(path) and not drive:
+        # Invoked from `cygpath()` directly with `D:Apps\123`?
+        #  It's an error, leave it alone just slashes)
+        p = path  # convert to str if AnyPath given
+    else:
+        p = path and osp.normpath(osp.expandvars(osp.expanduser(path)))
+        if osp.isabs(p):
+            if drive:
+                # Confusing, maybe a remote system should expand vars.
+                p = path
+            else:
+                p = cygpath(p)
+        elif drive:
+            p = "/proc/cygdrive/%s/%s" % (drive.lower(), p)
+    p_str = str(p)  # ensure it is a str and not AnyPath
+    return p_str.replace("\\", "/")
+
+
+_cygpath_parsers: Tuple[Tuple[Pattern[str], Callable, bool], ...] = (
+    # See: https://msdn.microsoft.com/en-us/library/windows/desktop/aa365247(v=vs.85).aspx
+    # and: https://www.cygwin.com/cygwin-ug-net/using.html#unc-paths
+    (
+        re.compile(r"\\\\\?\\UNC\\([^\\]+)\\([^\\]+)(?:\\(.*))?"),
+        (lambda server, share, rest_path: "//%s/%s/%s" % (server, share, rest_path.replace("\\", "/"))),
+        False,
+    ),
+    (re.compile(r"\\\\\?\\(\w):[/\\](.*)"), (_cygexpath), False),
+    (re.compile(r"(\w):[/\\](.*)"), (_cygexpath), False),
+    (re.compile(r"file:(.*)", re.I), (lambda rest_path: rest_path), True),
+    (re.compile(r"(\w{2,}:.*)"), (lambda url: url), False),  # remote URL, do nothing
+)
+
+
+def cygpath(path: str) -> str:
+    """Use :meth:`git.cmd.Git.polish_url` instead, that works on any environment."""
+    path = str(path)  # Ensure is str and not AnyPath.
+    # Fix to use Paths when 3.5 dropped. Or to be just str if only for URLs?
+    if not path.startswith(("/cygdrive", "//", "/proc/cygdrive")):
+        for regex, parser, recurse in _cygpath_parsers:
+            match = regex.match(path)
+            if match:
+                path = parser(*match.groups())
+                if recurse:
+                    path = cygpath(path)
+                break
+        else:
+            path = _cygexpath(None, path)
+
+    return path
+
+
+_decygpath_regex = re.compile(r"(?:/proc)?/cygdrive/(\w)(/.*)?")
+
+
+def decygpath(path: PathLike) -> str:
+    path = str(path)
+    m = _decygpath_regex.match(path)
+    if m:
+        drive, rest_path = m.groups()
+        path = "%s:%s" % (drive.upper(), rest_path or "")
+
+    return path.replace("/", "\\")
+
+
+#: Store boolean flags denoting if a specific Git executable
+#: is from a Cygwin installation (since `cache_lru()` unsupported on PY2).
+_is_cygwin_cache: Dict[str, Optional[bool]] = {}
+
+
+def _is_cygwin_git(git_executable: str) -> bool:
+    is_cygwin = _is_cygwin_cache.get(git_executable)  # type: Optional[bool]
+    if is_cygwin is None:
+        is_cygwin = False
+        try:
+            git_dir = osp.dirname(git_executable)
+            if not git_dir:
+                res = py_where(git_executable)
+                git_dir = osp.dirname(res[0]) if res else ""
+
+            # Just a name given, not a real path.
+            uname_cmd = osp.join(git_dir, "uname")
+
+            if not (pathlib.Path(uname_cmd).is_file() and os.access(uname_cmd, os.X_OK)):
+                _logger.debug(f"Failed checking if running in CYGWIN: {uname_cmd} is not an executable")
+                _is_cygwin_cache[git_executable] = is_cygwin
+                return is_cygwin
+
+            process = subprocess.Popen([uname_cmd], stdout=subprocess.PIPE, universal_newlines=True)
+            uname_out, _ = process.communicate()
+            # retcode = process.poll()
+            is_cygwin = "CYGWIN" in uname_out
+        except Exception as ex:
+            _logger.debug("Failed checking if running in CYGWIN due to: %r", ex)
+        _is_cygwin_cache[git_executable] = is_cygwin
+
+    return is_cygwin
+
+
+@overload
+def is_cygwin_git(git_executable: None) -> Literal[False]: ...
+
+
+@overload
+def is_cygwin_git(git_executable: PathLike) -> bool: ...
+
+
+def is_cygwin_git(git_executable: Union[None, PathLike]) -> bool:
+    # TODO: when py3.7 support is dropped, use the new interpolation f"{variable=}"
+    _logger.debug(f"sys.platform={sys.platform!r}, git_executable={git_executable!r}")
+    if sys.platform != "cygwin":
+        return False
+    elif git_executable is None:
+        return False
+    else:
+        return _is_cygwin_git(str(git_executable))
+
+
+def get_user_id() -> str:
+    """:return: String identifying the currently active system user as ``name@node``"""
+    return "%s@%s" % (getpass.getuser(), platform.node())
+
+
+def finalize_process(proc: Union[subprocess.Popen, "Git.AutoInterrupt"], **kwargs: Any) -> None:
+    """Wait for the process (clone, fetch, pull or push) and handle its errors
+    accordingly."""
+    # TODO: No close proc-streams??
+    proc.wait(**kwargs)
+
+
+@overload
+def expand_path(p: None, expand_vars: bool = ...) -> None: ...
+
+
+@overload
+def expand_path(p: PathLike, expand_vars: bool = ...) -> str:
+    # TODO: Support for Python 3.5 has been dropped, so these overloads can be improved.
+    ...
+
+
+def expand_path(p: Union[None, PathLike], expand_vars: bool = True) -> Optional[PathLike]:
+    if isinstance(p, pathlib.Path):
+        return p.resolve()
+    try:
+        p = osp.expanduser(p)  # type: ignore[arg-type]
+        if expand_vars:
+            p = osp.expandvars(p)
+        return osp.normpath(osp.abspath(p))
+    except Exception:
+        return None
+
+
+def remove_password_if_present(cmdline: Sequence[str]) -> List[str]:
+    """Parse any command line argument and if one of the elements is an URL with a
+    username and/or password, replace them by stars (in-place).
+
+    If nothing is found, this just returns the command line as-is.
+
+    This should be used for every log line that print a command line, as well as
+    exception messages.
+    """
+    new_cmdline = []
+    for index, to_parse in enumerate(cmdline):
+        new_cmdline.append(to_parse)
+        try:
+            url = urlsplit(to_parse)
+            # Remove password from the URL if present.
+            if url.password is None and url.username is None:
+                continue
+
+            if url.password is not None:
+                url = url._replace(netloc=url.netloc.replace(url.password, "*****"))
+            if url.username is not None:
+                url = url._replace(netloc=url.netloc.replace(url.username, "*****"))
+            new_cmdline[index] = urlunsplit(url)
+        except ValueError:
+            # This is not a valid URL.
+            continue
+    return new_cmdline
+
+
+# } END utilities
+
+# { Classes
+
+
+class RemoteProgress:
+    """Handler providing an interface to parse progress information emitted by
+    :manpage:`git-push(1)` and :manpage:`git-fetch(1)` and to dispatch callbacks
+    allowing subclasses to react to the progress."""
+
+    _num_op_codes: int = 9
+    (
+        BEGIN,
+        END,
+        COUNTING,
+        COMPRESSING,
+        WRITING,
+        RECEIVING,
+        RESOLVING,
+        FINDING_SOURCES,
+        CHECKING_OUT,
+    ) = [1 << x for x in range(_num_op_codes)]
+    STAGE_MASK = BEGIN | END
+    OP_MASK = ~STAGE_MASK
+
+    DONE_TOKEN = "done."
+    TOKEN_SEPARATOR = ", "
+
+    __slots__ = (
+        "_cur_line",
+        "_seen_ops",
+        "error_lines",  # Lines that started with 'error:' or 'fatal:'.
+        "other_lines",  # Lines not denoting progress (i.e.g. push-infos).
+    )
+    re_op_absolute = re.compile(r"(remote: )?([\w\s]+):\s+()(\d+)()(.*)")
+    re_op_relative = re.compile(r"(remote: )?([\w\s]+):\s+(\d+)% \((\d+)/(\d+)\)(.*)")
+
+    def __init__(self) -> None:
+        self._seen_ops: List[int] = []
+        self._cur_line: Optional[str] = None
+        self.error_lines: List[str] = []
+        self.other_lines: List[str] = []
+
+    def _parse_progress_line(self, line: AnyStr) -> None:
+        """Parse progress information from the given line as retrieved by
+        :manpage:`git-push(1)` or :manpage:`git-fetch(1)`.
+
+        - Lines that do not contain progress info are stored in :attr:`other_lines`.
+        - Lines that seem to contain an error (i.e. start with ``error:`` or ``fatal:``)
+          are stored in :attr:`error_lines`.
+        """
+        # handle
+        # Counting objects: 4, done.
+        # Compressing objects:  50% (1/2)
+        # Compressing objects: 100% (2/2)
+        # Compressing objects: 100% (2/2), done.
+        if isinstance(line, bytes):  # mypy argues about ternary assignment.
+            line_str = line.decode("utf-8")
+        else:
+            line_str = line
+        self._cur_line = line_str
+
+        if self._cur_line.startswith(("error:", "fatal:")):
+            self.error_lines.append(self._cur_line)
+            return
+
+        cur_count, max_count = None, None
+        match = self.re_op_relative.match(line_str)
+        if match is None:
+            match = self.re_op_absolute.match(line_str)
+
+        if not match:
+            self.line_dropped(line_str)
+            self.other_lines.append(line_str)
+            return
+        # END could not get match
+
+        op_code = 0
+        _remote, op_name, _percent, cur_count, max_count, message = match.groups()
+
+        # Get operation ID.
+        if op_name == "Counting objects":
+            op_code |= self.COUNTING
+        elif op_name == "Compressing objects":
+            op_code |= self.COMPRESSING
+        elif op_name == "Writing objects":
+            op_code |= self.WRITING
+        elif op_name == "Receiving objects":
+            op_code |= self.RECEIVING
+        elif op_name == "Resolving deltas":
+            op_code |= self.RESOLVING
+        elif op_name == "Finding sources":
+            op_code |= self.FINDING_SOURCES
+        elif op_name == "Checking out files":
+            op_code |= self.CHECKING_OUT
+        else:
+            # Note: On Windows it can happen that partial lines are sent.
+            # Hence we get something like "CompreReceiving objects", which is
+            # a blend of "Compressing objects" and "Receiving objects".
+            # This can't really be prevented, so we drop the line verbosely
+            # to make sure we get informed in case the process spits out new
+            # commands at some point.
+            self.line_dropped(line_str)
+            # Note: Don't add this line to the other lines, as we have to silently
+            # drop it.
+            return
+        # END handle op code
+
+        # Figure out stage.
+        if op_code not in self._seen_ops:
+            self._seen_ops.append(op_code)
+            op_code |= self.BEGIN
+        # END begin opcode
+
+        if message is None:
+            message = ""
+        # END message handling
+
+        message = message.strip()
+        if message.endswith(self.DONE_TOKEN):
+            op_code |= self.END
+            message = message[: -len(self.DONE_TOKEN)]
+        # END end message handling
+        message = message.strip(self.TOKEN_SEPARATOR)
+
+        self.update(
+            op_code,
+            cur_count and float(cur_count),
+            max_count and float(max_count),
+            message,
+        )
+
+    def new_message_handler(self) -> Callable[[str], None]:
+        """
+        :return:
+            A progress handler suitable for :func:`~git.cmd.handle_process_output`,
+            passing lines on to this progress handler in a suitable format.
+        """
+
+        def handler(line: AnyStr) -> None:
+            return self._parse_progress_line(line.rstrip())
+
+        # END handler
+
+        return handler
+
+    def line_dropped(self, line: str) -> None:
+        """Called whenever a line could not be understood and was therefore dropped."""
+        pass
+
+    def update(
+        self,
+        op_code: int,
+        cur_count: Union[str, float],
+        max_count: Union[str, float, None] = None,
+        message: str = "",
+    ) -> None:
+        """Called whenever the progress changes.
+
+        :param op_code:
+            Integer allowing to be compared against Operation IDs and stage IDs.
+
+            Stage IDs are :const:`BEGIN` and :const:`END`. :const:`BEGIN` will only be
+            set once for each Operation ID as well as :const:`END`. It may be that
+            :const:`BEGIN` and :const:`END` are set at once in case only one progress
+            message was emitted due to the speed of the operation. Between
+            :const:`BEGIN` and :const:`END`, none of these flags will be set.
+
+            Operation IDs are all held within the :const:`OP_MASK`. Only one Operation
+            ID will be active per call.
+
+        :param cur_count:
+            Current absolute count of items.
+
+        :param max_count:
+            The maximum count of items we expect. It may be ``None`` in case there is no
+            maximum number of items or if it is (yet) unknown.
+
+        :param message:
+            In case of the :const:`WRITING` operation, it contains the amount of bytes
+            transferred. It may possibly be used for other purposes as well.
+
+        :note:
+            You may read the contents of the current line in
+            :attr:`self._cur_line <_cur_line>`.
+        """
+        pass
+
+
+class CallableRemoteProgress(RemoteProgress):
+    """A :class:`RemoteProgress` implementation forwarding updates to any callable.
+
+    :note:
+        Like direct instances of :class:`RemoteProgress`, instances of this
+        :class:`CallableRemoteProgress` class are not themselves directly callable.
+        Rather, instances of this class wrap a callable and forward to it. This should
+        therefore not be confused with :class:`git.types.CallableProgress`.
+    """
+
+    __slots__ = ("_callable",)
+
+    def __init__(self, fn: Callable) -> None:
+        self._callable = fn
+        super().__init__()
+
+    def update(self, *args: Any, **kwargs: Any) -> None:
+        self._callable(*args, **kwargs)
+
+
+class Actor:
+    """Actors hold information about a person acting on the repository. They can be
+    committers and authors or anything with a name and an email as mentioned in the git
+    log entries."""
+
+    # PRECOMPILED REGEX
+    name_only_regex = re.compile(r"<(.*)>")
+    name_email_regex = re.compile(r"(.*) <(.*?)>")
+
+    # ENVIRONMENT VARIABLES
+    # These are read when creating new commits.
+    env_author_name = "GIT_AUTHOR_NAME"
+    env_author_email = "GIT_AUTHOR_EMAIL"
+    env_committer_name = "GIT_COMMITTER_NAME"
+    env_committer_email = "GIT_COMMITTER_EMAIL"
+
+    # CONFIGURATION KEYS
+    conf_name = "name"
+    conf_email = "email"
+
+    __slots__ = ("name", "email")
+
+    def __init__(self, name: Optional[str], email: Optional[str]) -> None:
+        self.name = name
+        self.email = email
+
+    def __eq__(self, other: Any) -> bool:
+        return self.name == other.name and self.email == other.email
+
+    def __ne__(self, other: Any) -> bool:
+        return not (self == other)
+
+    def __hash__(self) -> int:
+        return hash((self.name, self.email))
+
+    def __str__(self) -> str:
+        return self.name if self.name else ""
+
+    def __repr__(self) -> str:
+        return '<git.Actor "%s <%s>">' % (self.name, self.email)
+
+    @classmethod
+    def _from_string(cls, string: str) -> "Actor":
+        """Create an :class:`Actor` from a string.
+
+        :param string:
+            The string, which is expected to be in regular git format::
+
+                John Doe <jdoe@example.com>
+
+        :return:
+            :class:`Actor`
+        """
+        m = cls.name_email_regex.search(string)
+        if m:
+            name, email = m.groups()
+            return Actor(name, email)
+        else:
+            m = cls.name_only_regex.search(string)
+            if m:
+                return Actor(m.group(1), None)
+            # Assume the best and use the whole string as name.
+            return Actor(string, None)
+            # END special case name
+        # END handle name/email matching
+
+    @classmethod
+    def _main_actor(
+        cls,
+        env_name: str,
+        env_email: str,
+        config_reader: Union[None, "GitConfigParser", "SectionConstraint"] = None,
+    ) -> "Actor":
+        actor = Actor("", "")
+        user_id = None  # We use this to avoid multiple calls to getpass.getuser().
+
+        def default_email() -> str:
+            nonlocal user_id
+            if not user_id:
+                user_id = get_user_id()
+            return user_id
+
+        def default_name() -> str:
+            return default_email().split("@")[0]
+
+        for attr, evar, cvar, default in (
+            ("name", env_name, cls.conf_name, default_name),
+            ("email", env_email, cls.conf_email, default_email),
+        ):
+            try:
+                val = os.environ[evar]
+                setattr(actor, attr, val)
+            except KeyError:
+                if config_reader is not None:
+                    try:
+                        val = config_reader.get("user", cvar)
+                    except Exception:
+                        val = default()
+                    setattr(actor, attr, val)
+                # END config-reader handling
+                if not getattr(actor, attr):
+                    setattr(actor, attr, default())
+            # END handle name
+        # END for each item to retrieve
+        return actor
+
+    @classmethod
+    def committer(cls, config_reader: Union[None, "GitConfigParser", "SectionConstraint"] = None) -> "Actor":
+        """
+        :return:
+            :class:`Actor` instance corresponding to the configured committer. It
+            behaves similar to the git implementation, such that the environment will
+            override configuration values of `config_reader`. If no value is set at all,
+            it will be generated.
+
+        :param config_reader:
+            ConfigReader to use to retrieve the values from in case they are not set in
+            the environment.
+        """
+        return cls._main_actor(cls.env_committer_name, cls.env_committer_email, config_reader)
+
+    @classmethod
+    def author(cls, config_reader: Union[None, "GitConfigParser", "SectionConstraint"] = None) -> "Actor":
+        """Same as :meth:`committer`, but defines the main author. It may be specified
+        in the environment, but defaults to the committer."""
+        return cls._main_actor(cls.env_author_name, cls.env_author_email, config_reader)
+
+
+class Stats:
+    """Represents stat information as presented by git at the end of a merge. It is
+    created from the output of a diff operation.
+
+    Example::
+
+     c = Commit( sha1 )
+     s = c.stats
+     s.total         # full-stat-dict
+     s.files         # dict( filepath : stat-dict )
+
+    ``stat-dict``
+
+    A dictionary with the following keys and values::
+
+      deletions = number of deleted lines as int
+      insertions = number of inserted lines as int
+      lines = total number of lines changed as int, or deletions + insertions
+      change_type = type of change as str, A|C|D|M|R|T|U|X|B
+
+    ``full-stat-dict``
+
+    In addition to the items in the stat-dict, it features additional information::
+
+     files = number of changed files as int
+    """
+
+    __slots__ = ("total", "files")
+
+    def __init__(self, total: Total_TD, files: Dict[PathLike, Files_TD]) -> None:
+        self.total = total
+        self.files = files
+
+    @classmethod
+    def _list_from_string(cls, repo: "Repo", text: str) -> "Stats":
+        """Create a :class:`Stats` object from output retrieved by
+        :manpage:`git-diff(1)`.
+
+        :return:
+            :class:`git.Stats`
+        """
+
+        hsh: HSH_TD = {
+            "total": {"insertions": 0, "deletions": 0, "lines": 0, "files": 0},
+            "files": {},
+        }
+        for line in text.splitlines():
+            (change_type, raw_insertions, raw_deletions, filename) = line.split("\t")
+            insertions = raw_insertions != "-" and int(raw_insertions) or 0
+            deletions = raw_deletions != "-" and int(raw_deletions) or 0
+            hsh["total"]["insertions"] += insertions
+            hsh["total"]["deletions"] += deletions
+            hsh["total"]["lines"] += insertions + deletions
+            hsh["total"]["files"] += 1
+            files_dict: Files_TD = {
+                "insertions": insertions,
+                "deletions": deletions,
+                "lines": insertions + deletions,
+                "change_type": change_type,
+            }
+            hsh["files"][filename.strip()] = files_dict
+        return Stats(hsh["total"], hsh["files"])
+
+
+class IndexFileSHA1Writer:
+    """Wrapper around a file-like object that remembers the SHA1 of the data written to
+    it. It will write a sha when the stream is closed or if asked for explicitly using
+    :meth:`write_sha`.
+
+    Only useful to the index file.
+
+    :note:
+        Based on the dulwich project.
+    """
+
+    __slots__ = ("f", "sha1")
+
+    def __init__(self, f: IO) -> None:
+        self.f = f
+        self.sha1 = make_sha(b"")
+
+    def write(self, data: AnyStr) -> int:
+        self.sha1.update(data)
+        return self.f.write(data)
+
+    def write_sha(self) -> bytes:
+        sha = self.sha1.digest()
+        self.f.write(sha)
+        return sha
+
+    def close(self) -> bytes:
+        sha = self.write_sha()
+        self.f.close()
+        return sha
+
+    def tell(self) -> int:
+        return self.f.tell()
+
+
+class LockFile:
+    """Provides methods to obtain, check for, and release a file based lock which
+    should be used to handle concurrent access to the same file.
+
+    As we are a utility class to be derived from, we only use protected methods.
+
+    Locks will automatically be released on destruction.
+    """
+
+    __slots__ = ("_file_path", "_owns_lock")
+
+    def __init__(self, file_path: PathLike) -> None:
+        self._file_path = file_path
+        self._owns_lock = False
+
+    def __del__(self) -> None:
+        self._release_lock()
+
+    def _lock_file_path(self) -> str:
+        """:return: Path to lockfile"""
+        return "%s.lock" % (self._file_path)
+
+    def _has_lock(self) -> bool:
+        """
+        :return:
+            True if we have a lock and if the lockfile still exists
+
+        :raise AssertionError:
+            If our lock-file does not exist.
+        """
+        return self._owns_lock
+
+    def _obtain_lock_or_raise(self) -> None:
+        """Create a lock file as flag for other instances, mark our instance as
+        lock-holder.
+
+        :raise IOError:
+            If a lock was already present or a lock file could not be written.
+        """
+        if self._has_lock():
+            return
+        lock_file = self._lock_file_path()
+        if osp.isfile(lock_file):
+            raise IOError(
+                "Lock for file %r did already exist, delete %r in case the lock is illegal"
+                % (self._file_path, lock_file)
+            )
+
+        try:
+            with open(lock_file, mode="w"):
+                pass
+        except OSError as e:
+            raise IOError(str(e)) from e
+
+        self._owns_lock = True
+
+    def _obtain_lock(self) -> None:
+        """The default implementation will raise if a lock cannot be obtained.
+
+        Subclasses may override this method to provide a different implementation.
+        """
+        return self._obtain_lock_or_raise()
+
+    def _release_lock(self) -> None:
+        """Release our lock if we have one."""
+        if not self._has_lock():
+            return
+
+        # If someone removed our file beforehand, lets just flag this issue instead of
+        # failing, to make it more usable.
+        lfp = self._lock_file_path()
+        try:
+            rmfile(lfp)
+        except OSError:
+            pass
+        self._owns_lock = False
+
+
+class BlockingLockFile(LockFile):
+    """The lock file will block until a lock could be obtained, or fail after a
+    specified timeout.
+
+    :note:
+        If the directory containing the lock was removed, an exception will be raised
+        during the blocking period, preventing hangs as the lock can never be obtained.
+    """
+
+    __slots__ = ("_check_interval", "_max_block_time")
+
+    def __init__(
+        self,
+        file_path: PathLike,
+        check_interval_s: float = 0.3,
+        max_block_time_s: int = sys.maxsize,
+    ) -> None:
+        """Configure the instance.
+
+        :param check_interval_s:
+            Period of time to sleep until the lock is checked the next time.
+            By default, it waits a nearly unlimited time.
+
+        :param max_block_time_s:
+            Maximum amount of seconds we may lock.
+        """
+        super().__init__(file_path)
+        self._check_interval = check_interval_s
+        self._max_block_time = max_block_time_s
+
+    def _obtain_lock(self) -> None:
+        """This method blocks until it obtained the lock, or raises :exc:`IOError` if it
+        ran out of time or if the parent directory was not available anymore.
+
+        If this method returns, you are guaranteed to own the lock.
+        """
+        starttime = time.time()
+        maxtime = starttime + float(self._max_block_time)
+        while True:
+            try:
+                super()._obtain_lock()
+            except IOError as e:
+                # synity check: if the directory leading to the lockfile is not
+                # readable anymore, raise an exception
+                curtime = time.time()
+                if not osp.isdir(osp.dirname(self._lock_file_path())):
+                    msg = "Directory containing the lockfile %r was not readable anymore after waiting %g seconds" % (
+                        self._lock_file_path(),
+                        curtime - starttime,
+                    )
+                    raise IOError(msg) from e
+                # END handle missing directory
+
+                if curtime >= maxtime:
+                    msg = "Waited %g seconds for lock at %r" % (
+                        maxtime - starttime,
+                        self._lock_file_path(),
+                    )
+                    raise IOError(msg) from e
+                # END abort if we wait too long
+                time.sleep(self._check_interval)
+            else:
+                break
+        # END endless loop
+
+
+class IterableList(List[T_IterableObj]):
+    """List of iterable objects allowing to query an object by id or by named index::
+
+     heads = repo.heads
+     heads.master
+     heads['master']
+     heads[0]
+
+    Iterable parent objects:
+
+    * :class:`Commit <git.objects.Commit>`
+    * :class:`Submodule <git.objects.submodule.base.Submodule>`
+    * :class:`Reference <git.refs.reference.Reference>`
+    * :class:`FetchInfo <git.remote.FetchInfo>`
+    * :class:`PushInfo <git.remote.PushInfo>`
+
+    Iterable via inheritance:
+
+    * :class:`Head <git.refs.head.Head>`
+    * :class:`TagReference <git.refs.tag.TagReference>`
+    * :class:`RemoteReference <git.refs.remote.RemoteReference>`
+
+    This requires an ``id_attribute`` name to be set which will be queried from its
+    contained items to have a means for comparison.
+
+    A prefix can be specified which is to be used in case the id returned by the items
+    always contains a prefix that does not matter to the user, so it can be left out.
+    """
+
+    __slots__ = ("_id_attr", "_prefix")
+
+    def __new__(cls, id_attr: str, prefix: str = "") -> "IterableList[T_IterableObj]":
+        return super().__new__(cls)
+
+    def __init__(self, id_attr: str, prefix: str = "") -> None:
+        self._id_attr = id_attr
+        self._prefix = prefix
+
+    def __contains__(self, attr: object) -> bool:
+        # First try identity match for performance.
+        try:
+            rval = list.__contains__(self, attr)
+            if rval:
+                return rval
+        except (AttributeError, TypeError):
+            pass
+        # END handle match
+
+        # Otherwise make a full name search.
+        try:
+            getattr(self, cast(str, attr))  # Use cast to silence mypy.
+            return True
+        except (AttributeError, TypeError):
+            return False
+        # END handle membership
+
+    def __getattr__(self, attr: str) -> T_IterableObj:
+        attr = self._prefix + attr
+        for item in self:
+            if getattr(item, self._id_attr) == attr:
+                return item
+        # END for each item
+        return list.__getattribute__(self, attr)
+
+    def __getitem__(self, index: Union[SupportsIndex, int, slice, str]) -> T_IterableObj:  # type: ignore[override]
+        if isinstance(index, int):
+            return list.__getitem__(self, index)
+        elif isinstance(index, slice):
+            raise ValueError("Index should be an int or str")
+        else:
+            try:
+                return getattr(self, index)
+            except AttributeError as e:
+                raise IndexError("No item found with id %r" % (self._prefix + index)) from e
+        # END handle getattr
+
+    def __delitem__(self, index: Union[SupportsIndex, int, slice, str]) -> None:
+        delindex = cast(int, index)
+        if not isinstance(index, int):
+            delindex = -1
+            name = self._prefix + index
+            for i, item in enumerate(self):
+                if getattr(item, self._id_attr) == name:
+                    delindex = i
+                    break
+                # END search index
+            # END for each item
+            if delindex == -1:
+                raise IndexError("Item with name %s not found" % name)
+            # END handle error
+        # END get index to delete
+        list.__delitem__(self, delindex)
+
+
+@runtime_checkable
+class IterableObj(Protocol):
+    """Defines an interface for iterable items, so there is a uniform way to retrieve
+    and iterate items within the git repository.
+
+    Subclasses:
+
+    * :class:`Submodule <git.objects.submodule.base.Submodule>`
+    * :class:`Commit <git.objects.Commit>`
+    * :class:`Reference <git.refs.reference.Reference>`
+    * :class:`PushInfo <git.remote.PushInfo>`
+    * :class:`FetchInfo <git.remote.FetchInfo>`
+    * :class:`Remote <git.remote.Remote>`
+    """
+
+    __slots__ = ()
+
+    _id_attribute_: str
+
+    @classmethod
+    @abstractmethod
+    def iter_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> Iterator[T_IterableObj]:
+        # Return-typed to be compatible with subtypes e.g. Remote.
+        """Find (all) items of this type.
+
+        Subclasses can specify `args` and `kwargs` differently, and may use them for
+        filtering. However, when the method is called with no additional positional or
+        keyword arguments, subclasses are obliged to to yield all items.
+
+        :return:
+            Iterator yielding Items
+        """
+        raise NotImplementedError("To be implemented by Subclass")
+
+    @classmethod
+    def list_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> IterableList[T_IterableObj]:
+        """Find (all) items of this type and collect them into a list.
+
+        For more information about the arguments, see :meth:`iter_items`.
+
+        :note:
+            Favor the :meth:`iter_items` method as it will avoid eagerly collecting all
+            items. When there are many items, that can slow performance and increase
+            memory usage.
+
+        :return:
+            list(Item,...) list of item instances
+        """
+        out_list: IterableList = IterableList(cls._id_attribute_)
+        out_list.extend(cls.iter_items(repo, *args, **kwargs))
+        return out_list
+
+
+class IterableClassWatcher(type):
+    """Metaclass that issues :exc:`DeprecationWarning` when :class:`git.util.Iterable`
+    is subclassed."""
+
+    def __init__(cls, name: str, bases: Tuple, clsdict: Dict) -> None:
+        for base in bases:
+            if type(base) is IterableClassWatcher:
+                warnings.warn(
+                    f"GitPython Iterable subclassed by {name}."
+                    " Iterable is deprecated due to naming clash since v3.1.18"
+                    " and will be removed in 4.0.0."
+                    " Use IterableObj instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+
+
+class Iterable(metaclass=IterableClassWatcher):
+    """Deprecated, use :class:`IterableObj` instead.
+
+    Defines an interface for iterable items, so there is a uniform way to retrieve
+    and iterate items within the git repository.
+    """
+
+    __slots__ = ()
+
+    _id_attribute_ = "attribute that most suitably identifies your instance"
+
+    @classmethod
+    def iter_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> Any:
+        """Deprecated, use :class:`IterableObj` instead.
+
+        Find (all) items of this type.
+
+        See :meth:`IterableObj.iter_items` for details on usage.
+
+        :return:
+            Iterator yielding Items
+        """
+        raise NotImplementedError("To be implemented by Subclass")
+
+    @classmethod
+    def list_items(cls, repo: "Repo", *args: Any, **kwargs: Any) -> Any:
+        """Deprecated, use :class:`IterableObj` instead.
+
+        Find (all) items of this type and collect them into a list.
+
+        See :meth:`IterableObj.list_items` for details on usage.
+
+        :return:
+            list(Item,...) list of item instances
+        """
+        out_list: Any = IterableList(cls._id_attribute_)
+        out_list.extend(cls.iter_items(repo, *args, **kwargs))
+        return out_list
+
+
+# } END classes

.venv/lib/python3.11/site-packages/google/_upb/_message.abi3.so

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9fd150616ef20dfeb5709e2ddd83a331b7a02ed5d7f7ab8040e6c05f1276b8a2
+size 401520

.venv/lib/python3.11/site-packages/google/cloud/storage/__pycache__/blob.cpython-311.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a36378a9e8c6cca2c6da59dbeef5181249ade2f556ecd8b7f3721f0fed3b09ab
+size 188903

.venv/lib/python3.11/site-packages/google/cloud/storage/__pycache__/bucket.cpython-311.pyc

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d8412d031a7fba5c4db29cfa7c812d19ef213ef505a76900be69f3933879d52f
+size 159151

.venv/lib/python3.11/site-packages/huggingface_hub/__init__.py

@@ -0,0 +1,1554 @@
+# Copyright 2020 The HuggingFace Team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# ***********
+# `huggingface_hub` init has 2 modes:
+# - Normal usage:
+#       If imported to use it, all modules and functions are lazy-loaded. This means
+#       they exist at top level in module but are imported only the first time they are
+#       used. This way, `from huggingface_hub import something` will import `something`
+#       quickly without the hassle of importing all the features from `huggingface_hub`.
+# - Static check:
+#       If statically analyzed, all modules and functions are loaded normally. This way
+#       static typing check works properly as well as autocomplete in text editors and
+#       IDEs.
+#
+# The static model imports are done inside the `if TYPE_CHECKING:` statement at
+# the bottom of this file. Since module/functions imports are duplicated, it is
+# mandatory to make sure to add them twice when adding one. This is checked in the
+# `make quality` command.
+#
+# To update the static imports, please run the following command and commit the changes.
+# ```
+# # Use script
+# python utils/check_static_imports.py --update-file
+#
+# # Or run style on codebase
+# make style
+# ```
+#
+# ***********
+# Lazy loader vendored from https://github.com/scientific-python/lazy_loader
+import importlib
+import os
+import sys
+from typing import TYPE_CHECKING
+
+
+__version__ = "0.36.0"
+
+# Alphabetical order of definitions is ensured in tests
+# WARNING: any comment added in this dictionary definition will be lost when
+# re-generating the file !
+_SUBMOD_ATTRS = {
+    "_commit_scheduler": [
+        "CommitScheduler",
+    ],
+    "_inference_endpoints": [
+        "InferenceEndpoint",
+        "InferenceEndpointError",
+        "InferenceEndpointStatus",
+        "InferenceEndpointTimeoutError",
+        "InferenceEndpointType",
+    ],
+    "_jobs_api": [
+        "JobInfo",
+        "JobOwner",
+        "JobStage",
+        "JobStatus",
+    ],
+    "_login": [
+        "auth_list",
+        "auth_switch",
+        "interpreter_login",
+        "login",
+        "logout",
+        "notebook_login",
+    ],
+    "_oauth": [
+        "OAuthInfo",
+        "OAuthOrgInfo",
+        "OAuthUserInfo",
+        "attach_huggingface_oauth",
+        "parse_huggingface_oauth",
+    ],
+    "_snapshot_download": [
+        "snapshot_download",
+    ],
+    "_space_api": [
+        "SpaceHardware",
+        "SpaceRuntime",
+        "SpaceStage",
+        "SpaceStorage",
+        "SpaceVariable",
+    ],
+    "_tensorboard_logger": [
+        "HFSummaryWriter",
+    ],
+    "_webhooks_payload": [
+        "WebhookPayload",
+        "WebhookPayloadComment",
+        "WebhookPayloadDiscussion",
+        "WebhookPayloadDiscussionChanges",
+        "WebhookPayloadEvent",
+        "WebhookPayloadMovedTo",
+        "WebhookPayloadRepo",
+        "WebhookPayloadUrl",
+        "WebhookPayloadWebhook",
+    ],
+    "_webhooks_server": [
+        "WebhooksServer",
+        "webhook_endpoint",
+    ],
+    "community": [
+        "Discussion",
+        "DiscussionComment",
+        "DiscussionCommit",
+        "DiscussionEvent",
+        "DiscussionStatusChange",
+        "DiscussionTitleChange",
+        "DiscussionWithDetails",
+    ],
+    "constants": [
+        "CONFIG_NAME",
+        "FLAX_WEIGHTS_NAME",
+        "HUGGINGFACE_CO_URL_HOME",
+        "HUGGINGFACE_CO_URL_TEMPLATE",
+        "PYTORCH_WEIGHTS_NAME",
+        "REPO_TYPE_DATASET",
+        "REPO_TYPE_MODEL",
+        "REPO_TYPE_SPACE",
+        "TF2_WEIGHTS_NAME",
+        "TF_WEIGHTS_NAME",
+    ],
+    "fastai_utils": [
+        "_save_pretrained_fastai",
+        "from_pretrained_fastai",
+        "push_to_hub_fastai",
+    ],
+    "file_download": [
+        "HfFileMetadata",
+        "_CACHED_NO_EXIST",
+        "get_hf_file_metadata",
+        "hf_hub_download",
+        "hf_hub_url",
+        "try_to_load_from_cache",
+    ],
+    "hf_api": [
+        "Collection",
+        "CollectionItem",
+        "CommitInfo",
+        "CommitOperation",
+        "CommitOperationAdd",
+        "CommitOperationCopy",
+        "CommitOperationDelete",
+        "DatasetInfo",
+        "GitCommitInfo",
+        "GitRefInfo",
+        "GitRefs",
+        "HfApi",
+        "ModelInfo",
+        "Organization",
+        "RepoUrl",
+        "SpaceInfo",
+        "User",
+        "UserLikes",
+        "WebhookInfo",
+        "WebhookWatchedItem",
+        "accept_access_request",
+        "add_collection_item",
+        "add_space_secret",
+        "add_space_variable",
+        "auth_check",
+        "cancel_access_request",
+        "cancel_job",
+        "change_discussion_status",
+        "comment_discussion",
+        "create_branch",
+        "create_collection",
+        "create_commit",
+        "create_discussion",
+        "create_inference_endpoint",
+        "create_inference_endpoint_from_catalog",
+        "create_pull_request",
+        "create_repo",
+        "create_scheduled_job",
+        "create_scheduled_uv_job",
+        "create_tag",
+        "create_webhook",
+        "dataset_info",
+        "delete_branch",
+        "delete_collection",
+        "delete_collection_item",
+        "delete_file",
+        "delete_folder",
+        "delete_inference_endpoint",
+        "delete_repo",
+        "delete_scheduled_job",
+        "delete_space_secret",
+        "delete_space_storage",
+        "delete_space_variable",
+        "delete_tag",
+        "delete_webhook",
+        "disable_webhook",
+        "duplicate_space",
+        "edit_discussion_comment",
+        "enable_webhook",
+        "fetch_job_logs",
+        "file_exists",
+        "get_collection",
+        "get_dataset_tags",
+        "get_discussion_details",
+        "get_full_repo_name",
+        "get_inference_endpoint",
+        "get_model_tags",
+        "get_organization_overview",
+        "get_paths_info",
+        "get_repo_discussions",
+        "get_safetensors_metadata",
+        "get_space_runtime",
+        "get_space_variables",
+        "get_token_permission",
+        "get_user_overview",
+        "get_webhook",
+        "grant_access",
+        "inspect_job",
+        "inspect_scheduled_job",
+        "list_accepted_access_requests",
+        "list_collections",
+        "list_datasets",
+        "list_inference_catalog",
+        "list_inference_endpoints",
+        "list_jobs",
+        "list_lfs_files",
+        "list_liked_repos",
+        "list_models",
+        "list_organization_members",
+        "list_papers",
+        "list_pending_access_requests",
+        "list_rejected_access_requests",
+        "list_repo_commits",
+        "list_repo_files",
+        "list_repo_likers",
+        "list_repo_refs",
+        "list_repo_tree",
+        "list_spaces",
+        "list_user_followers",
+        "list_user_following",
+        "list_webhooks",
+        "merge_pull_request",
+        "model_info",
+        "move_repo",
+        "paper_info",
+        "parse_safetensors_file_metadata",
+        "pause_inference_endpoint",
+        "pause_space",
+        "permanently_delete_lfs_files",
+        "preupload_lfs_files",
+        "reject_access_request",
+        "rename_discussion",
+        "repo_exists",
+        "repo_info",
+        "repo_type_and_id_from_hf_id",
+        "request_space_hardware",
+        "request_space_storage",
+        "restart_space",
+        "resume_inference_endpoint",
+        "resume_scheduled_job",
+        "revision_exists",
+        "run_as_future",
+        "run_job",
+        "run_uv_job",
+        "scale_to_zero_inference_endpoint",
+        "set_space_sleep_time",
+        "space_info",
+        "super_squash_history",
+        "suspend_scheduled_job",
+        "unlike",
+        "update_collection_item",
+        "update_collection_metadata",
+        "update_inference_endpoint",
+        "update_repo_settings",
+        "update_repo_visibility",
+        "update_webhook",
+        "upload_file",
+        "upload_folder",
+        "upload_large_folder",
+        "whoami",
+    ],
+    "hf_file_system": [
+        "HfFileSystem",
+        "HfFileSystemFile",
+        "HfFileSystemResolvedPath",
+        "HfFileSystemStreamFile",
+    ],
+    "hub_mixin": [
+        "ModelHubMixin",
+        "PyTorchModelHubMixin",
+    ],
+    "inference._client": [
+        "InferenceClient",
+        "InferenceTimeoutError",
+    ],
+    "inference._generated._async_client": [
+        "AsyncInferenceClient",
+    ],
+    "inference._generated.types": [
+        "AudioClassificationInput",
+        "AudioClassificationOutputElement",
+        "AudioClassificationOutputTransform",
+        "AudioClassificationParameters",
+        "AudioToAudioInput",
+        "AudioToAudioOutputElement",
+        "AutomaticSpeechRecognitionEarlyStoppingEnum",
+        "AutomaticSpeechRecognitionGenerationParameters",
+        "AutomaticSpeechRecognitionInput",
+        "AutomaticSpeechRecognitionOutput",
+        "AutomaticSpeechRecognitionOutputChunk",
+        "AutomaticSpeechRecognitionParameters",
+        "ChatCompletionInput",
+        "ChatCompletionInputFunctionDefinition",
+        "ChatCompletionInputFunctionName",
+        "ChatCompletionInputGrammarType",
+        "ChatCompletionInputJSONSchema",
+        "ChatCompletionInputMessage",
+        "ChatCompletionInputMessageChunk",
+        "ChatCompletionInputMessageChunkType",
+        "ChatCompletionInputResponseFormatJSONObject",
+        "ChatCompletionInputResponseFormatJSONSchema",
+        "ChatCompletionInputResponseFormatText",
+        "ChatCompletionInputStreamOptions",
+        "ChatCompletionInputTool",
+        "ChatCompletionInputToolCall",
+        "ChatCompletionInputToolChoiceClass",
+        "ChatCompletionInputToolChoiceEnum",
+        "ChatCompletionInputURL",
+        "ChatCompletionOutput",
+        "ChatCompletionOutputComplete",
+        "ChatCompletionOutputFunctionDefinition",
+        "ChatCompletionOutputLogprob",
+        "ChatCompletionOutputLogprobs",
+        "ChatCompletionOutputMessage",
+        "ChatCompletionOutputToolCall",
+        "ChatCompletionOutputTopLogprob",
+        "ChatCompletionOutputUsage",
+        "ChatCompletionStreamOutput",
+        "ChatCompletionStreamOutputChoice",
+        "ChatCompletionStreamOutputDelta",
+        "ChatCompletionStreamOutputDeltaToolCall",
+        "ChatCompletionStreamOutputFunction",
+        "ChatCompletionStreamOutputLogprob",
+        "ChatCompletionStreamOutputLogprobs",
+        "ChatCompletionStreamOutputTopLogprob",
+        "ChatCompletionStreamOutputUsage",
+        "DepthEstimationInput",
+        "DepthEstimationOutput",
+        "DocumentQuestionAnsweringInput",
+        "DocumentQuestionAnsweringInputData",
+        "DocumentQuestionAnsweringOutputElement",
+        "DocumentQuestionAnsweringParameters",
+        "FeatureExtractionInput",
+        "FeatureExtractionInputTruncationDirection",
+        "FillMaskInput",
+        "FillMaskOutputElement",
+        "FillMaskParameters",
+        "ImageClassificationInput",
+        "ImageClassificationOutputElement",
+        "ImageClassificationOutputTransform",
+        "ImageClassificationParameters",
+        "ImageSegmentationInput",
+        "ImageSegmentationOutputElement",
+        "ImageSegmentationParameters",
+        "ImageSegmentationSubtask",
+        "ImageToImageInput",
+        "ImageToImageOutput",
+        "ImageToImageParameters",
+        "ImageToImageTargetSize",
+        "ImageToTextEarlyStoppingEnum",
+        "ImageToTextGenerationParameters",
+        "ImageToTextInput",
+        "ImageToTextOutput",
+        "ImageToTextParameters",
+        "ImageToVideoInput",
+        "ImageToVideoOutput",
+        "ImageToVideoParameters",
+        "ImageToVideoTargetSize",
+        "ObjectDetectionBoundingBox",
+        "ObjectDetectionInput",
+        "ObjectDetectionOutputElement",
+        "ObjectDetectionParameters",
+        "Padding",
+        "QuestionAnsweringInput",
+        "QuestionAnsweringInputData",
+        "QuestionAnsweringOutputElement",
+        "QuestionAnsweringParameters",
+        "SentenceSimilarityInput",
+        "SentenceSimilarityInputData",
+        "SummarizationInput",
+        "SummarizationOutput",
+        "SummarizationParameters",
+        "SummarizationTruncationStrategy",
+        "TableQuestionAnsweringInput",
+        "TableQuestionAnsweringInputData",
+        "TableQuestionAnsweringOutputElement",
+        "TableQuestionAnsweringParameters",
+        "Text2TextGenerationInput",
+        "Text2TextGenerationOutput",
+        "Text2TextGenerationParameters",
+        "Text2TextGenerationTruncationStrategy",
+        "TextClassificationInput",
+        "TextClassificationOutputElement",
+        "TextClassificationOutputTransform",
+        "TextClassificationParameters",
+        "TextGenerationInput",
+        "TextGenerationInputGenerateParameters",
+        "TextGenerationInputGrammarType",
+        "TextGenerationOutput",
+        "TextGenerationOutputBestOfSequence",
+        "TextGenerationOutputDetails",
+        "TextGenerationOutputFinishReason",
+        "TextGenerationOutputPrefillToken",
+        "TextGenerationOutputToken",
+        "TextGenerationStreamOutput",
+        "TextGenerationStreamOutputStreamDetails",
+        "TextGenerationStreamOutputToken",
+        "TextToAudioEarlyStoppingEnum",
+        "TextToAudioGenerationParameters",
+        "TextToAudioInput",
+        "TextToAudioOutput",
+        "TextToAudioParameters",
+        "TextToImageInput",
+        "TextToImageOutput",
+        "TextToImageParameters",
+        "TextToSpeechEarlyStoppingEnum",
+        "TextToSpeechGenerationParameters",
+        "TextToSpeechInput",
+        "TextToSpeechOutput",
+        "TextToSpeechParameters",
+        "TextToVideoInput",
+        "TextToVideoOutput",
+        "TextToVideoParameters",
+        "TokenClassificationAggregationStrategy",
+        "TokenClassificationInput",
+        "TokenClassificationOutputElement",
+        "TokenClassificationParameters",
+        "TranslationInput",
+        "TranslationOutput",
+        "TranslationParameters",
+        "TranslationTruncationStrategy",
+        "TypeEnum",
+        "VideoClassificationInput",
+        "VideoClassificationOutputElement",
+        "VideoClassificationOutputTransform",
+        "VideoClassificationParameters",
+        "VisualQuestionAnsweringInput",
+        "VisualQuestionAnsweringInputData",
+        "VisualQuestionAnsweringOutputElement",
+        "VisualQuestionAnsweringParameters",
+        "ZeroShotClassificationInput",
+        "ZeroShotClassificationOutputElement",
+        "ZeroShotClassificationParameters",
+        "ZeroShotImageClassificationInput",
+        "ZeroShotImageClassificationOutputElement",
+        "ZeroShotImageClassificationParameters",
+        "ZeroShotObjectDetectionBoundingBox",
+        "ZeroShotObjectDetectionInput",
+        "ZeroShotObjectDetectionOutputElement",
+        "ZeroShotObjectDetectionParameters",
+    ],
+    "inference._mcp.agent": [
+        "Agent",
+    ],
+    "inference._mcp.mcp_client": [
+        "MCPClient",
+    ],
+    "inference_api": [
+        "InferenceApi",
+    ],
+    "keras_mixin": [
+        "KerasModelHubMixin",
+        "from_pretrained_keras",
+        "push_to_hub_keras",
+        "save_pretrained_keras",
+    ],
+    "repocard": [
+        "DatasetCard",
+        "ModelCard",
+        "RepoCard",
+        "SpaceCard",
+        "metadata_eval_result",
+        "metadata_load",
+        "metadata_save",
+        "metadata_update",
+    ],
+    "repocard_data": [
+        "CardData",
+        "DatasetCardData",
+        "EvalResult",
+        "ModelCardData",
+        "SpaceCardData",
+    ],
+    "repository": [
+        "Repository",
+    ],
+    "serialization": [
+        "StateDictSplit",
+        "get_tf_storage_size",
+        "get_torch_storage_id",
+        "get_torch_storage_size",
+        "load_state_dict_from_file",
+        "load_torch_model",
+        "save_torch_model",
+        "save_torch_state_dict",
+        "split_state_dict_into_shards_factory",
+        "split_tf_state_dict_into_shards",
+        "split_torch_state_dict_into_shards",
+    ],
+    "serialization._dduf": [
+        "DDUFEntry",
+        "export_entries_as_dduf",
+        "export_folder_as_dduf",
+        "read_dduf_file",
+    ],
+    "utils": [
+        "CacheNotFound",
+        "CachedFileInfo",
+        "CachedRepoInfo",
+        "CachedRevisionInfo",
+        "CorruptedCacheException",
+        "DeleteCacheStrategy",
+        "HFCacheInfo",
+        "HfFolder",
+        "cached_assets_path",
+        "configure_http_backend",
+        "dump_environment_info",
+        "get_session",
+        "get_token",
+        "logging",
+        "scan_cache_dir",
+    ],
+}
+
+# WARNING: __all__ is generated automatically, Any manual edit will be lost when re-generating this file !
+#
+# To update the static imports, please run the following command and commit the changes.
+# ```
+# # Use script
+# python utils/check_all_variable.py --update
+#
+# # Or run style on codebase
+# make style
+# ```
+
+__all__ = [
+    "Agent",
+    "AsyncInferenceClient",
+    "AudioClassificationInput",
+    "AudioClassificationOutputElement",
+    "AudioClassificationOutputTransform",
+    "AudioClassificationParameters",
+    "AudioToAudioInput",
+    "AudioToAudioOutputElement",
+    "AutomaticSpeechRecognitionEarlyStoppingEnum",
+    "AutomaticSpeechRecognitionGenerationParameters",
+    "AutomaticSpeechRecognitionInput",
+    "AutomaticSpeechRecognitionOutput",
+    "AutomaticSpeechRecognitionOutputChunk",
+    "AutomaticSpeechRecognitionParameters",
+    "CONFIG_NAME",
+    "CacheNotFound",
+    "CachedFileInfo",
+    "CachedRepoInfo",
+    "CachedRevisionInfo",
+    "CardData",
+    "ChatCompletionInput",
+    "ChatCompletionInputFunctionDefinition",
+    "ChatCompletionInputFunctionName",
+    "ChatCompletionInputGrammarType",
+    "ChatCompletionInputJSONSchema",
+    "ChatCompletionInputMessage",
+    "ChatCompletionInputMessageChunk",
+    "ChatCompletionInputMessageChunkType",
+    "ChatCompletionInputResponseFormatJSONObject",
+    "ChatCompletionInputResponseFormatJSONSchema",
+    "ChatCompletionInputResponseFormatText",
+    "ChatCompletionInputStreamOptions",
+    "ChatCompletionInputTool",
+    "ChatCompletionInputToolCall",
+    "ChatCompletionInputToolChoiceClass",
+    "ChatCompletionInputToolChoiceEnum",
+    "ChatCompletionInputURL",
+    "ChatCompletionOutput",
+    "ChatCompletionOutputComplete",
+    "ChatCompletionOutputFunctionDefinition",
+    "ChatCompletionOutputLogprob",
+    "ChatCompletionOutputLogprobs",
+    "ChatCompletionOutputMessage",
+    "ChatCompletionOutputToolCall",
+    "ChatCompletionOutputTopLogprob",
+    "ChatCompletionOutputUsage",
+    "ChatCompletionStreamOutput",
+    "ChatCompletionStreamOutputChoice",
+    "ChatCompletionStreamOutputDelta",
+    "ChatCompletionStreamOutputDeltaToolCall",
+    "ChatCompletionStreamOutputFunction",
+    "ChatCompletionStreamOutputLogprob",
+    "ChatCompletionStreamOutputLogprobs",
+    "ChatCompletionStreamOutputTopLogprob",
+    "ChatCompletionStreamOutputUsage",
+    "Collection",
+    "CollectionItem",
+    "CommitInfo",
+    "CommitOperation",
+    "CommitOperationAdd",
+    "CommitOperationCopy",
+    "CommitOperationDelete",
+    "CommitScheduler",
+    "CorruptedCacheException",
+    "DDUFEntry",
+    "DatasetCard",
+    "DatasetCardData",
+    "DatasetInfo",
+    "DeleteCacheStrategy",
+    "DepthEstimationInput",
+    "DepthEstimationOutput",
+    "Discussion",
+    "DiscussionComment",
+    "DiscussionCommit",
+    "DiscussionEvent",
+    "DiscussionStatusChange",
+    "DiscussionTitleChange",
+    "DiscussionWithDetails",
+    "DocumentQuestionAnsweringInput",
+    "DocumentQuestionAnsweringInputData",
+    "DocumentQuestionAnsweringOutputElement",
+    "DocumentQuestionAnsweringParameters",
+    "EvalResult",
+    "FLAX_WEIGHTS_NAME",
+    "FeatureExtractionInput",
+    "FeatureExtractionInputTruncationDirection",
+    "FillMaskInput",
+    "FillMaskOutputElement",
+    "FillMaskParameters",
+    "GitCommitInfo",
+    "GitRefInfo",
+    "GitRefs",
+    "HFCacheInfo",
+    "HFSummaryWriter",
+    "HUGGINGFACE_CO_URL_HOME",
+    "HUGGINGFACE_CO_URL_TEMPLATE",
+    "HfApi",
+    "HfFileMetadata",
+    "HfFileSystem",
+    "HfFileSystemFile",
+    "HfFileSystemResolvedPath",
+    "HfFileSystemStreamFile",
+    "HfFolder",
+    "ImageClassificationInput",
+    "ImageClassificationOutputElement",
+    "ImageClassificationOutputTransform",
+    "ImageClassificationParameters",
+    "ImageSegmentationInput",
+    "ImageSegmentationOutputElement",
+    "ImageSegmentationParameters",
+    "ImageSegmentationSubtask",
+    "ImageToImageInput",
+    "ImageToImageOutput",
+    "ImageToImageParameters",
+    "ImageToImageTargetSize",
+    "ImageToTextEarlyStoppingEnum",
+    "ImageToTextGenerationParameters",
+    "ImageToTextInput",
+    "ImageToTextOutput",
+    "ImageToTextParameters",
+    "ImageToVideoInput",
+    "ImageToVideoOutput",
+    "ImageToVideoParameters",
+    "ImageToVideoTargetSize",
+    "InferenceApi",
+    "InferenceClient",
+    "InferenceEndpoint",
+    "InferenceEndpointError",
+    "InferenceEndpointStatus",
+    "InferenceEndpointTimeoutError",
+    "InferenceEndpointType",
+    "InferenceTimeoutError",
+    "JobInfo",
+    "JobOwner",
+    "JobStage",
+    "JobStatus",
+    "KerasModelHubMixin",
+    "MCPClient",
+    "ModelCard",
+    "ModelCardData",
+    "ModelHubMixin",
+    "ModelInfo",
+    "OAuthInfo",
+    "OAuthOrgInfo",
+    "OAuthUserInfo",
+    "ObjectDetectionBoundingBox",
+    "ObjectDetectionInput",
+    "ObjectDetectionOutputElement",
+    "ObjectDetectionParameters",
+    "Organization",
+    "PYTORCH_WEIGHTS_NAME",
+    "Padding",
+    "PyTorchModelHubMixin",
+    "QuestionAnsweringInput",
+    "QuestionAnsweringInputData",
+    "QuestionAnsweringOutputElement",
+    "QuestionAnsweringParameters",
+    "REPO_TYPE_DATASET",
+    "REPO_TYPE_MODEL",
+    "REPO_TYPE_SPACE",
+    "RepoCard",
+    "RepoUrl",
+    "Repository",
+    "SentenceSimilarityInput",
+    "SentenceSimilarityInputData",
+    "SpaceCard",
+    "SpaceCardData",
+    "SpaceHardware",
+    "SpaceInfo",
+    "SpaceRuntime",
+    "SpaceStage",
+    "SpaceStorage",
+    "SpaceVariable",
+    "StateDictSplit",
+    "SummarizationInput",
+    "SummarizationOutput",
+    "SummarizationParameters",
+    "SummarizationTruncationStrategy",
+    "TF2_WEIGHTS_NAME",
+    "TF_WEIGHTS_NAME",
+    "TableQuestionAnsweringInput",
+    "TableQuestionAnsweringInputData",
+    "TableQuestionAnsweringOutputElement",
+    "TableQuestionAnsweringParameters",
+    "Text2TextGenerationInput",
+    "Text2TextGenerationOutput",
+    "Text2TextGenerationParameters",
+    "Text2TextGenerationTruncationStrategy",
+    "TextClassificationInput",
+    "TextClassificationOutputElement",
+    "TextClassificationOutputTransform",
+    "TextClassificationParameters",
+    "TextGenerationInput",
+    "TextGenerationInputGenerateParameters",
+    "TextGenerationInputGrammarType",
+    "TextGenerationOutput",
+    "TextGenerationOutputBestOfSequence",
+    "TextGenerationOutputDetails",
+    "TextGenerationOutputFinishReason",
+    "TextGenerationOutputPrefillToken",
+    "TextGenerationOutputToken",
+    "TextGenerationStreamOutput",
+    "TextGenerationStreamOutputStreamDetails",
+    "TextGenerationStreamOutputToken",
+    "TextToAudioEarlyStoppingEnum",
+    "TextToAudioGenerationParameters",
+    "TextToAudioInput",
+    "TextToAudioOutput",
+    "TextToAudioParameters",
+    "TextToImageInput",
+    "TextToImageOutput",
+    "TextToImageParameters",
+    "TextToSpeechEarlyStoppingEnum",
+    "TextToSpeechGenerationParameters",
+    "TextToSpeechInput",
+    "TextToSpeechOutput",
+    "TextToSpeechParameters",
+    "TextToVideoInput",
+    "TextToVideoOutput",
+    "TextToVideoParameters",
+    "TokenClassificationAggregationStrategy",
+    "TokenClassificationInput",
+    "TokenClassificationOutputElement",
+    "TokenClassificationParameters",
+    "TranslationInput",
+    "TranslationOutput",
+    "TranslationParameters",
+    "TranslationTruncationStrategy",
+    "TypeEnum",
+    "User",
+    "UserLikes",
+    "VideoClassificationInput",
+    "VideoClassificationOutputElement",
+    "VideoClassificationOutputTransform",
+    "VideoClassificationParameters",
+    "VisualQuestionAnsweringInput",
+    "VisualQuestionAnsweringInputData",
+    "VisualQuestionAnsweringOutputElement",
+    "VisualQuestionAnsweringParameters",
+    "WebhookInfo",
+    "WebhookPayload",
+    "WebhookPayloadComment",
+    "WebhookPayloadDiscussion",
+    "WebhookPayloadDiscussionChanges",
+    "WebhookPayloadEvent",
+    "WebhookPayloadMovedTo",
+    "WebhookPayloadRepo",
+    "WebhookPayloadUrl",
+    "WebhookPayloadWebhook",
+    "WebhookWatchedItem",
+    "WebhooksServer",
+    "ZeroShotClassificationInput",
+    "ZeroShotClassificationOutputElement",
+    "ZeroShotClassificationParameters",
+    "ZeroShotImageClassificationInput",
+    "ZeroShotImageClassificationOutputElement",
+    "ZeroShotImageClassificationParameters",
+    "ZeroShotObjectDetectionBoundingBox",
+    "ZeroShotObjectDetectionInput",
+    "ZeroShotObjectDetectionOutputElement",
+    "ZeroShotObjectDetectionParameters",
+    "_CACHED_NO_EXIST",
+    "_save_pretrained_fastai",
+    "accept_access_request",
+    "add_collection_item",
+    "add_space_secret",
+    "add_space_variable",
+    "attach_huggingface_oauth",
+    "auth_check",
+    "auth_list",
+    "auth_switch",
+    "cached_assets_path",
+    "cancel_access_request",
+    "cancel_job",
+    "change_discussion_status",
+    "comment_discussion",
+    "configure_http_backend",
+    "create_branch",
+    "create_collection",
+    "create_commit",
+    "create_discussion",
+    "create_inference_endpoint",
+    "create_inference_endpoint_from_catalog",
+    "create_pull_request",
+    "create_repo",
+    "create_scheduled_job",
+    "create_scheduled_uv_job",
+    "create_tag",
+    "create_webhook",
+    "dataset_info",
+    "delete_branch",
+    "delete_collection",
+    "delete_collection_item",
+    "delete_file",
+    "delete_folder",
+    "delete_inference_endpoint",
+    "delete_repo",
+    "delete_scheduled_job",
+    "delete_space_secret",
+    "delete_space_storage",
+    "delete_space_variable",
+    "delete_tag",
+    "delete_webhook",
+    "disable_webhook",
+    "dump_environment_info",
+    "duplicate_space",
+    "edit_discussion_comment",
+    "enable_webhook",
+    "export_entries_as_dduf",
+    "export_folder_as_dduf",
+    "fetch_job_logs",
+    "file_exists",
+    "from_pretrained_fastai",
+    "from_pretrained_keras",
+    "get_collection",
+    "get_dataset_tags",
+    "get_discussion_details",
+    "get_full_repo_name",
+    "get_hf_file_metadata",
+    "get_inference_endpoint",
+    "get_model_tags",
+    "get_organization_overview",
+    "get_paths_info",
+    "get_repo_discussions",
+    "get_safetensors_metadata",
+    "get_session",
+    "get_space_runtime",
+    "get_space_variables",
+    "get_tf_storage_size",
+    "get_token",
+    "get_token_permission",
+    "get_torch_storage_id",
+    "get_torch_storage_size",
+    "get_user_overview",
+    "get_webhook",
+    "grant_access",
+    "hf_hub_download",
+    "hf_hub_url",
+    "inspect_job",
+    "inspect_scheduled_job",
+    "interpreter_login",
+    "list_accepted_access_requests",
+    "list_collections",
+    "list_datasets",
+    "list_inference_catalog",
+    "list_inference_endpoints",
+    "list_jobs",
+    "list_lfs_files",
+    "list_liked_repos",
+    "list_models",
+    "list_organization_members",
+    "list_papers",
+    "list_pending_access_requests",
+    "list_rejected_access_requests",
+    "list_repo_commits",
+    "list_repo_files",
+    "list_repo_likers",
+    "list_repo_refs",
+    "list_repo_tree",
+    "list_spaces",
+    "list_user_followers",
+    "list_user_following",
+    "list_webhooks",
+    "load_state_dict_from_file",
+    "load_torch_model",
+    "logging",
+    "login",
+    "logout",
+    "merge_pull_request",
+    "metadata_eval_result",
+    "metadata_load",
+    "metadata_save",
+    "metadata_update",
+    "model_info",
+    "move_repo",
+    "notebook_login",
+    "paper_info",
+    "parse_huggingface_oauth",
+    "parse_safetensors_file_metadata",
+    "pause_inference_endpoint",
+    "pause_space",
+    "permanently_delete_lfs_files",
+    "preupload_lfs_files",
+    "push_to_hub_fastai",
+    "push_to_hub_keras",
+    "read_dduf_file",
+    "reject_access_request",
+    "rename_discussion",
+    "repo_exists",
+    "repo_info",
+    "repo_type_and_id_from_hf_id",
+    "request_space_hardware",
+    "request_space_storage",
+    "restart_space",
+    "resume_inference_endpoint",
+    "resume_scheduled_job",
+    "revision_exists",
+    "run_as_future",
+    "run_job",
+    "run_uv_job",
+    "save_pretrained_keras",
+    "save_torch_model",
+    "save_torch_state_dict",
+    "scale_to_zero_inference_endpoint",
+    "scan_cache_dir",
+    "set_space_sleep_time",
+    "snapshot_download",
+    "space_info",
+    "split_state_dict_into_shards_factory",
+    "split_tf_state_dict_into_shards",
+    "split_torch_state_dict_into_shards",
+    "super_squash_history",
+    "suspend_scheduled_job",
+    "try_to_load_from_cache",
+    "unlike",
+    "update_collection_item",
+    "update_collection_metadata",
+    "update_inference_endpoint",
+    "update_repo_settings",
+    "update_repo_visibility",
+    "update_webhook",
+    "upload_file",
+    "upload_folder",
+    "upload_large_folder",
+    "webhook_endpoint",
+    "whoami",
+]
+
+
+def _attach(package_name, submodules=None, submod_attrs=None):
+    """Attach lazily loaded submodules, functions, or other attributes.
+
+    Typically, modules import submodules and attributes as follows:
+
+    ```py
+    import mysubmodule
+    import anothersubmodule
+
+    from .foo import someattr
+    ```
+
+    The idea is to replace a package's `__getattr__`, `__dir__`, such that all imports
+    work exactly the way they would with normal imports, except that the import occurs
+    upon first use.
+
+    The typical way to call this function, replacing the above imports, is:
+
+    ```python
+    __getattr__, __dir__ = lazy.attach(
+        __name__,
+        ['mysubmodule', 'anothersubmodule'],
+        {'foo': ['someattr']}
+    )
+    ```
+    This functionality requires Python 3.7 or higher.
+
+    Args:
+        package_name (`str`):
+            Typically use `__name__`.
+        submodules (`set`):
+            List of submodules to attach.
+        submod_attrs (`dict`):
+            Dictionary of submodule -> list of attributes / functions.
+            These attributes are imported as they are used.
+
+    Returns:
+        __getattr__, __dir__, __all__
+
+    """
+    if submod_attrs is None:
+        submod_attrs = {}
+
+    if submodules is None:
+        submodules = set()
+    else:
+        submodules = set(submodules)
+
+    attr_to_modules = {attr: mod for mod, attrs in submod_attrs.items() for attr in attrs}
+
+    def __getattr__(name):
+        if name in submodules:
+            try:
+                return importlib.import_module(f"{package_name}.{name}")
+            except Exception as e:
+                print(f"Error importing {package_name}.{name}: {e}")
+                raise
+        elif name in attr_to_modules:
+            submod_path = f"{package_name}.{attr_to_modules[name]}"
+            try:
+                submod = importlib.import_module(submod_path)
+            except Exception as e:
+                print(f"Error importing {submod_path}: {e}")
+                raise
+            attr = getattr(submod, name)
+
+            # If the attribute lives in a file (module) with the same
+            # name as the attribute, ensure that the attribute and *not*
+            # the module is accessible on the package.
+            if name == attr_to_modules[name]:
+                pkg = sys.modules[package_name]
+                pkg.__dict__[name] = attr
+
+            return attr
+        else:
+            raise AttributeError(f"No {package_name} attribute {name}")
+
+    def __dir__():
+        return __all__
+
+    return __getattr__, __dir__
+
+
+__getattr__, __dir__ = _attach(__name__, submodules=[], submod_attrs=_SUBMOD_ATTRS)
+
+if os.environ.get("EAGER_IMPORT", ""):
+    for attr in __all__:
+        __getattr__(attr)
+
+# WARNING: any content below this statement is generated automatically. Any manual edit
+# will be lost when re-generating this file !
+#
+# To update the static imports, please run the following command and commit the changes.
+# ```
+# # Use script
+# python utils/check_static_imports.py --update
+#
+# # Or run style on codebase
+# make style
+# ```
+if TYPE_CHECKING:  # pragma: no cover
+    from ._commit_scheduler import CommitScheduler  # noqa: F401
+    from ._inference_endpoints import (
+        InferenceEndpoint,  # noqa: F401
+        InferenceEndpointError,  # noqa: F401
+        InferenceEndpointStatus,  # noqa: F401
+        InferenceEndpointTimeoutError,  # noqa: F401
+        InferenceEndpointType,  # noqa: F401
+    )
+    from ._jobs_api import (
+        JobInfo,  # noqa: F401
+        JobOwner,  # noqa: F401
+        JobStage,  # noqa: F401
+        JobStatus,  # noqa: F401
+    )
+    from ._login import (
+        auth_list,  # noqa: F401
+        auth_switch,  # noqa: F401
+        interpreter_login,  # noqa: F401
+        login,  # noqa: F401
+        logout,  # noqa: F401
+        notebook_login,  # noqa: F401
+    )
+    from ._oauth import (
+        OAuthInfo,  # noqa: F401
+        OAuthOrgInfo,  # noqa: F401
+        OAuthUserInfo,  # noqa: F401
+        attach_huggingface_oauth,  # noqa: F401
+        parse_huggingface_oauth,  # noqa: F401
+    )
+    from ._snapshot_download import snapshot_download  # noqa: F401
+    from ._space_api import (
+        SpaceHardware,  # noqa: F401
+        SpaceRuntime,  # noqa: F401
+        SpaceStage,  # noqa: F401
+        SpaceStorage,  # noqa: F401
+        SpaceVariable,  # noqa: F401
+    )
+    from ._tensorboard_logger import HFSummaryWriter  # noqa: F401
+    from ._webhooks_payload import (
+        WebhookPayload,  # noqa: F401
+        WebhookPayloadComment,  # noqa: F401
+        WebhookPayloadDiscussion,  # noqa: F401
+        WebhookPayloadDiscussionChanges,  # noqa: F401
+        WebhookPayloadEvent,  # noqa: F401
+        WebhookPayloadMovedTo,  # noqa: F401
+        WebhookPayloadRepo,  # noqa: F401
+        WebhookPayloadUrl,  # noqa: F401
+        WebhookPayloadWebhook,  # noqa: F401
+    )
+    from ._webhooks_server import (
+        WebhooksServer,  # noqa: F401
+        webhook_endpoint,  # noqa: F401
+    )
+    from .community import (
+        Discussion,  # noqa: F401
+        DiscussionComment,  # noqa: F401
+        DiscussionCommit,  # noqa: F401
+        DiscussionEvent,  # noqa: F401
+        DiscussionStatusChange,  # noqa: F401
+        DiscussionTitleChange,  # noqa: F401
+        DiscussionWithDetails,  # noqa: F401
+    )
+    from .constants import (
+        CONFIG_NAME,  # noqa: F401
+        FLAX_WEIGHTS_NAME,  # noqa: F401
+        HUGGINGFACE_CO_URL_HOME,  # noqa: F401
+        HUGGINGFACE_CO_URL_TEMPLATE,  # noqa: F401
+        PYTORCH_WEIGHTS_NAME,  # noqa: F401
+        REPO_TYPE_DATASET,  # noqa: F401
+        REPO_TYPE_MODEL,  # noqa: F401
+        REPO_TYPE_SPACE,  # noqa: F401
+        TF2_WEIGHTS_NAME,  # noqa: F401
+        TF_WEIGHTS_NAME,  # noqa: F401
+    )
+    from .fastai_utils import (
+        _save_pretrained_fastai,  # noqa: F401
+        from_pretrained_fastai,  # noqa: F401
+        push_to_hub_fastai,  # noqa: F401
+    )
+    from .file_download import (
+        _CACHED_NO_EXIST,  # noqa: F401
+        HfFileMetadata,  # noqa: F401
+        get_hf_file_metadata,  # noqa: F401
+        hf_hub_download,  # noqa: F401
+        hf_hub_url,  # noqa: F401
+        try_to_load_from_cache,  # noqa: F401
+    )
+    from .hf_api import (
+        Collection,  # noqa: F401
+        CollectionItem,  # noqa: F401
+        CommitInfo,  # noqa: F401
+        CommitOperation,  # noqa: F401
+        CommitOperationAdd,  # noqa: F401
+        CommitOperationCopy,  # noqa: F401
+        CommitOperationDelete,  # noqa: F401
+        DatasetInfo,  # noqa: F401
+        GitCommitInfo,  # noqa: F401
+        GitRefInfo,  # noqa: F401
+        GitRefs,  # noqa: F401
+        HfApi,  # noqa: F401
+        ModelInfo,  # noqa: F401
+        Organization,  # noqa: F401
+        RepoUrl,  # noqa: F401
+        SpaceInfo,  # noqa: F401
+        User,  # noqa: F401
+        UserLikes,  # noqa: F401
+        WebhookInfo,  # noqa: F401
+        WebhookWatchedItem,  # noqa: F401
+        accept_access_request,  # noqa: F401
+        add_collection_item,  # noqa: F401
+        add_space_secret,  # noqa: F401
+        add_space_variable,  # noqa: F401
+        auth_check,  # noqa: F401
+        cancel_access_request,  # noqa: F401
+        cancel_job,  # noqa: F401
+        change_discussion_status,  # noqa: F401
+        comment_discussion,  # noqa: F401
+        create_branch,  # noqa: F401
+        create_collection,  # noqa: F401
+        create_commit,  # noqa: F401
+        create_discussion,  # noqa: F401
+        create_inference_endpoint,  # noqa: F401
+        create_inference_endpoint_from_catalog,  # noqa: F401
+        create_pull_request,  # noqa: F401
+        create_repo,  # noqa: F401
+        create_scheduled_job,  # noqa: F401
+        create_scheduled_uv_job,  # noqa: F401
+        create_tag,  # noqa: F401
+        create_webhook,  # noqa: F401
+        dataset_info,  # noqa: F401
+        delete_branch,  # noqa: F401
+        delete_collection,  # noqa: F401
+        delete_collection_item,  # noqa: F401
+        delete_file,  # noqa: F401
+        delete_folder,  # noqa: F401
+        delete_inference_endpoint,  # noqa: F401
+        delete_repo,  # noqa: F401
+        delete_scheduled_job,  # noqa: F401
+        delete_space_secret,  # noqa: F401
+        delete_space_storage,  # noqa: F401
+        delete_space_variable,  # noqa: F401
+        delete_tag,  # noqa: F401
+        delete_webhook,  # noqa: F401
+        disable_webhook,  # noqa: F401
+        duplicate_space,  # noqa: F401
+        edit_discussion_comment,  # noqa: F401
+        enable_webhook,  # noqa: F401
+        fetch_job_logs,  # noqa: F401
+        file_exists,  # noqa: F401
+        get_collection,  # noqa: F401
+        get_dataset_tags,  # noqa: F401
+        get_discussion_details,  # noqa: F401
+        get_full_repo_name,  # noqa: F401
+        get_inference_endpoint,  # noqa: F401
+        get_model_tags,  # noqa: F401
+        get_organization_overview,  # noqa: F401
+        get_paths_info,  # noqa: F401
+        get_repo_discussions,  # noqa: F401
+        get_safetensors_metadata,  # noqa: F401
+        get_space_runtime,  # noqa: F401
+        get_space_variables,  # noqa: F401
+        get_token_permission,  # noqa: F401
+        get_user_overview,  # noqa: F401
+        get_webhook,  # noqa: F401
+        grant_access,  # noqa: F401
+        inspect_job,  # noqa: F401
+        inspect_scheduled_job,  # noqa: F401
+        list_accepted_access_requests,  # noqa: F401
+        list_collections,  # noqa: F401
+        list_datasets,  # noqa: F401
+        list_inference_catalog,  # noqa: F401
+        list_inference_endpoints,  # noqa: F401
+        list_jobs,  # noqa: F401
+        list_lfs_files,  # noqa: F401
+        list_liked_repos,  # noqa: F401
+        list_models,  # noqa: F401
+        list_organization_members,  # noqa: F401
+        list_papers,  # noqa: F401
+        list_pending_access_requests,  # noqa: F401
+        list_rejected_access_requests,  # noqa: F401
+        list_repo_commits,  # noqa: F401
+        list_repo_files,  # noqa: F401
+        list_repo_likers,  # noqa: F401
+        list_repo_refs,  # noqa: F401
+        list_repo_tree,  # noqa: F401
+        list_spaces,  # noqa: F401
+        list_user_followers,  # noqa: F401
+        list_user_following,  # noqa: F401
+        list_webhooks,  # noqa: F401
+        merge_pull_request,  # noqa: F401
+        model_info,  # noqa: F401
+        move_repo,  # noqa: F401
+        paper_info,  # noqa: F401
+        parse_safetensors_file_metadata,  # noqa: F401
+        pause_inference_endpoint,  # noqa: F401
+        pause_space,  # noqa: F401
+        permanently_delete_lfs_files,  # noqa: F401
+        preupload_lfs_files,  # noqa: F401
+        reject_access_request,  # noqa: F401
+        rename_discussion,  # noqa: F401
+        repo_exists,  # noqa: F401
+        repo_info,  # noqa: F401
+        repo_type_and_id_from_hf_id,  # noqa: F401
+        request_space_hardware,  # noqa: F401
+        request_space_storage,  # noqa: F401
+        restart_space,  # noqa: F401
+        resume_inference_endpoint,  # noqa: F401
+        resume_scheduled_job,  # noqa: F401
+        revision_exists,  # noqa: F401
+        run_as_future,  # noqa: F401
+        run_job,  # noqa: F401
+        run_uv_job,  # noqa: F401
+        scale_to_zero_inference_endpoint,  # noqa: F401
+        set_space_sleep_time,  # noqa: F401
+        space_info,  # noqa: F401
+        super_squash_history,  # noqa: F401
+        suspend_scheduled_job,  # noqa: F401
+        unlike,  # noqa: F401
+        update_collection_item,  # noqa: F401
+        update_collection_metadata,  # noqa: F401
+        update_inference_endpoint,  # noqa: F401
+        update_repo_settings,  # noqa: F401
+        update_repo_visibility,  # noqa: F401
+        update_webhook,  # noqa: F401
+        upload_file,  # noqa: F401
+        upload_folder,  # noqa: F401
+        upload_large_folder,  # noqa: F401
+        whoami,  # noqa: F401
+    )
+    from .hf_file_system import (
+        HfFileSystem,  # noqa: F401
+        HfFileSystemFile,  # noqa: F401
+        HfFileSystemResolvedPath,  # noqa: F401
+        HfFileSystemStreamFile,  # noqa: F401
+    )
+    from .hub_mixin import (
+        ModelHubMixin,  # noqa: F401
+        PyTorchModelHubMixin,  # noqa: F401
+    )
+    from .inference._client import (
+        InferenceClient,  # noqa: F401
+        InferenceTimeoutError,  # noqa: F401
+    )
+    from .inference._generated._async_client import AsyncInferenceClient  # noqa: F401
+    from .inference._generated.types import (
+        AudioClassificationInput,  # noqa: F401
+        AudioClassificationOutputElement,  # noqa: F401
+        AudioClassificationOutputTransform,  # noqa: F401
+        AudioClassificationParameters,  # noqa: F401
+        AudioToAudioInput,  # noqa: F401
+        AudioToAudioOutputElement,  # noqa: F401
+        AutomaticSpeechRecognitionEarlyStoppingEnum,  # noqa: F401
+        AutomaticSpeechRecognitionGenerationParameters,  # noqa: F401
+        AutomaticSpeechRecognitionInput,  # noqa: F401
+        AutomaticSpeechRecognitionOutput,  # noqa: F401
+        AutomaticSpeechRecognitionOutputChunk,  # noqa: F401
+        AutomaticSpeechRecognitionParameters,  # noqa: F401
+        ChatCompletionInput,  # noqa: F401
+        ChatCompletionInputFunctionDefinition,  # noqa: F401
+        ChatCompletionInputFunctionName,  # noqa: F401
+        ChatCompletionInputGrammarType,  # noqa: F401
+        ChatCompletionInputJSONSchema,  # noqa: F401
+        ChatCompletionInputMessage,  # noqa: F401
+        ChatCompletionInputMessageChunk,  # noqa: F401
+        ChatCompletionInputMessageChunkType,  # noqa: F401
+        ChatCompletionInputResponseFormatJSONObject,  # noqa: F401
+        ChatCompletionInputResponseFormatJSONSchema,  # noqa: F401
+        ChatCompletionInputResponseFormatText,  # noqa: F401
+        ChatCompletionInputStreamOptions,  # noqa: F401
+        ChatCompletionInputTool,  # noqa: F401
+        ChatCompletionInputToolCall,  # noqa: F401
+        ChatCompletionInputToolChoiceClass,  # noqa: F401
+        ChatCompletionInputToolChoiceEnum,  # noqa: F401
+        ChatCompletionInputURL,  # noqa: F401
+        ChatCompletionOutput,  # noqa: F401
+        ChatCompletionOutputComplete,  # noqa: F401
+        ChatCompletionOutputFunctionDefinition,  # noqa: F401
+        ChatCompletionOutputLogprob,  # noqa: F401
+        ChatCompletionOutputLogprobs,  # noqa: F401
+        ChatCompletionOutputMessage,  # noqa: F401
+        ChatCompletionOutputToolCall,  # noqa: F401
+        ChatCompletionOutputTopLogprob,  # noqa: F401
+        ChatCompletionOutputUsage,  # noqa: F401
+        ChatCompletionStreamOutput,  # noqa: F401
+        ChatCompletionStreamOutputChoice,  # noqa: F401
+        ChatCompletionStreamOutputDelta,  # noqa: F401
+        ChatCompletionStreamOutputDeltaToolCall,  # noqa: F401
+        ChatCompletionStreamOutputFunction,  # noqa: F401
+        ChatCompletionStreamOutputLogprob,  # noqa: F401
+        ChatCompletionStreamOutputLogprobs,  # noqa: F401
+        ChatCompletionStreamOutputTopLogprob,  # noqa: F401
+        ChatCompletionStreamOutputUsage,  # noqa: F401
+        DepthEstimationInput,  # noqa: F401
+        DepthEstimationOutput,  # noqa: F401
+        DocumentQuestionAnsweringInput,  # noqa: F401
+        DocumentQuestionAnsweringInputData,  # noqa: F401
+        DocumentQuestionAnsweringOutputElement,  # noqa: F401
+        DocumentQuestionAnsweringParameters,  # noqa: F401
+        FeatureExtractionInput,  # noqa: F401
+        FeatureExtractionInputTruncationDirection,  # noqa: F401
+        FillMaskInput,  # noqa: F401
+        FillMaskOutputElement,  # noqa: F401
+        FillMaskParameters,  # noqa: F401
+        ImageClassificationInput,  # noqa: F401
+        ImageClassificationOutputElement,  # noqa: F401
+        ImageClassificationOutputTransform,  # noqa: F401
+        ImageClassificationParameters,  # noqa: F401
+        ImageSegmentationInput,  # noqa: F401
+        ImageSegmentationOutputElement,  # noqa: F401
+        ImageSegmentationParameters,  # noqa: F401
+        ImageSegmentationSubtask,  # noqa: F401
+        ImageToImageInput,  # noqa: F401
+        ImageToImageOutput,  # noqa: F401
+        ImageToImageParameters,  # noqa: F401
+        ImageToImageTargetSize,  # noqa: F401
+        ImageToTextEarlyStoppingEnum,  # noqa: F401
+        ImageToTextGenerationParameters,  # noqa: F401
+        ImageToTextInput,  # noqa: F401
+        ImageToTextOutput,  # noqa: F401
+        ImageToTextParameters,  # noqa: F401
+        ImageToVideoInput,  # noqa: F401
+        ImageToVideoOutput,  # noqa: F401
+        ImageToVideoParameters,  # noqa: F401
+        ImageToVideoTargetSize,  # noqa: F401
+        ObjectDetectionBoundingBox,  # noqa: F401
+        ObjectDetectionInput,  # noqa: F401
+        ObjectDetectionOutputElement,  # noqa: F401
+        ObjectDetectionParameters,  # noqa: F401
+        Padding,  # noqa: F401
+        QuestionAnsweringInput,  # noqa: F401
+        QuestionAnsweringInputData,  # noqa: F401
+        QuestionAnsweringOutputElement,  # noqa: F401
+        QuestionAnsweringParameters,  # noqa: F401
+        SentenceSimilarityInput,  # noqa: F401
+        SentenceSimilarityInputData,  # noqa: F401
+        SummarizationInput,  # noqa: F401
+        SummarizationOutput,  # noqa: F401
+        SummarizationParameters,  # noqa: F401
+        SummarizationTruncationStrategy,  # noqa: F401
+        TableQuestionAnsweringInput,  # noqa: F401
+        TableQuestionAnsweringInputData,  # noqa: F401
+        TableQuestionAnsweringOutputElement,  # noqa: F401
+        TableQuestionAnsweringParameters,  # noqa: F401
+        Text2TextGenerationInput,  # noqa: F401
+        Text2TextGenerationOutput,  # noqa: F401
+        Text2TextGenerationParameters,  # noqa: F401
+        Text2TextGenerationTruncationStrategy,  # noqa: F401
+        TextClassificationInput,  # noqa: F401
+        TextClassificationOutputElement,  # noqa: F401
+        TextClassificationOutputTransform,  # noqa: F401
+        TextClassificationParameters,  # noqa: F401
+        TextGenerationInput,  # noqa: F401
+        TextGenerationInputGenerateParameters,  # noqa: F401
+        TextGenerationInputGrammarType,  # noqa: F401
+        TextGenerationOutput,  # noqa: F401
+        TextGenerationOutputBestOfSequence,  # noqa: F401
+        TextGenerationOutputDetails,  # noqa: F401
+        TextGenerationOutputFinishReason,  # noqa: F401
+        TextGenerationOutputPrefillToken,  # noqa: F401
+        TextGenerationOutputToken,  # noqa: F401
+        TextGenerationStreamOutput,  # noqa: F401
+        TextGenerationStreamOutputStreamDetails,  # noqa: F401
+        TextGenerationStreamOutputToken,  # noqa: F401
+        TextToAudioEarlyStoppingEnum,  # noqa: F401
+        TextToAudioGenerationParameters,  # noqa: F401
+        TextToAudioInput,  # noqa: F401
+        TextToAudioOutput,  # noqa: F401
+        TextToAudioParameters,  # noqa: F401
+        TextToImageInput,  # noqa: F401
+        TextToImageOutput,  # noqa: F401
+        TextToImageParameters,  # noqa: F401
+        TextToSpeechEarlyStoppingEnum,  # noqa: F401
+        TextToSpeechGenerationParameters,  # noqa: F401
+        TextToSpeechInput,  # noqa: F401
+        TextToSpeechOutput,  # noqa: F401
+        TextToSpeechParameters,  # noqa: F401
+        TextToVideoInput,  # noqa: F401
+        TextToVideoOutput,  # noqa: F401
+        TextToVideoParameters,  # noqa: F401
+        TokenClassificationAggregationStrategy,  # noqa: F401
+        TokenClassificationInput,  # noqa: F401
+        TokenClassificationOutputElement,  # noqa: F401
+        TokenClassificationParameters,  # noqa: F401
+        TranslationInput,  # noqa: F401
+        TranslationOutput,  # noqa: F401
+        TranslationParameters,  # noqa: F401
+        TranslationTruncationStrategy,  # noqa: F401
+        TypeEnum,  # noqa: F401
+        VideoClassificationInput,  # noqa: F401
+        VideoClassificationOutputElement,  # noqa: F401
+        VideoClassificationOutputTransform,  # noqa: F401
+        VideoClassificationParameters,  # noqa: F401
+        VisualQuestionAnsweringInput,  # noqa: F401
+        VisualQuestionAnsweringInputData,  # noqa: F401
+        VisualQuestionAnsweringOutputElement,  # noqa: F401
+        VisualQuestionAnsweringParameters,  # noqa: F401
+        ZeroShotClassificationInput,  # noqa: F401
+        ZeroShotClassificationOutputElement,  # noqa: F401
+        ZeroShotClassificationParameters,  # noqa: F401
+        ZeroShotImageClassificationInput,  # noqa: F401
+        ZeroShotImageClassificationOutputElement,  # noqa: F401
+        ZeroShotImageClassificationParameters,  # noqa: F401
+        ZeroShotObjectDetectionBoundingBox,  # noqa: F401
+        ZeroShotObjectDetectionInput,  # noqa: F401
+        ZeroShotObjectDetectionOutputElement,  # noqa: F401
+        ZeroShotObjectDetectionParameters,  # noqa: F401
+    )
+    from .inference._mcp.agent import Agent  # noqa: F401
+    from .inference._mcp.mcp_client import MCPClient  # noqa: F401
+    from .inference_api import InferenceApi  # noqa: F401
+    from .keras_mixin import (
+        KerasModelHubMixin,  # noqa: F401
+        from_pretrained_keras,  # noqa: F401
+        push_to_hub_keras,  # noqa: F401
+        save_pretrained_keras,  # noqa: F401
+    )
+    from .repocard import (
+        DatasetCard,  # noqa: F401
+        ModelCard,  # noqa: F401
+        RepoCard,  # noqa: F401
+        SpaceCard,  # noqa: F401
+        metadata_eval_result,  # noqa: F401
+        metadata_load,  # noqa: F401
+        metadata_save,  # noqa: F401
+        metadata_update,  # noqa: F401
+    )
+    from .repocard_data import (
+        CardData,  # noqa: F401
+        DatasetCardData,  # noqa: F401
+        EvalResult,  # noqa: F401
+        ModelCardData,  # noqa: F401
+        SpaceCardData,  # noqa: F401
+    )
+    from .repository import Repository  # noqa: F401
+    from .serialization import (
+        StateDictSplit,  # noqa: F401
+        get_tf_storage_size,  # noqa: F401
+        get_torch_storage_id,  # noqa: F401
+        get_torch_storage_size,  # noqa: F401
+        load_state_dict_from_file,  # noqa: F401
+        load_torch_model,  # noqa: F401
+        save_torch_model,  # noqa: F401
+        save_torch_state_dict,  # noqa: F401
+        split_state_dict_into_shards_factory,  # noqa: F401
+        split_tf_state_dict_into_shards,  # noqa: F401
+        split_torch_state_dict_into_shards,  # noqa: F401
+    )
+    from .serialization._dduf import (
+        DDUFEntry,  # noqa: F401
+        export_entries_as_dduf,  # noqa: F401
+        export_folder_as_dduf,  # noqa: F401
+        read_dduf_file,  # noqa: F401
+    )
+    from .utils import (
+        CachedFileInfo,  # noqa: F401
+        CachedRepoInfo,  # noqa: F401
+        CachedRevisionInfo,  # noqa: F401
+        CacheNotFound,  # noqa: F401
+        CorruptedCacheException,  # noqa: F401
+        DeleteCacheStrategy,  # noqa: F401
+        HFCacheInfo,  # noqa: F401
+        HfFolder,  # noqa: F401
+        cached_assets_path,  # noqa: F401
+        configure_http_backend,  # noqa: F401
+        dump_environment_info,  # noqa: F401
+        get_session,  # noqa: F401
+        get_token,  # noqa: F401
+        logging,  # noqa: F401
+        scan_cache_dir,  # noqa: F401
+    )