commit: Commit

linenos: range

orig_path: Optional[str]

"""Represents a git repository and allows you to query references, create commit

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."""

# stored as string for easier processing, but annotated as path for clearer intention

_working_tree_dir: Optional[PathLike] = None

git_dir: PathLike

"""The ``.git`` repository directory."""

odb: GitCmdObjectDB

_common_dir: PathLike = ""

# Precompiled regex

re_whitespace = re.compile(r"\s+")

re_hexsha_only = re.compile(r"^(?:[0-9A-Fa-f]{40}|[0-9A-Fa-f]{64})$")

re_hexsha_shortened = re.compile(r"^[0-9A-Fa-f]{4,64}$")

re_author_committer_start = re.compile(r"^(author|committer)")

re_tab_full_line = re.compile(r"^\t(.*)$")

unsafe_git_init_options = [

# Can install hooks that execute during later Git commands:

"--template",

# Redirects the repository metadata to a caller-controlled path:

"--separate-git-dir",

]

"""Options to :manpage:`git-init(1)` that permit unsafe code execution or I/O."""

unsafe_git_clone_options = [

# Executes arbitrary commands:

"--upload-pack",

"-u",

# Can override configuration variables that execute arbitrary commands:

"--config",

"-c",

# Can install hooks that execute during clone:

"--template",

# Redirects the repository metadata to a caller-controlled path:

"--separate-git-dir",

# Fetches from an additional caller-controlled URI:

"--bundle-uri",

]

"""Options to :manpage:`git-clone(1)` that permit unsafe command execution or I/O.

unsafe_git_archive_options = [

# Allows arbitrary command execution through the remote git-upload-archive command.

"--exec",

# Writes output to a caller-controlled filesystem path.

"--output",

"-o",

# Reads from a caller-controlled filesystem path:

"--add-file",

# Injects a caller-controlled path and contents:

"--add-virtual-file",

]

unsafe_git_revision_options = [

# This option allows output to be written to arbitrary files before revision parsing.

"--output",

"-o",

]

unsafe_git_blame_options = unsafe_git_revision_options + [

# Runs a configured text conversion program.

"--textconv",

# These options read from arbitrary files and expose their contents through blame output.

"--contents",

"-S",

"--ignore-revs-file",

]

unsafe_git_diff_options = unsafe_git_revision_options + [

# Treats path operands as arbitrary filesystem paths.

"--no-index",

# Reads caller-controlled order patterns from an arbitrary file.

"-O",

"--orderfile",

]

# 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

def __init__(

self,

path: Optional[PathLike] = None,

odbt: Type[GitCmdObjectDB] = GitCmdObjectDB,

search_parent_directories: bool = False,

expand_vars: bool = False,

*,

_env: Optional[Mapping[str, Optional[str]]] = None,

) -> None:

R"""Create a new :class:`Repo` instance.

# Clones can clear inherited source-storage variables without changing the

# process environment. Apply these overrides to discovery and later calls.

if not isinstance(odbt, type) or not issubclass(odbt, GitCmdObjectDB):

raise ValueError("odbt must be GitCmdObjectDB or a subclass")

if expand_vars:

raise ValueError("Environment variable expansion is unsupported; expand the path explicitly")

environment = dict(_env or {})

git_dir_env = environment.pop("GIT_DIR", os.getenv("GIT_DIR"))

object_dir_env = environment.get("GIT_OBJECT_DIRECTORY", os.getenv("GIT_OBJECT_DIRECTORY"))

if object_dir_env is not None:

object_dir_env = osp.abspath(object_dir_env)

epath = path or git_dir_env

if not epath:

epath = os.getcwd()

epath = os.fspath(epath)

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(epath)

epath = expand_path(epath)

if epath is not None:

if not os.path.exists(epath):

raise NoSuchPathError(epath)

# Resolve storage through Git. Absolutize environment paths before changing

# the command's working directory, preserving Git's process-CWD semantics.

for name in ("GIT_COMMON_DIR", "GIT_OBJECT_DIRECTORY", "GIT_WORK_TREE"):

value = environment.get(name, os.environ.get(name))

if value == "" and name != "GIT_WORK_TREE":

raise InvalidGitRepositoryError(epath)

if value is not None:

environment[name] = osp.abspath(value)

probe = self.GitCommandWrapperType(os.getcwd())

probe._environment.update(GIT_DIR=None, **environment)

explicit_git_dir = not path and bool(git_dir_env)

assert epath is not None

curpath = osp.abspath(os.fspath(epath))

git_dir = None

native = NotImplemented

while True:

dotgit = osp.join(curpath, ".git")

candidate = curpath if explicit_git_dir or not osp.lexists(dotgit) else dotgit

try:

# Git resolves relative gitfile targets using the last forward

# slash in this operand, including on Windows.

native = _backend.discover_repository(candidate, environment, from_worktree=candidate == dotgit)

git_dir = (

probe._call_process_safe("rev_parse", "--resolve-git-dir", to_native_path_linux(candidate))

if native is NotImplemented

else os.fspath(native.git_dir())

)

