detached HEAD: standing on a commit, not on a branch

A detached HEAD means HEAD points straight at a commit instead of at a branch name, so new commits have nothing to attach to.

Normally there are two levels of pointers: HEAD points at a branch, the branch points at a commit. In a detached HEAD the middle level drops out and HEAD holds the hash itself. The files in your working directory are perfectly fine; they simply match the commit you landed on.

You get here by naming a commit where git expects a branch:

$ git checkout a0ca112          # by commit hash
$ git switch --detach a0ca112   # the same thing, said explicitly
$ git checkout v1.0             # by tag

Git tells you plainly what just happened:

$ git checkout 06877dc
Note: switching to '06877dc'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by switching back to a branch.

$ git status
HEAD detached at 06877dc
nothing to commit, working tree clean

The line HEAD detached at 06877dc in place of the usual On branch main is the giveaway. git branch shows the same thing:

$ git branch
* (HEAD detached at 06877dc)
  main

What can go wrong

Reading history in this state is safe: you look at how the project stood a month ago, then leave. The one risk is commits. A commit made here belongs to no branch, and the moment you switch back, git log will not show it to you anywhere.

Git warns about that too, though the message is easy to scroll past:

$ git switch main
Warning: you are leaving 1 commit behind, not connected to
any of your branches:

  7f3fd53 experiment

Switched to branch 'main'

How to get out

If you only looked around, go back where you came from:

$ git switch -                  # back to the previous branch
$ git switch main               # or straight to the branch you want, by name

If you managed to commit something worth keeping, put a branch name on those commits first, and only then leave:

$ git switch -c experiment      # keep the work on a new branch
Switched to a new branch 'experiment'

Common mistakes

Walking away with commits and deciding they are gone. They are not: the hash is in git reflog, and from a hash you get a branch with git switch -c rescue <hash>. Reflog entries for commits no branch can reach live for 30 days by default, so there is time to rescue them.

Doing long stretches of work in a detached HEAD. Nothing breaks, but you have to remember every step yourself. It is easier to create a branch with git switch -c right away and use the bare commit only for looking.

Where this is in the book

Chapter 8. First aid: when something goes wrong covers detached HEAD along with other alarming messages and shows how to pull a commit back by hash.

To practise it by hand, open the Sandbox: a real terminal with git and step checks.