Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Objects, Refs and Internals

HEAD and detached HEAD

Reference for Git's HEAD: the symbolic ref that names your current branch, what a detached HEAD is on disk, how to read and change it, and how to recover commits.

HEAD is the ref that says where you are. Normally it is a symbolic ref: the file .git/HEAD contains ref: refs/heads/main, so HEAD means "whatever the branch main points to", and a new commit moves main. When HEAD instead contains a raw commit ID it is detached: it points at a commit directly, no branch follows along, and the next commit moves only HEAD itself.

Everything that depends on "the current commit" starts from HEAD: git commit uses it as the parent, git status compares against it, git diff HEAD and git log default to it, and @ is a shorthand for it.

Terminal
git symbolic-ref HEAD            # refs/heads/main, or an error if detached
git rev-parse HEAD               # the commit ID, in both cases
git switch --detach <commit>     # detach on purpose

Try it

Bash Attached versus detached HEAD on disk

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Commits on a detached HEAD, and how to keep them

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

What is stored

State Content of .git/HEAD Meaning
On a branch ref: refs/heads/<name> Commits advance that branch.
Detached A full object ID Commits advance HEAD only.
Unborn branch ref: refs/heads/<name> where the ref file does not exist yet A new repository before its first commit. rev-parse HEAD fails.

With the reftable backend there is still a small .git/HEAD stub file, and the real value is kept in the tables (see Refs and ref storage).

Terminal
git symbolic-ref [-q] [--short] HEAD
git symbolic-ref HEAD refs/heads/other      # re-point HEAD without touching files
git update-ref --no-deref HEAD <commit>     # detach HEAD at <commit>
git rev-parse --abbrev-ref HEAD             # "HEAD" when detached
Command Result when detached
git symbolic-ref HEAD Fails with exit code 128 and "ref HEAD is not a symbolic ref".
git symbolic-ref -q HEAD Quiet; exit code 1 instead of a message.
git branch --show-current Prints nothing.
git rev-parse --abbrev-ref HEAD Prints HEAD.

Usage notes

  • When Git detaches for you. Checking out a tag, a remote-tracking branch or a commit ID; during rebase, bisect and cherry-pick sequences; and in submodules after git submodule update.
  • Detached commits are not lost at once. They are kept by the reflog (default 90 days for reachable, 30 days for unreachable entries) until gc prunes them. Create a branch with git switch -c <name> before moving away to keep them safely.
  • Unborn branches. git switch --orphan <name> and git checkout --orphan <name> point HEAD at a branch that does not exist yet; the first commit creates it with no parent.
  • HEAD in other forms. HEAD~2, HEAD^2, HEAD@{1} and HEAD:path are revision syntax built on HEAD. FETCH_HEAD, ORIG_HEAD and MERGE_HEAD are different refs (see Special refs).
  • Remote HEAD. refs/remotes/origin/HEAD is a symbolic ref naming the remote's default branch. git remote set-head origin -a refreshes it. A bare server's own HEAD decides which branch a new clone checks out.
  • Case sensitivity. The name HEAD must be uppercase. On a case-insensitive file system, head may appear to work but is not guaranteed.
  • Per worktree. Each linked worktree has its own HEAD.