HEAD detached
This state occurs when you check out a specific commit, tag, or remote branch directly rather than a local branch pointer.
Usually happens because:
- ☑ Checking out an older commit hash directly
- ☑ Checking out a read-only tag reference
- ☑ Checking out a remote branch directly without tracking local branch
🔍 Quick Checklist:
What is HEAD detached?
A 'detached HEAD' state is not an error but a descriptive warning indicating that your active HEAD pointer is pointing directly to a specific commit hash in the history, rather than to a local branch reference. Any commits you make in this state will not belong to any branch, and will become orphaned (lost) as soon as you switch to another branch, unless you explicitly create a branch to save them.
Common Causes
- Checking out a specific commit hash: Running 'git checkout <commit_hash>' to inspect older states of code.
- Checking out a tag: Running 'git checkout <tag_name>' to access a specific build release version.
- Checking out a remote-only branch: Checking out 'origin/main' directly instead of creating a local tracking counterpart.
| Cause | Frequency |
|---|---|
| Checking out a specific commit hash | ⭐⭐⭐⭐⭐ |
| Checking out a remote tracking branch directly | ⭐⭐⭐⭐ |
| Checking out a release tag name | ⭐⭐⭐ |
Common Mistakes
- Switching to another branch (`git checkout main`) after making commits in a detached HEAD state without creating a branch first, which makes those commits orphaned and difficult to recover.
- Attempting to push changes directly to remote server while in detached HEAD state, which fails because there is no local branch to track.
How to Fix
Git Operations & Verification
If you made commits while detached, save them into a new branch before switching back to main.
# 1. Make experimental changes and commit
$ git commit -am "Experimental edit"
[detached HEAD 5e6f7g8] Experimental edit
# 2. Save work into a new branch
$ git checkout -b feature-experimental
Switched to a new branch 'feature-experimental'Platform Specific Fixes
List branch references to check detached state indicators on Linux.
$ git branch
* (HEAD detached at a1b2c3d)
main
feature-xyzBest Practices
- Always use `git checkout -b <branch_name>` when starting new work instead of checking out random commit states.
- Verify branch state by ensuring your terminal prompt displays the active branch name.
Frequently Asked Questions (FAQ)
Q: What is HEAD in Git?
HEAD is a pointer that reference-links your active local branch and latest commit. It is usually pointing to a branch (which points to a commit). In a detached state, HEAD points directly to a commit.
Q: Will I lose changes made in detached HEAD state?
Yes, if you switch to another branch without saving your work first. To save your changes, create a branch from your current commit by running 'git checkout -b <new-branch-name>'.
Q: How do I switch back to my main branch?
Run 'git checkout main' or 'git switch main' to return to your local main branch.
Q: Why does checking out a tag trigger detached HEAD?
Because tags are read-only markers pointing to a specific commit. Unlike branches, tags do not move forward automatically when you make new commits, so checking one out detaches HEAD.