Git detached HEAD (tested)

"You are in 'detached HEAD' state" means HEAD points directly at a commit instead of at a branch. You can look around and even commit, but nothing is tracking those commits — if you switch to a branch without saving them first, they become unreachable by name. We reproduced the whole lifecycle: entering it, committing inside it, losing the commit, and recovering it.

1. How you get here

Checking out anything that isn't a branch name puts you in detached HEAD: a specific commit hash, a tag, origin/main directly, or an old commit via git checkout HEAD~3. We checked out a commit by hash:

$ git checkout b96b477
Note: switching to 'b96b477dac1a0642414b375769c17fff2c70e5b7'.

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.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -c with the switch command. Example:

  git switch -c <new-branch-name>

Or undo this operation with:

  git switch -

HEAD is now at b96b477 c1

git status and git branch both show it plainly, so you can always tell you're in this state:

$ git status
HEAD detached at b96b477
nothing to commit, working tree clean

$ git branch
* (HEAD detached at b96b477)
  master

2. The real risk: committing while detached

We made a real commit while detached, then switched back to master. Git told us exactly what we were about to leave behind:

$ git switch master
Warning: you are leaving 1 commit behind, not connected to
any of your branches:

  a8d41a3 detached work

If you want to keep it by creating a new branch, this may be a good time
to do so with:

 git branch <new-branch-name> a8d41a3

Switched to branch 'master'

At this point git branch --contains a8d41a3 returns nothing — no branch contains that commit. It looks gone. It isn't.

3. Recovering a "lost" detached commit

git reflog records every place HEAD has pointed, including commits made while detached, for 90 days by default:

$ git reflog
8836116 HEAD@{0}: checkout: moving from a8d41a3... to master
a8d41a3 HEAD@{1}: commit: detached work
b96b477 HEAD@{2}: checkout: moving from master to b96b477...
8836116 HEAD@{3}: commit: c3

Create a branch pointing at it and the commit is fully back:

$ git switch -c recovered a8d41a3
Switched to a new branch 'recovered'
$ git log --oneline -1
a8d41a3 detached work

This works even if you didn't save the hash: just read it off the reflog warning when you switched away, or scroll git reflog for the commit: line right before you left.

4. How to avoid the risk entirely

• Before committing in a detached state, run git switch -c some-branch-name first. Now every commit you make is on a real branch from the start — no warning, no reflog archaeology needed.
• If you just want to look around (read old code, run an old build), don't commit. Detached HEAD is completely safe for read-only exploration; the risk is only in committing and then forgetting.
• To get back to normal, git switch - returns you to whatever you were on before, or git switch master (or your default branch) by name.

5. A related error: "fatal: not a git repository"

A different but commonly confused error: running a git command outside any repository. We reproduced it with git 2.47.3:

$ git status
fatal: not a git repository (or any parent up to mount point /)
Stopping at filesystem boundary (GIT_DISCOVERY_ACROSS_FILESYSTEM not set).

This wording (mentioning the filesystem boundary and GIT_DISCOVERY_ACROSS_FILESYSTEM) is what current git versions print; older tutorials often quote a shorter fatal: not a git repository (or any of the parent directories): .git, which is the same error from an earlier git release. Either way, the cause is the same: git walks up from your current directory looking for a .git folder and found none before hitting a filesystem boundary (or the root). It works fine from any subdirectory of a real repo — git keeps walking up until it finds .git. Fixes: cd into the actual repo, run git init if there should be one, or pass git -C /path/to/repo status to point git at it explicitly without changing directory.

Written with AI assistance. Measured on 2026-10-02 with git 2.47.3 on Linux, in a throwaway /tmp repo. Git is free and open source.