What to Do in a Detached HEAD

“You are in ‘detached HEAD’ state” reads like a warning that something broke. Nothing broke. Git is saying your HEAD - the pointer that normally sits on a branch - is pointing directly at a commit. Everything works; the only real question is what happens to commits you make here.

How you got here#

The usual doors in:

git checkout 3357a04      # inspect an old commit
git checkout v1.4.0       # look at exactly what a tag shipped

Bisect and rebase also park you here on purpose. Checking out a tag to reproduce a bug against the exact deployed code is a completely ordinary reason to be detached.

Looking is free, committing is fine, leaving is the catch#

Read files, run the test suite, boot the app - the working tree is real. You can even commit. The catch: no branch points at those new commits, so when you switch away they become unreferenced, and the only thing that will ever find them again is the reflog.

So the rule is simple. The moment you make a commit you want to keep, give it a branch:

git switch -c fix/reproduce-invoice-bug

That is the whole fix. HEAD now points at a normal branch holding your work, and the detached state is over.

If you already switched away#

The commits are not gone; they are unreferenced. Find the hash you were on:

git reflog

The recent checkouts are right at the top. Put a branch on the hash:

git branch rescue 3357a04

The reflog keeps these entries for 90 days by default, so “I detached, committed, and switched away an hour ago” is a two-command recovery, not a lost afternoon.

The habit#

Treat detached HEAD as a reading room, not a workspace. Look all you want; the instant you write something worth keeping, git switch -c before you do anything else - especially before switching branches, which is the moment the work becomes findable only through the reflog.

If you find yourself detaching often just to run someone else’s PR without disturbing your working tree, that is the job worktrees do without the detachment at all.