git_dir = osp.abspath(git_dir)

if osp.isfile(candidate):

# Git canonicalizes gitfile targets. Retain an equivalent

# caller spelling, e.g. /var instead of /private/var on macOS.

parent = osp.dirname(candidate)

try:

relative = osp.relpath(osp.realpath(git_dir), osp.realpath(parent))

except ValueError:

pass # Gitfile targets may be on another Windows drive.

else:

spelling = osp.abspath(osp.join(parent, relative))

if osp.realpath(spelling) == osp.realpath(git_dir):

git_dir = spelling

break

except GitCommandError:

# A malformed .git entry must not cause fallback to a parent repo.

if candidate == dotgit or explicit_git_dir or not search_parent_directories:

break

parent = osp.dirname(curpath)

if parent == curpath:

break

curpath = parent

if git_dir is None:

raise InvalidGitRepositoryError(epath)

checkout = None

if native is NotImplemented and candidate == dotgit and osp.isfile(candidate):

# Let Git select the checkout through the supplied .git file. Its

# administrative directory alone need not identify the worktree.

checkout_probe = self.GitCommandWrapperType(curpath)

checkout_probe._environment.update(GIT_DIR=None, **environment)

checkout = checkout_probe._call_process_safe("rev_parse", "--show-toplevel")

self.git_dir = git_dir

self._discovery_path = git_dir if candidate == curpath else curpath

probe.update_environment(GIT_DIR=git_dir)

try:

if native is not NotImplemented:

self.ref_format = probe._call_process_safe("rev_parse", "--show-ref-format")

else:

# Query the fixed scalar fields together, leaving the path last so

# embedded newlines in the common directory remain unambiguous.

metadata = probe._call_process_safe(

"rev_parse",

"--show-ref-format",

"--show-object-format",

"--is-bare-repository",

"--path-format=absolute",

"--git-common-dir",

)

self.ref_format, self.object_format, bare, self._common_dir = metadata.split("\n", 3)

self._bare = bare == "true"

except GitCommandError as exc:

raise InvalidGitRepositoryError(epath) from exc

if native is not NotImplemented:

self._common_dir = to_native_path_linux(osp.abspath(native.common_dir()))

self.object_format = str(native.object_hash())

workdir = native.workdir()

self._working_tree_dir = environment.get("GIT_WORK_TREE") or (

to_native_path_linux(os.fspath(workdir)) if workdir is not None else None

)

# Gix's configured bare flag also applies to linked worktrees.

self._bare = native.is_bare() and self._working_tree_dir is None

else:

self._working_tree_dir = environment.get("GIT_WORK_TREE") or checkout

if self._working_tree_dir is None and not self._bare and environment.get("GIT_COMMON_DIR") is None:

try:

probe._call_process_safe("config", "--get", "core.worktree")

except GitCommandError as exc:

if exc.status != 1:

raise

else:

# Let Git resolve relative paths and per-worktree configuration.

self._working_tree_dir = probe._call_process_safe("rev_parse", "--show-toplevel")

if self._working_tree_dir is None:

# The worktree registry also resolves administrative directories and

# relative worktree metadata without interpreting gitdir/commondir files.

listing = probe._call_process_safe("worktree", "list", "--porcelain", "-z")

for record in listing.split("\0\0"):

fields = record.split("\0")

if not fields or not fields[0].startswith("worktree ") or "bare" in fields:

continue

worktree = fields[0][9:]

# Git only strips a forward-slash /.git suffix from its registry.

# A Windows gitdir file can instead contain a native backslash.

if osp.basename(worktree) == ".git" and osp.isfile(worktree):

worktree = osp.dirname(worktree)

try:

resolved = probe._call_process_safe(

"rev_parse", "--resolve-git-dir", to_native_path_linux(osp.join(worktree, ".git"))

)

except GitCommandError:

continue

if osp.realpath(resolved) == osp.realpath(git_dir):

self._working_tree_dir = worktree

self._bare = False

break

if self._working_tree_dir is None:

try:

configured_bare = probe._call_process_safe(

"config", "--file", osp.join(self.common_dir, "config"), "--bool", "--get", "core.bare"

)

self._bare = configured_bare == "true"

except GitCommandError as exc:

if exc.status != 1:

raise

if self._working_tree_dir is None and not self._bare:

self._working_tree_dir = osp.dirname(git_dir)

if self._bare:

self._working_tree_dir = None

elif self._working_tree_dir is not None:

# Preserve the caller's spelling of symlinked path prefixes (such as

# /var on macOS), so absolute index paths remain relative to this repo.

for spelling in (curpath, osp.dirname(curpath)):

if osp.realpath(spelling) == osp.realpath(self._working_tree_dir):

self._working_tree_dir = spelling

break

self.working_dir = self._working_tree_dir or self.common_dir

self.git = self.GitCommandWrapperType(self.working_dir)

self.git._repo = weakref.ref(self)

self.git._environment.update(GIT_DIR=git_dir, **environment)

