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.
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
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.
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).
Syntax of related commands
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,bisectandcherry-picksequences; and in submodules aftergit 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
gcprunes them. Create a branch withgit switch -c <name>before moving away to keep them safely. - Unborn branches.
git switch --orphan <name>andgit checkout --orphan <name>point HEAD at a branch that does not exist yet; the first commit creates it with no parent. HEADin other forms.HEAD~2,HEAD^2,HEAD@{1}andHEAD:pathare revision syntax built on HEAD.FETCH_HEAD,ORIG_HEADandMERGE_HEADare different refs (see Special refs).- Remote HEAD.
refs/remotes/origin/HEADis a symbolic ref naming the remote's default branch.git remote set-head origin -arefreshes it. A bare server's ownHEADdecides which branch a new clone checks out. - Case sensitivity. The name
HEADmust be uppercase. On a case-insensitive file system,headmay appear to work but is not guaranteed. - Per worktree. Each linked worktree has its own
HEAD.