This page looks best with JavaScript enabled

Demystifying the scary detached HEAD in Git

 ·  ☕ 4 min read  ·  ✍️ Iskander Samatov

detached HEAD

I agree, the You are in 'detached' HEAD state message does sound scary. I wish the creators of Git picked a less alarming one. But let me put your worries at ease – the detached HEAD state is easily reversible and is a natural state of a project. Here’s what the full message looks like:

detached head git
detached HEAD message

If you’re here for the solution, feel free to skip to the “How to fix” section. If you would like to know more about the reasoning behind the state, then read along.

Basics of Git

First, let’s skim over how Git works. Don’t worry we’ll only cover enough to understand the root cause of the state.

The parent-child relationship of commits

Git is a system made of objects and pointers. Commits are connected through the parent-child relationship. Each commit points to a previous commit as its parent. Here’s a diagram to illustrate this point:

commit links
Commits relationship

Notice how each commits points to the previous one, except for the first commit.

The next question then is what is HEAD? HEAD is a pointer to your current working commit. It also defines the current state of your project. Usually, HEAD points to a branch.

Git branch

A lot of people have a general idea of what branch is. But let’s try to come up with a simple definition. Simply put branches are labels for commits. When you push to a branch, that label now points to the new commit. And when you run a checkout command with a branch name, Git checks out the latest commit the branch points to.

Following that logic, when HEAD points to a branch, it points to the latest commit under that branch.

git commit branch label
Commit branch

Notice how both master branch and HEAD point to the same commit.

What is a detached HEAD?

So what is a detached HEAD? According to Tower’s blog post: “When a specific commit is checked out instead of a branch – is what’s called a “detached HEAD.”

To reiterate, it means that the HEAD of your project is not pointing to a branch anymore. Instead, it’s pointing to a specific commit. It happens when you run the checkout command using a commit hash rather than a branch name. As a side-note, you can get hashes of your commits using git log:

git log
git log

Reasons to detach the HEAD

There are a couple of reasons to check out a specific commit. One of them is to debug or fix issues. In that case, rolling back to a certain moment can be helpful.

Another reason is to experiment with alternative solutions to any given problem. Since the state is simple to correct, that’s a great way to play around with your code. 

How to fix

Remember, a detached HEAD is not an error but a feature in Git. With that said, there are two ways to make things go back to “normal.”

Check out a different branch

If you found yourself in this state by accident or finished experimenting, all you need to do is check out another branch. Git will discard your uncommitted code, and your HEAD will point to a branch again.

Create a new branch and commit your code.

If you have some code changes you don’t want to lose, create a new branch and commit your code. Here are the Git commands to do so:

git branch <branch-name>
git checkout <branch-name>

Once you do that, you can commit and push your code to the new branch. As long as you do that before returning to your regular branch, you’ll be fine.

And there you have it! Once you understand the underlying logic in play, the detached HEAD is not so scary and can be quite useful.

If you’d like to get more web development, React and TypeScript tips consider following me on Twitter, where I share things as I learn them.
Happy coding!

Share on

Software Development Tutorials
Iskander Samatov
The best up-to-date tutorials on React, JavaScript and web development.