# 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.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__ = ()
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