if git_dir_env is None:

self.git._repository_environment["GIT_DIR"] = git_dir

if self._working_tree_dir is not None:

self.git.update_environment(GIT_WORK_TREE=os.fspath(self._working_tree_dir))

if "GIT_WORK_TREE" not in environment:

self.git._repository_environment["GIT_WORK_TREE"] = os.fspath(self._working_tree_dir)

if native is not NotImplemented:

self._empty_tree_hexsha = str(native.empty_tree().id)

else:

with tempfile.TemporaryFile() as empty:

self._empty_tree_hexsha = self.git._call_process_safe(

"hash_object", "-t", "tree", "--stdin", istream=empty

)

self._oid_size = len(self._empty_tree_hexsha) // 2

self._null_binsha = bytes(self._oid_size)

self._null_hexsha = "0" * (self._oid_size * 2)

self.re_hexsha_only = re.compile(r"^[0-9A-Fa-f]{%d}$" % (self._oid_size * 2))

self.re_hexsha_shortened = re.compile(r"^[0-9A-Fa-f]{4,%d}$" % (self._oid_size * 2))

# Special handling, in special times.

rootpath = object_dir_env if object_dir_env is not None else osp.join(self.common_dir, "objects")

self.odb = odbt(rootpath, self.git)

def _get_gix_repository(

self,

*,

command: Optional[Git] = None,

env: Optional[Dict[str, Any]] = None,

query_config: bool = False,

) -> Any:

"""Open a fresh native repository for each operation.

return _backend._open_repository(

command if command is not None else self.git, env or {}, query_config=query_config

)

def __setstate__(self, state: Dict[str, Any]) -> None:

self.__dict__.update(state)

self.git._repo = weakref.ref(self)

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:

"""Release persistent Git object readers.

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 self._working_tree_dir

@property

def common_dir(self) -> PathLike:

"""

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

return Head.list_items(self)

@property

def branches(self) -> "IterableList[Head]":

"""Alias for heads.

return self.heads

@property

def references(self) -> "IterableList[Reference]":

"""A list of :class:`~git.refs.reference.Reference` objects representing tags,

return Reference.list_items(self)

@property

def refs(self) -> "IterableList[Reference]":

"""Alias for references.

return self.references

@property

def index(self) -> "IndexFile":

"""

return IndexFile(self)

@property

def head(self) -> "HEAD":

"""

return HEAD(self, "HEAD")

@property

def remotes(self) -> "IterableList[Remote]":

"""A list of :class:`~git.remote.Remote` objects allowing to access and

return Remote.list_items(self)

def remote(self, name: str = "origin") -> "Remote":

""":return: The remote with the specified name

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 Submodule.list_items(self)

def submodule(self, name: str) -> "Submodule":

""":return: The submodule with the given name

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.

return Submodule.add(self, *args, **kwargs)

def iter_submodules(self, *args: Any, **kwargs: Any) -> Iterator[Submodule]:

"""An iterator yielding Submodule instances.

return RootModule(self).traverse(*args, **kwargs)

def submodule_update(self, *args: Any, **kwargs: Any) -> RootModule:

"""Update the submodules, keeping the repository consistent as it will

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

return TagReference.list_items(self)

def tag(self, path: PathLike) -> TagReference:

"""

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.

return Head.create(self, path, commit, logmsg, force)

def delete_head(self, *heads: "Union[str, Head]", **kwargs: Any) -> None:

"""Delete the given heads.

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.

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.

return Remote.create(self, name, url, **kwargs)

def delete_remote(self, remote: _T_RemoteName) -> _T_RemoteName:

"""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 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(f, git_dir) for f in self.config_level if 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 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.

if rev is None:

return self.head.commit

return to_commit(self.rev_parse(Git._check_revision(rev)))

def iter_trees(self, *args: Any, **kwargs: Any) -> Iterator["Tree"]:

""":return: Iterator yielding :class:`~git.objects.tree.Tree` objects

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.

if rev is None:

return self.head.commit.tree

obj = self.rev_parse(Git._check_revision(rev))

if obj.type == "tree":

obj.path = getattr(obj, "path", "")

return obj

return to_commit(obj).tree

def iter_commits(

self,

rev: Union[str, Commit, "SymbolicReference", None] = None,

paths: Union[PathLike, Sequence[PathLike]] = "",

allow_unsafe_options: bool = False,

**kwargs: Any,

) -> Iterator[Commit]:

"""An iterator of :class:`~git.objects.commit.Commit` objects representing the

if rev is None:

rev = self.head.commit

if not allow_unsafe_options:

Git.check_unsafe_options(

options=Git._option_candidates([rev], kwargs), unsafe_options=self.unsafe_git_revision_options

)

return Commit.iter_items(

self,

rev,

paths,

allow_unsafe_options=allow_unsafe_options,

**kwargs,

)

def merge_base(self, *rev: TBD, allow_unsafe_options: bool = False, **kwargs: Any) -> List[Commit]:

R"""Find the closest common ancestor for the given revision