Introduction

Normally HEAD points at a branch ref, which in turn points at a commit. In detached HEAD, HEAD points directly at a commit. Detached HEAD is not broken; it is a deliberate mode that is useful for inspecting history and dangerous for committing without thinking.

How you get there

git checkout v1.2.3
git switch --detach v1.2.3
git checkout HEAD~5
git checkout origin/main      # remote-tracking is read-only-ish

Each of these puts HEAD directly on a commit instead of a branch.

Inspecting

cat .git/HEAD
# a1b2c3d4...   (raw SHA, not "ref: ...")
git status
# HEAD detached at v1.2.3

Why it exists

• Inspecting an old release without affecting any branch.
• Bisecting (git bisect uses detached HEAD).
• Building a quick experiment you may discard.
• Operating on a tag that should remain immovable.

Committing in detached HEAD

You can commit in detached HEAD, and the commit object is created normally. The catch: no branch points at it. Switch away and the commit becomes unreachable.

git switch --detach v1.2.3
echo fix > patch.txt
git add patch.txt
git commit -m "Quick fix"
git switch main             # the new commit is now orphan

Anchor it before switching:

git switch -c hotfix/1.2.4

Recovering from accidental detach

If you already switched away, the reflog has the commit:

git reflog
# a1b2c3d HEAD@{1}: commit: Quick fix
git switch -c hotfix/1.2.4 a1b2c3d

When detached HEAD is not detached

Bare repositories often have HEAD as a symbolic ref to refs/heads/main even though there is no working tree. Submodules also intentionally check out detached HEAD on the recorded commit; that is normal.

Configuring warnings

git config --global advice.detachedHead true   # default: show advice

Beginners should leave this on; the warning text explains exactly how to recover.

Working safely while detached

If you intentionally want to experiment without affecting any branch, detached HEAD is the right tool. The trick is to anchor important work before switching away. A reliable pattern:

git switch --detach v1.2.3
# ... experiment, commit ...
git tag tmp/experiment           # bookmark
git switch main
# later
git switch -c rescued tmp/experiment
git tag -d tmp/experiment

The tmp/ tag namespace makes it obvious these are throwaway anchors. Some teams reserve a whole prefix for this purpose and have CI ignore it.

Common mistakes

Treating the warning as scary error and panicking. It is informational. Doing significant work in detached HEAD and then running git switch main without creating a branch first; recover via reflog, but better to anchor first. Confusing detached HEAD with a corrupted repo; nothing is corrupt, you just lack a branch label. Finally, pushing while detached: git push needs a branch on both ends. Either create a local branch and push it, or use git push origin HEAD:refs/heads/new.