How to fix a Git detached HEAD?
To fix a detached HEAD in Git, you need to save your work by creating a new branch or by checking out an existing one. A detached HEAD occurs when you check out a specific commit, tag, or a remote branch's commit instead of a local branch name (1). In this state, any new commits you make are not part of any branch, making them easy to lose.
The HEAD pointer in Git usually points to the tip of a branch (e.g., main, feature-a). A detached HEAD means the pointer is pointing directly to a commit instead of a branch.
Identify if You Have a Detached HEAD
You will typically see a warning from Git when you are in a detached HEAD state. The git status command will also tell you.
git status
# HEAD detached at 1a2b3c4
# nothing to commit, working tree clean
Your command prompt might also show a commit hash instead of a branch name.
The Solution: Save Your Work
To fix this, you have two primary options, depending on your goal.
Option A: Create a New Branch to Keep Your Work
This is the most common and recommended way to save your new commits. By creating a new branch from your current detached HEAD position, you give your commits a permanent home.
- Make your new commits.
- Create a new branch from your current detached
HEADposition.
# This creates a new branch and switches to it
git switch -c new-branch-name
or
# This is an older, but still common, command
git checkout -b new-branch-name
Now, new-branch-name points to your latest commit, and HEAD points to new-branch-name. You are no longer in a detached HEAD state.
If you want to integrate the changes from this new branch into an existing one (e.g., master), you can then check out the target branch and merge your new branch into it.
# Save your work in a temporary branch
git switch -c tmp
# Switch to the branch you want to integrate changes into
git switch master
# Merge the changes from your temporary branch
git merge tmp
Option B: Discarding New Commits and Returning to a Branch
If you have no new commits and just want to get back to a regular branch, simply check out the branch you want to be on.
Discard any new, uncommitted changes you may have
git reset --hard
Switch to your desired branch
git switch main
# or
git checkout main
What Happens If You Forget?
If you make commits in a detached HEAD state and then check out another branch without creating a new one, your new commits will become dangling commits. They will exist in the Git object database but will not be reachable from any branch or tag. Git's garbage collection will eventually remove them (2), so it is crucial to save them.
To recover a dangling commit, you can use the git reflog command, which shows a history of your HEAD movements.
- Find the commit hash of your lost commits using
git reflog.
git reflog
# 1a2b3c4 (HEAD) HEAD@{0}: commit: My lost commit message
# ...
Create a new branch from that commit hash
git switch -c recovered-branch 1a2b3c4
This will restore your lost work.
Common Causes of a Detached HEAD
- Checking out a specific commit:
git checkout 1a2b3c4 - Checking out a tag:
git checkout v1.0.0 - Using
git checkoutto view a remote branch without creating a local one:git checkout origin/main
By understanding the nature of a detached HEAD and using the proper steps to create or check out a branch, you can prevent losing your work and maintain a healthy Git workflow.