Clarify detached HEAD access and isolate test branch state (#2230)

Reading head.reference intentionally returns another reference, so it raises
TypeError when HEAD contains a commit ID directly. That contract is useful,
but the public properties did not explain how to obtain the commit instead.
The package tests also assumed the source checkout was attached, sometimes
specifically to master. The seven tests reported in #2230 passed attached
and failed after detaching at the same commit.

Document head.commit.hexsha for both HEAD states, the reference setter/getter
asymmetry, and active_branch's detached-HEAD restriction. Keep TypeError and
the existing exception message prefix, appending a hint to use .commit or
.object. The full diagnostic changes; return types and exception types do
not. The extended API regression failed on the missing hint before this fix
and verifies that commit access still works after detaching.

Make writable test clones attach a branch when cloning leaves HEAD detached,
while retaining clone-created branch/tracking configuration otherwise. Give
the temporary bare remote its own master branch. Move branch-dependent
assertions and tutorial setup to writable fixtures, make remote tests supply
their refspecs, and establish tracking configuration before testing its
removal. Compare @{1} against git rev-parse instead of assuming successive
reflog entries contain different commits.

Add a helper regression using a detached commit that no branch points to,
covering both bare and working clones without reattaching the source. The
Ubuntu/Python 3.14 CI job now also runs the full suite after detaching the
source and after renaming master to another branch, leaving master absent.

Git baseline: /Users/byron/dev/github.com/git/git at
1630431f326e15fcde608827b5ff38422528eb59, Documentation/git-symbolic-ref.adoc,
documents exit status 1 when the requested name is not symbolic. Apple Git
2.50.1 confirmed that symbolic-ref -q HEAD exits 1 for detached HEAD while
rev-parse HEAD still returns its commit ID.

Validation on Python 3.14.7:
- Full pytest suite using GIT_PYTHON_TEST_GIT_REPO_BASE with non-master and
  detached source clones, each without a local master: 760 passed, 81 skipped,
  1 xfailed and 14 subtests passed per state. Six tests needing network or
  process access were run separately outside the sandbox and all passed.
- Ruff check and format --check passed for the repository.
- Sphinx HTML build succeeded; its 12 Python 3.14 annotation warnings are
  byte-for-byte identical to the unchanged baseline's warnings.

Author: codex

.github/workflows/pythonpackage.yml

@@ -170,6 +170,15 @@ jobs:
         pytest --color=yes -p no:sugar --instafail -vv
       continue-on-error: false
 
+    - name: Test detached and non-master source checkouts
+      if: matrix.os-type == 'ubuntu' && matrix.python-version == '3.14'
+      run: |
+        git checkout --detach HEAD
+        pytest --color=yes -p no:sugar --instafail -q
+        git branch -m master gitpython-test-checkout
+        git checkout gitpython-test-checkout
+        pytest --color=yes -p no:sugar --instafail -q
+
     - name: Documentation
       if: matrix.build-docs
       run: |

doc/source/tutorial.rst

@@ -23,7 +23,7 @@ The first step is to create a :class:`git.Repo <git.repo.base.Repo>` object to r
     :start-after: # [1-test_init_repo_object]
     :end-before: # ![1-test_init_repo_object]
 
-In the above example, the directory ``self.rorepo.working_tree_dir`` equals ``/Users/mtrier/Development/git-python`` and is my working repository which contains the ``.git`` directory. You can also initialize GitPython with a *bare* repository.
+In the above example, ``rw_repo.working_tree_dir`` is the path to a working repository which contains the ``.git`` directory. You can also initialize GitPython with a *bare* repository.
 
 .. literalinclude:: ../../test/test_docs.py
     :language: python
@@ -78,6 +78,12 @@ Query relevant repository paths ...
 
 :class:`Heads <git.refs.head.Head>` Heads are branches in git-speak. :class:`References <git.refs.reference.Reference>` are pointers to a specific commit or to other references. Heads and :class:`Tags <git.refs.tag.TagReference>` are a kind of references. GitPython allows you to query them rather intuitively.
 
+To obtain the current commit ID, use ``repo.head.commit.hexsha``. This works both
+on a branch and with a detached HEAD, provided HEAD resolves to an existing commit.
+When ``repo.head.is_detached`` is true, HEAD points directly to a commit and there
+is no active branch: reading ``repo.head.reference`` or ``repo.active_branch``
+raises :exc:`TypeError`. The branch examples below assume an attached HEAD.
+
 .. literalinclude:: ../../test/test_docs.py
     :language: python
     :dedent: 8
@@ -152,7 +158,7 @@ Examining References
     :start-after: # [2-test_references_and_objects]
     :end-before: # ![2-test_references_and_objects]
 
-A :class:`symbolic reference <git.refs.symbolic.SymbolicReference>` is a special case of a reference as it points to another reference instead of a commit.
+A :class:`symbolic reference <git.refs.symbolic.SymbolicReference>` can point to another reference. When detached, it points directly to a commit instead. Reading its ``commit`` property resolves the commit in either state. Assigning a commit to ``reference`` detaches it; reading ``reference`` then raises :exc:`TypeError`.
 
 .. literalinclude:: ../../test/test_docs.py
     :language: python

git/refs/symbolic.py

@@ -59,12 +59,14 @@ def _git_dir(repo: "Repo", path: Union[PathLike, None]) -> PathLike:
 
 
 class SymbolicReference:
-    """Special case of a reference that is symbolic.
+    """A reference that can point to another reference or be detached.
 
-    This does not point to a specific commit, but to another
-    :class:`~git.refs.head.Head`, which itself specifies a commit.
+    An attached :class:`~git.refs.head.HEAD` usually points to a
+    :class:`~git.refs.head.Head`, which itself specifies a commit. A detached
+    :class:`~git.refs.head.HEAD` points directly to a commit instead.
 
-    A typical example for a symbolic reference is :class:`~git.refs.head.HEAD`.
+    Use :attr:`commit` to access the commit in either case, and :attr:`reference`
+    to access the target reference when attached.
     """
 
     __slots__ = ("repo", "path")
@@ -416,7 +418,15 @@ def set_object(
 
     @property
     def commit(self) -> "Commit":
-        """Query or set commits directly"""
+        """The commit this reference resolves to, whether detached or symbolic.
+
+        For example, ``repo.head.commit.hexsha`` returns the current commit ID
+        both on a branch and with a detached HEAD. HEAD must resolve to an
+        existing commit; an unborn branch in an empty repository has none.
+
+        Assigning updates the commit without changing whether this reference
+        is detached.
+        """
         return self._get_commit()
 
     @commit.setter
@@ -443,7 +453,10 @@ def _get_reference(self) -> "Reference":
         """
         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))
