Clarify detached HEAD access and isolate test branch state

[Byron]

Tasks

This section is for Byron only. Models continuing this PR must not add, remove, check, uncheck, rename, or reorder checkboxes here.

• refackiew

---

Everything below this line was generated by Codex GPT-6.

Created by Codex on behalf of Byron. Byron will review before this is ready to merge.

Detached HEAD makes repo.head.reference raise TypeError, but its public documentation and diagnostic did not explain how to obtain the commit. The diagnostic now points to .commit and .object, and the property documentation and tutorial show repo.head.commit.hexsha for both HEAD states. They also explain why assigning a commit to .reference succeeds while reading it afterward raises. Return types and exception types are preserved; the existing diagnostic gains a hint.

The test suite now supplies branch state in its temporary repositories, gives writable remote fixtures their own master, and uses explicit refspecs where an upstream is unnecessary. Branch-dependent assertions use writable fixtures, and the reflog assertion compares against Git instead of assuming consecutive entries name different commits. A regression covers bare and working clones of a detached commit that no branch points to. The Ubuntu/Python 3.14 CI job additionally runs the suite from detached and non-master source checkouts, with master absent in the latter.

Refs #2230.

Validation:

• Python 3.14.7: full 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, plus 14 passing subtests per state. Six tests needing network or process access were run separately and passed in both states.
• The extended API regression failed on the missing diagnostic hint before the implementation changed.
• Repository-wide Ruff lint and formatting checks passed.
• Sphinx HTML build passed. Its 12 Python 3.14 annotation warnings exactly match the unchanged baseline.

Git reference: git/git at 1630431f326e15fcde608827b5ff38422528eb59, Documentation/git-symbolic-ref.adoc. Apple Git 2.50.1 confirms that git symbolic-ref -q HEAD exits 1 for detached HEAD while git rev-parse HEAD returns the commit ID.

[Copilot]

🔵 Needs a closer look

Normalize annotated-tag revisions to commits before creating the fixture branch.

Pull request overview

This pull request clarifies detached-HEAD access and isolates test fixtures from source branch state.

Changes:

• Documents detached-HEAD commit and reference behavior.
• Improves detached-reference diagnostics.
• Stabilizes temporary repository branch setup.

File summaries

File	Summary
test/lib/helper.py	Adjusts writable fixture branch setup; annotated-tag revisions need normalization to a commit.
git/repo/base.py	Clarifies detached active_branch behavior.
git/refs/symbolic.py	Documents reference semantics and improves diagnostics.
doc/source/tutorial.rst	Adds detached-HEAD usage guidance.

Review details

Suppressed comments (1)

test/lib/helper.py:165

• create_head resolves a string with rev_parse, so an annotated tag resolves to a TagObject and Head rejects it as non-commit. The attached-HEAD branch above avoids this by calling rw_repo.commit(working_tree_ref), so detached-source fixtures regress for any annotated-tag working_tree_ref; normalize the revision to a commit before creating master.

                rw_repo.head.reference = rw_repo.create_head(
                    "master", working_tree_ref, force=True, logmsg="Create test branch"
                )

• Files reviewed: 4/4 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.