Detached HEAD, Explained

The symptom

You checked something out — maybe an old commit from git log, maybe a tag — and Git printed a wall of text starting with this:

What Git prints

Terminal 
$ 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.
In VS Code
  1. No error appears — instead, the bottom-left status bar shows a short commit hash (like a1b2c3d) where the branch name usually is

This is Git's message, not commands to run.

Despite the surgical-sounding name, nothing is broken and nothing is lost. Git is just telling you where you're standing.

What it means

HEAD is Git's "you are here" pin — it marks which snapshot your files currently reflect. Normally the pin is attached to a branch, so every new commit moves the branch (and the pin) forward together. When you check out a specific commit hash or a tag, you pin HEAD directly to that one commit instead — no branch attached. That's all "detached" means: the pin came off the branch.

main newest
HEAD usually rides a branch's newest commit — detached HEAD parks it on an older one.

It's a perfectly normal state for looking around: inspecting how the code looked three versions ago, testing whether a bug existed at release v1.2, and so on. The only catch is that commits you make here don't belong to any branch — so when you leave, Git has no name to find them by. Both exits below handle that.

Mental model: think of HEAD as the "you are here" pin on a map. Usually it's clipped to a moving vehicle (a branch) and travels with it. Detached HEAD just means you unclipped the pin and stuck it on one fixed spot. Clip it back on, or start a new vehicle from where you're standing.

Just looking? Go back

If you only wanted a peek at the past and made no commits, simply switch back to your branch. HEAD re-attaches, your files return to normal, and the message never mattered.

Re-attach HEAD to your branch

Terminal 
$ git switch main
In VS Code
  1. Click the commit hash in the bottom-left status bar
  2. Pick main from the list — the status bar shows the branch name again

Older tutorials say 'git checkout main' — same effect, switch is the modern command.

Made commits you want to keep?

If you committed while detached, don't switch away yet — give those commits a home first. Creating a branch right where you are attaches a name to them, and from then on it's an ordinary branch like any other.

Turn your detached commits into a branch

Terminal 
$ git switch -c my-experiment
In VS Code
  1. Click the commit hash in the status bar
  2. Choose Create new branch…
  3. Type a name and press Enter — your commits are safe on it

Do this before switching back to main. Once the commits have a branch name, nothing can quietly forget them.

Switched away and lost them?

Already jumped back to main and now your detached commits seem gone? They aren't — Git keeps them around for weeks, just without a name pointing at them. The Recover Lost Work chapter shows how to find their hash with git reflog and pin a branch back onto them.

Up next: the safety net behind that rescue — Recover Lost Work walks through git reflog, the log of everywhere HEAD has been.

FAQ

Frequently Asked Questions

Is detached HEAD an error?
No — it's an informational message, not an error. It means HEAD (Git's "you are here" pin) points at a specific commit instead of a branch, which is a normal state for inspecting old versions. Nothing is broken and no work is lost.
How do I get out of detached HEAD?
Run git switch main (or any branch name) and HEAD re-attaches. In VS Code, click the commit hash in the bottom-left status bar and pick a branch from the list.
I made commits in detached HEAD — are they lost?
Not if you act before switching away: run git switch -c my-experiment to put them on a new branch. If you already switched, they're still recoverable for weeks — find their hash with git reflog, as shown in Recover Lost Work.
Why did checking out a tag detach HEAD?
A tag is a fixed label on one commit — it never moves, so there's no branch for HEAD to ride. Checking out v1.2 therefore pins HEAD directly to that commit. To make changes from a tag, start a branch there with git switch -c fix-from-v1.2 v1.2.