+            raise TypeError(
+                "%s is a detached symbolic reference as it points to %r. "
+                "Use .commit or .object to access the target directly." % (self, sha)
+            )
         return cast("Reference", self.from_path(self.repo, target_ref_path))
 
     def set_reference(
@@ -531,6 +544,18 @@ def set_reference(
     # Aliased reference
     @property
     def reference(self) -> "Reference":
+        """The reference we point to, available only when not detached.
+
+        Check :attr:`is_detached` before reading this property if a target
+        reference is required. To access the target commit or object in either
+        state, use :attr:`commit` or :attr:`object` instead.
+
+        Assigning a reference keeps this reference symbolic. Assigning a git
+        object or revision string detaches it; reading this property then raises.
+
+        :raise TypeError:
+            If this reference is detached when reading the property.
+        """
         return self._get_reference()
 
     @reference.setter

git/repo/base.py

@@ -1150,7 +1150,11 @@ def ignored(self, *paths: PathLike) -> List[str]:
 
     @property
     def active_branch(self) -> Head:
-        """The name of the currently active branch.
+        """The currently active branch.
+
+        Check ``repo.head.is_detached`` before accessing this property if HEAD
+        may be detached. To access the current commit in either state, use
+        ``repo.head.commit`` instead.
 
         :raise TypeError:
             If HEAD is detached.

test/lib/helper.py

@@ -139,7 +139,8 @@ def wrapper(self, *args, **kwargs):
 
 def with_rw_repo(working_tree_ref, bare=False):
     """Same as with_bare_repo, but clones the rorepo as non-bare repository, checking
-    out the working tree at the given working_tree_ref.
+    out the working tree at the given working_tree_ref with an attached HEAD,
+    regardless of the source repository's HEAD state.
 
     This repository type is more costly due to the working copy checkout.
 
@@ -158,7 +159,12 @@ def repo_creator(self):
             repo_dir = tempfile.mktemp(prefix="%sbare_%s" % (prefix, func.__name__))
             rw_repo = self.rorepo.clone(repo_dir, shared=True, bare=bare, n=True)
 
-            rw_repo.head.commit = rw_repo.commit(working_tree_ref)
+            if rw_repo.head.is_detached:
+                rw_repo.head.reference = rw_repo.create_head(
+                    "master", working_tree_ref, force=True, logmsg="Create test branch"
+                )
+            else:
+                rw_repo.head.commit = rw_repo.commit(working_tree_ref)
             if not bare:
                 rw_repo.head.reference.checkout()
             # END handle checkout
@@ -294,6 +300,7 @@ def remote_repo_creator(self):
             rw_repo_dir = tempfile.mktemp(prefix="daemon_cloned_repo-%s-" % func.__name__)
 
             rw_daemon_repo = self.rorepo.clone(rw_daemon_repo_dir, shared=True, bare=True)
+            rw_daemon_repo.head.reference = rw_daemon_repo.create_head("master", force=True)
             # Recursive alternates info?
             rw_repo = rw_daemon_repo.clone(rw_repo_dir, shared=True, bare=False, n=True)
             try:

test/test_base.py

@@ -8,7 +8,7 @@
 import os.path as osp
 import sys
 import tempfile
-from unittest import skipIf
+from unittest import mock, skipIf
 
 from git import Repo
 from git.objects import Blob, Commit, TagObject, Tree
@@ -92,7 +92,7 @@ def test_get_object_type_by_name(self):
 
     def test_object_resolution(self):
         # Objects must be resolved to shas so they compare equal.
-        self.assertEqual(self.rorepo.head.reference.object, self.rorepo.active_branch.object)
+        self.assertEqual(self.rorepo.head.object, self.rorepo.commit("HEAD"))
 
     @with_rw_repo("HEAD", bare=True)
     def test_with_bare_rw_repo(self, bare_rw_repo: Repo):
@@ -108,6 +108,22 @@ def test_with_rw_repo(self, rw_repo: Repo):
         assert osp.isdir(osp.join(rw_repo.working_tree_dir, "lib"))
         assert osp.isdir(rw_repo.working_dir)
 
+    @with_rw_repo("HEAD")
+    def test_with_rw_repo_from_detached_source(self, source_repo):
+        source_repo.active_branch.rename("test-source")
+        commit = source_repo.head.commit.parents[0]
+        source_repo.head.reference = commit
+
+        def check_repo(_self, repo):
+            assert not repo.head.is_detached
+            self.assertEqual(repo.head.commit, commit)
+            assert repo.head.reference.log()
+
+        with mock.patch.object(self, "rorepo", source_repo):
+            for bare in (False, True):
+                with_rw_repo("HEAD", bare=bare)(check_repo)(self)
+        assert source_repo.head.is_detached
+
     @skipIf(HIDE_WINDOWS_FREEZE_ERRORS, "FIXME: Freezes!  sometimes...")
     @with_rw_and_rw_remote_repo("0.1.6")
     def test_with_rw_remote_and_rw_repo(self, rw_repo, rw_remote_repo):

test/test_docs.py

@@ -22,15 +22,16 @@ def tearDown(self):
     # @skipIf(HIDE_WINDOWS_KNOWN_ERRORS,
     #         "FIXME: helper.wrapper fails with: PermissionError: [WinError 5] Access is denied: "
     #         "'C:\\Users\\appveyor\\AppData\\Local\\Temp\\1\\test_work_tree_unsupportedryfa60di\\master_repo\\.git\\objects\\pack\\pack-bc9e0787aef9f69e1591ef38ea0a6f566ec66fe3.idx")  # noqa: E501
+    @with_rw_repo("HEAD")
     @with_rw_directory
-    def test_init_repo_object(self, rw_dir):
+    def test_init_repo_object(self, rw_dir, rw_repo):
         # [1-test_init_repo_object]
         from git import Repo
 
-        # rorepo is a Repo instance pointing to the git-python repository.
+        # rw_repo is a Repo instance pointing to a clone of the git-python repository.
         # For all you know, the first argument to Repo is a path to the repository you
         # want to work with.
-        repo = Repo(self.rorepo.working_tree_dir)
+        repo = Repo(rw_repo.working_tree_dir)
         assert not repo.bare
         # ![1-test_init_repo_object]
 
@@ -457,6 +458,7 @@ def test_references_and_objects(self, rw_dir):
         # To detach your head, you have to point to a commit directly.
         repo.head.reference = repo.commit("HEAD~5")
         assert repo.head.is_detached
+        assert repo.head.commit.hexsha == repo.commit("HEAD").hexsha
         # Now our head points 15 commits into the past, whereas the working tree
         # and index are 10 commits in the past.
         # ![29-test_references_and_objects]

test/test_refs.py

@@ -249,8 +249,6 @@ def test_set_tracking_branch_with_import(self, rwrepo):
             writer.set_value("include", "path", included_config)
 
         for head in rwrepo.heads:
-            head.set_tracking_branch(None)
-            assert head.tracking_branch() is None
             remote_ref = rwrepo.remotes[0].refs[0]
             assert head.set_tracking_branch(remote_ref) is head
             assert head.tracking_branch() == remote_ref
@@ -263,18 +261,20 @@ def test_refs(self):
             types_found.add(type(ref))
         assert len(types_found) >= 3
 
-    def test_is_valid(self):
-        assert not Reference(self.rorepo, "refs/doesnt/exist").is_valid()
-        assert self.rorepo.head.is_valid()
-        assert self.rorepo.head.reference.is_valid()
-        assert not SymbolicReference(self.rorepo, "hellothere").is_valid()
+    @with_rw_repo("HEAD")
+    def test_is_valid(self, rw_repo):
+        assert not Reference(rw_repo, "refs/doesnt/exist").is_valid()
+        assert rw_repo.head.is_valid()
+        assert rw_repo.head.reference.is_valid()
+        assert not SymbolicReference(rw_repo, "hellothere").is_valid()
 
     def test_orig_head(self):
         assert type(self.rorepo.head.orig_head()) is SymbolicReference
 
     @with_rw_repo("0.1.6")
     def test_head_checkout_detached_head(self, rw_repo):
-        res = rw_repo.remotes.origin.refs.HEAD.reference.checkout()
+        remote_branch = next(ref for ref in rw_repo.remotes.origin.refs if ref.remote_head != "HEAD")
+        res = remote_branch.checkout()
         assert isinstance(res, SymbolicReference)
         assert res.name == "HEAD"
 
@@ -495,6 +495,7 @@ def test_head_reset(self, rw_repo):
         # We allow heads to point to any object.
         head.object = head_tree
         assert head.object == head_tree
+        self.assertRaisesRegex(TypeError, r"\.object", getattr, head, "reference")
         # Cannot query tree as commit.
         self.assertRaises(TypeError, getattr, head, "commit")
 
@@ -721,8 +722,9 @@ def test_dereference_recursive(self):
         # For now, just test the HEAD.
         assert SymbolicReference.dereference_recursive(self.rorepo, "HEAD")
 
-    def test_reflog(self):
-        assert isinstance(self.rorepo.active_branch.log(), RefLog)
+    @with_rw_repo("HEAD")
+    def test_reflog(self, rw_repo):
+        assert isinstance(rw_repo.active_branch.log(), RefLog)
 
     def test_refs_outside_repo(self):
         # Create a file containing a valid reference outside the repository. Attempting

test/test_remote.py

@@ -1022,7 +1022,7 @@ def test_push_unsafe_options_allowed(self, rw_repo):
                 # The options will be allowed, but the command will fail.
                 assert not tmp_file.exists()
                 with self.assertRaises(GitCommandError):
-                    remote.push(**unsafe_option, allow_unsafe_options=True)
+                    remote.push("HEAD:refs/heads/test-push", **unsafe_option, allow_unsafe_options=True)
                 assert tmp_file.exists()
                 tmp_file.unlink()
 
@@ -1096,8 +1096,8 @@ def test_timeout_funcs(self, repo):
         for function in ["pull", "fetch"]:  # Can't get push to time out.
             f = getattr(repo.remotes.origin, function)
             assert f is not None  # Make sure these functions exist.
-            _ = f()  # Make sure the function runs.
+            _ = f("HEAD")  # Make sure the function runs without requiring an upstream branch.
             with pytest.raises(GitCommandError, match="kill_after_timeout=0 s"):
-                f(kill_after_timeout=0)
+                f("HEAD", kill_after_timeout=0)
 
         Git.AutoInterrupt._status_code_if_terminate = default

test/test_repo.py

@@ -322,15 +322,16 @@ def test_heads_should_return_array_of_head_objects(self):
         for head in self.rorepo.heads:
             self.assertEqual(Head, head.__class__)
 
-    def test_heads_should_populate_head_data(self):
-        for head in self.rorepo.heads:
+    @with_rw_repo("HEAD")
+    def test_heads_should_populate_head_data(self, rw_repo):
+        for head in rw_repo.heads:
             assert head.name
             self.assertIsInstance(head.commit, Commit)
         # END for each head
 
-        active_branch = self.rorepo.active_branch
-        self.assertIsInstance(self.rorepo.heads[active_branch.name], Head)
-        self.assertEqual(self.rorepo.heads[active_branch.name], active_branch)
+        active_branch = rw_repo.active_branch
+        self.assertIsInstance(rw_repo.heads[active_branch.name], Head)
+        self.assertEqual(rw_repo.heads[active_branch.name], active_branch)
 
     def test_tree_from_revision(self):
         tree = self.rorepo.tree("0.1.6")
@@ -634,8 +635,9 @@ def test_is_dirty_with_pathlib_and_pathlike(self, rwrepo):
         assert rwrepo.is_dirty(path=Path("doc")) is False
         assert rwrepo.is_dirty(path=PathLikeMock("doc")) is False
 
-    def test_head(self):
-        self.assertEqual(self.rorepo.head.reference.object, self.rorepo.active_branch.object)
+    @with_rw_repo("HEAD")
+    def test_head(self, rw_repo):
+        self.assertEqual(rw_repo.head.reference.object, rw_repo.active_branch.object)
 
     def test_index(self):
         index = self.rorepo.index
@@ -1185,7 +1187,8 @@ def test_rev_parse(self):
         except IndexError:
             pass
         else:
-            self.assertNotEqual(previous, head.commit)
+            # A checkout can record the same commit in consecutive reflog entries.
+            self.assertEqual(previous.hexsha, self.rorepo.git.rev_parse("@{1}"))
 
     def test_repo_odbtype(self):
         target_type = GitCmdObjectDB
@@ -1351,9 +1354,17 @@ def test_active_branch_raises_type_error_when_head_is_detached(self, rw_dir):
         with open(osp.join(rw_dir, "a.txt"), "w") as f:
             f.write("a")
         repo.index.add(["a.txt"])
-        repo.index.commit("initial commit")
-        repo.git.checkout(repo.head.commit.hexsha)
-        self.assertRaisesRegex(TypeError, "detached symbolic reference", lambda: repo.active_branch)
+        commit = repo.index.commit("initial commit")
+        self.assertEqual(repo.head.reference.commit, commit)
+        self.assertEqual(repo.head.commit.hexsha, commit.hexsha)
+
+        repo.git.checkout(commit.hexsha)
+        assert repo.head.is_detached
+        self.assertEqual(repo.head.commit.hexsha, repo.git.rev_parse("HEAD"))
+        self.assertEqual(repo.commit().hexsha, commit.hexsha)
+        self.assertEqual(repo.commit("HEAD").hexsha, commit.hexsha)
+        self.assertRaisesRegex(TypeError, r"detached symbolic reference.*\.commit", lambda: repo.head.reference)
+        self.assertRaisesRegex(TypeError, r"detached symbolic reference.*\.commit", lambda: repo.active_branch)
 
     def test_merge_base(self):
         repo = self.rorepo