Git: you are in 'detached HEAD' state

Hi, it's BlueByte. "Detached HEAD" reads like a crash, but nothing is broken — Git is just telling you HEAD is pointing straight at a commit instead of a branch. Let's understand how you got here, and the one move that keeps any commits you made from getting lost.

What "detached HEAD" means

Git warns after a checkout:

Note: switching to 'a1b2c3d'.
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.

Nothing is broken. HEAD is just pointing straight at a commit rather than at a branch that moves with your commits. It is a normal, useful state for inspecting history — the only real risk is committing here and then leaving without saving the work to a branch.

How you ended up detached

You checked out something that is not a local branch. In practice that means one of:

• A commit hash — inspecting an old state.
• A tag — checking out a release like v1.4.0.
• A remote-tracking branch like origin/main instead of a local main.
• A submodule, which Git keeps at a specific commit by design.
• A git bisect run, which checks out commits directly while it searches.

In that state new commits are recorded, but no branch label follows them, so switching away leaves them unreferenced.

Ask Git where HEAD points

You do not have to wonder — ask Git:

git status
git symbolic-ref -q HEAD || echo "HEAD is detached"

git status says "HEAD detached at a1b2c3d" and names what you checked out. If it names a tag or a remote branch, that is how you got here — checking out a local branch name never detaches HEAD. git log --oneline -1 shows the exact commit you are sitting on.

Keep your work: put a branch on it

1. If you made commits here and want to keep them, create a branch at your current position — the important step:

git switch -c my-work

Your commits are now on my-work and safe.

2. If you only looked around, switch back to a real branch:

git switch main

3. If you already switched away and think you lost commits, they are still in the reflog:

git reflog
git switch -c recovered a1b2c3d

A real case: two commits on a tag

You check out a tag to reproduce a bug — git checkout v1.4.0 — and Git warns about detached HEAD. You make two commits trying a fix, then run git switch main out of habit. Git says you are leaving commits behind. You realize the work is unreferenced, so you run git reflog, find the top commit hash from a minute ago, and run git switch -c bugfix-1.4 <hash>. Your two commits are now on bugfix-1.4, safe and ready to push. Nothing was lost — the reflog remembered where HEAD had been.

Confirm you're back on a branch

Check HEAD now points at a branch and your work is on it:

git status          # "On branch my-work"
git log --oneline -3

Seeing "On branch ..." instead of "HEAD detached" means you are back on a branch that will hold future commits.

Keep it from surprising you

When you check out a commit or tag to experiment, create a branch first if you intend to commit. Detaching on purpose to inspect a release is fine — just run git switch -c before you leave if you made changes.

How this differs from a merge error

Detached HEAD is a state, not an error — Git still works normally. It is unrelated to a merge conflict or refusing to merge unrelated histories; those are about combining branches, while this is simply about which ref HEAD is attached to. If you committed here, branch before you leave and nothing is lost.