checking out a detached HEAD breaks Repo.head.reference

While building this package for openSUSE and running the testsuite we encountered a lot of test failures like this

self = <git.HEAD "HEAD">

    def _get_reference(self) -> "Reference":
        """
        :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))
E           TypeError: HEAD is a detached symbolic reference as it points to '3481da9618e69063464c94447167d83bd45505a9'

git/refs/symbolic.py:446: TypeError

It seems that this only occurs when checking out a revision instead of a branch, aka when the ref in .git/HEAD points to a commit instead of something like ref: refs/heads/master.

Repo.head.reference in git/repo/base.py fails to resolve references to commit hashes which I would expect to work.

Also there is an unrelated problem where TestRemote.test_base hardcodes the branch name as "master" which leads to the test failing when checking out any other branch.

To reproduce, run git checkout $(git describe HEAD). Then pytest fails with failures like

AILED test/test_base.py::TestBase::test_object_resolution - TypeError: HEAD is a detached symbolic reference as it points to 'b62e91be897f687a622e40cd1e59c33dce45f124'
FAILED test/test_docs.py::Tutorials::test_init_repo_object - TypeError: HEAD is a detached symbolic reference as it points to 'b62e91be897f687a622e40cd1e59c33dce45f124'
FAILED test/test_refs.py::TestRefs::test_is_valid - TypeError: HEAD is a detached symbolic reference as it points to 'b62e91be897f687a622e40cd1e59c33dce45f124'
FAILED test/test_refs.py::TestRefs::test_reflog - TypeError: HEAD is a detached symbolic reference as it points to 'b62e91be897f687a622e40cd1e59c33dce45f124'
FAILED test/test_repo.py::TestRepo::test_head - TypeError: HEAD is a detached symbolic reference as it points to 'b62e91be897f687a622e40cd1e59c33dce45f124'
FAILED test/test_repo.py::TestRepo::test_heads_should_populate_head_data - TypeError: HEAD is a detached symbolic reference as it points to 'b62e91be897f687a622e40cd1e59c33dce45f124'
FAILED test/test_repo.py::TestRepo::test_rev_parse - AssertionError: <git.Commit "b62e91be897f687a622e40cd1e59c33dce45f124"> == <git.Commit "b62e91be897f687a622e40cd1e59c33dce45f124">

feat!: return None for detached refs and add HEAD.hexsha (#2230)

Clarify detached HEAD access and attach writable test fixtures (#2230)

@Vogtinator

@Vogtinator It's well-known that the tests aren't isolated and require a certain initial state of the parent repository. It's a wont-fix for v3.

@tiltingpenguin It's a very inconvenient API and exceptions generally aren't great, but it's nothing that can be fixed in v3. Hence, repo.head.commit should instead be used to learn about the commit.
Sorry for that, but improvements are in the works which unfortunately will be breaking and release as v4.

The related PR makes the diagnostic message better.
Thanks for your understanding.

Navigation Menu

Repository navigation

checking out a detached HEAD breaks Repo.head.reference #2230

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

checking out a detached HEAD breaks Repo.head.reference #2230

Description

Activity

Vogtinator commented on Sep 9, 2026

Byron commented on Sep 10, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions