Git: You are in 'detached HEAD' state — commits won't be on any branch
detached HEAD — commits not on any branch
Verified against Git docs: git-checkout — DETACHED HEAD, Pro Git book: Chapter 2.3 — Viewing the Commit History, Git source: checkout.c detach_head() · Updated June 2026
> quick_fix
You checked out a specific commit, tag, or remote branch instead of a local branch. Any commits you make here aren't on a branch and will eventually be garbage-collected. Fix: run git checkout -b my-branch to create a branch at your current position.
# You're in detached HEAD. Save your work:
git checkout -b my-new-branch
# Or, if you want to go back to an existing branch:
git checkout main
# If you already made commits in detached HEAD:
git checkout -b save-my-work
# All commits are now safely on 'save-my-work'What causes this error
In Git, HEAD is a pointer that normally points to a branch (e.g., refs/heads/main), and the branch in turn points to a commit. When you checkout a specific commit hash, a tag, or a remote tracking branch (origin/main), HEAD points directly to a commit instead of a branch. This is 'detached HEAD' state. Git warns you because any new commits you make will have no branch reference pointing to them — once you switch away, those commits become unreachable and will be garbage-collected within ~30 days.
How to fix it
- 01
step 1
Understand what happened
You're in detached HEAD because you ran something like git checkout abc123, git checkout v1.0, or git checkout origin/main. HEAD now points to a commit, not a branch.
# See where HEAD points: git log --oneline -1 # See all branches: git branch -a - 02
step 2
If you haven't made any commits: just switch to a branch
If you were just looking at old code and didn't commit anything, simply switch back: git checkout main (or whatever branch you want).
git checkout main - 03
step 3
If you made commits: create a branch first
If you made commits in detached HEAD, create a branch to save them before switching away. This is the critical step — without it, your commits become orphaned.
# Create a branch at current position: git checkout -b my-work # Now your commits are safely on 'my-work' git log --oneline -5 - 04
step 4
If you already switched away and lost commits
Git reflog keeps a record of where HEAD was. Find the lost commit hash and create a branch from it.
# Find the lost commit: git reflog # Look for your commit message, note the hash # Recover it: git checkout -b recovered abc1234
How to verify the fix
- git status shows 'On branch my-branch' (not 'HEAD detached at').
- git log shows your commits are reachable from the branch.
- git branch lists your new branch.
Why detached HEAD happens at the runtime level
Git's HEAD is a symbolic reference stored in .git/HEAD. In normal state, it contains 'ref: refs/heads/main' (a pointer to a branch). In detached state, it contains a raw commit SHA — e.g., 'abc123def456'. Git's checkout.c implements this: when the target is a branch, it updates HEAD to a symbolic ref; when the target is a commit hash, tag, or remote branch, it writes the resolved commit SHA directly. The 'detached HEAD' warning is printed by advice.c when HEAD transitions from symbolic to direct. Commits made in detached state are reachable only through HEAD and the reflog — once HEAD moves (you checkout something else), those commits have no branch ref and enter the 'unreachable' set that git gc eventually prunes.
Common debug mistakes for detached HEAD
- Panicking and running git checkout main immediately — if you made commits in detached HEAD, this orphans them. Always create a branch first if you have uncommitted work.
- Using git checkout <tag> to 'work from a release' without creating a branch — tags are immutable references, so checking out a tag always detaches HEAD. Create a branch from the tag: git checkout -b hotfix v1.0.
- Thinking detached HEAD means your repo is broken — it's a normal, designed state. The warning is advisory, not an error.
- Running git stash in detached HEAD expecting it to save your position — stash saves working tree changes but doesn't save which commit HEAD was pointing to. You still need to note the commit hash or create a branch.
- Not using git reflog to recover lost commits — reflog is the single most important recovery tool in Git and most developers don't know it exists.
When detached HEAD signals a deeper problem
Developers who frequently end up in detached HEAD usually have a workflow problem: they're using git checkout for too many things. Modern Git separates concerns with git switch (for branches) and git restore (for files). Using git switch main instead of git checkout main eliminates accidental detached-HEAD situations because git switch refuses to switch to a non-branch target without the --detach flag. Teams that standardize on switch/restore over checkout see detached-HEAD confusion drop to near zero.
Editor's take
The scariest detached-HEAD story I know: a developer spent an entire Friday afternoon building a feature in detached HEAD, made 12 commits, went home for the weekend, came back Monday, ran git checkout main to 'start fresh', and lost all 12 commits. They didn't know about git reflog and assumed the work was gone. A coworker recovered everything in 30 seconds with reflog, but the developer had already spent Sunday night rewriting half the feature from memory.
The mental model that makes detached HEAD intuitive is this: HEAD is just a pointer. Normally it points to a branch name (which itself points to a commit). In detached state, HEAD points directly to a commit, skipping the branch indirection. Branches exist to give commits a stable name — without a branch, commits are anonymous and will be cleaned up like any unreferenced object. Once you internalize 'branches are names for commits', detached HEAD stops being mysterious.
Adjacent errors you'll encounter: 'Your branch is behind origin/main by N commits' after recovering from detached HEAD (because your new branch started from an old commit), 'error: pathspec did not match any file(s)' when git checkout can't tell if you mean a branch or a file, and 'fatal: not a valid object name: main' in fresh clones where the default branch has a different name.
By Bikram Nath · Curator · Updated June 2026
Frequently asked questions
Is detached HEAD dangerous?
Not inherently — it's a normal Git state useful for inspecting old commits. The danger is making commits in detached HEAD and then switching away without creating a branch. Those commits become orphaned and will be garbage-collected. As long as you don't commit (or create a branch if you do), detached HEAD is harmless.
Why does git checkout origin/main cause detached HEAD?
origin/main is a remote tracking branch, not a local branch. Git can't commit to a remote tracking branch (it's read-only), so it detaches HEAD at that commit. Use git checkout main (local) or git checkout -b my-branch origin/main (create local branch tracking remote).
How long before orphaned commits are deleted?
By default, git gc prunes unreachable objects older than 2 weeks (gc.reflogExpireUnreachable). The reflog itself keeps entries for 30 days by default. So you have at least 2 weeks to recover commits via git reflog before they're permanently gone.