How to resolve detached HEAD state in Git

Greg Foster
Greg Foster
Graphite software engineer

A Git detached HEAD occurs when you're working directly on a commit rather than on a branch. This guide will walk you through understanding, resolving, and leveraging a detached HEAD state in Git.

  • Detached HEAD state: You enter this state when you check out a specific commit rather than a branch. In this mode, HEAD points directly to a commit, not to a branch reference.

  • Git Detached HEAD meaning: Being in a detached HEAD means you're no longer working on the tip of a branch. Any commits made in this state aren't attached to any branch, making them harder to find later.

  • Check to see if you are in a detached HEAD state: Run git status. If you're in a detached HEAD state, Git will explicitly tell you so.
  1. Go Back to Previous Branch: If you simply want to exit detached HEAD state without keeping any changes made:

    git checkout <branch-name>

    Replace <branch-name> with the name of the branch you wish to return to, such as master or main. For more information, see this guide on how to use git checkout.

  2. Create a new branch from detached HEAD: To keep your current changes, and continue working on them run:

    git checkout -b new-branch-name

    This command creates a new branch from your current detached HEAD position and switches to it. On this branch you can continue to push, pull, and commit as normal.

  • After accidental detachment: If you've made commits in the detached HEAD state and want to attach them to a branch: Replace <target_branch> with your target branch . This sequence of commands creates a temporary branch pointing to your detached HEAD, then merges these changes back into your target branch so you can continue development as usual.
Terminal
git branch temp-branch
git checkout <target_branch>
git merge temp-branch

If you find yourself in a detached HEAD state after a rebase, it's likely because the rebase was started from a detached HEAD state or a specific commit. To fix:

  1. Create a new branch as previously described to preserve your rebased commits.

  2. Then, resolve any conflicts or issues as you would after a standard rebase operation.

To push changes made in a detached HEAD state to a remote repository, first, ensure you've moved the changes to a new branch:

Terminal
git checkout -b new-feature
git push origin new-feature

git checkout -b new-feature checks out a new branch with all of the changes in the detached HEAD. The git push command then pushes the branch to your remote repository, so the branch will be tracked and stored remotely. From here, once you have made all the necessary changes in this new branch, you can then merge these changes back into your main development branch by opening a pull request.

When you checkout a remote branch directly, you might end up in a detached HEAD state. To avoid this, always create a new local branch to track the remote branch:

Terminal
git checkout -b local-branch-name origin/remote-branch-name
  • Checkout tag detached HEAD: Checking out a tag directly leads to a detached HEAD. Create a branch if you intend to make changes based on a tag.

  • Detached HEAD on rebase: Always ensure you're on a branch before starting a rebase to avoid detaching.

  • Lost commits in detached HEAD: Use git reflog to find commits made in a detached HEAD state, then branch off from there to recover them.

A detached HEAD in Git is not an error but a state indicating you're directly on a commit. It's useful for exploring history, conducting code reviews, or making temporary experimental changes. Always remember to create a new branch from your detached HEAD if you wish to preserve your changes, thereby avoiding any potential loss of work.

For more information on the detached HEAD state, see the official git documentation.

Give your PR workflow
an upgrade today

Stack easier | Ship smaller | Review quicker

Or install our CLI.
Product Screenshot 1
Product Screenshot 2