Git Lesson: Be mindful of a detached head

Git Lesson: Be mindful of a detached head

A severed head is never fun, and in git this is no different. In fact, a detached head can cause quite the headache.  In this article I will discuss what a detached head is, how it can happen, and most importantly, what you can do about it.  But before I begin, let’s rehash a bit about how git works.

A git repository is a direct acyclic graph of commits.  Here is a very simple git repository.

In the EGit history view it would look like this:

Now, let’s assume that core and ui bugs (commits E and F) were not actually bugs, but rather controversial design decisions. And the the fixes broke other parts of the application.  After a quick meeting, someone suggests a new way of addressing the problems that will make everyone happy. One problem, they’re not sure if it will actually work.   Since they are using git, they checkout the code before the controversial bugs were addressed (Commit B) and they start hacking away.  Now here’s the crux of the problem: a branch is a linear set of commits, so where do these new commits live? The truth is, head is not actually visible from any branch now.  This is a detached head.


In the EGit history view you can see you have no head.

The good news is that you can quickly fix this problem by creating a new branch.  In egit, this is as simple as Team -> Switch To -> New Branch. Now, all these ‘detached commits’ will live on the new branch (new_idea).

You can now see the new commits (and new branch) in the EGit history view:

What if you accidentally  switched branches while you were on a detached head.  At this point, there is no way to access the commits because they are not attached to any branch. Luckily, git remembers all the commits, even the ones that happened while your head was detached.  Simply drop the command line and issue: git reflog

You can now see the missing commits.  If you return to Eclipse and use Navigate -> Open Git Commit you can open the commit 73df399

And directly create a branch from here

Another very common way to lose your head is to checkout a remote branch. Again, if you checkout a remote branch, immediately create a new local branch for your new commits; otherwise you’ll be working with a detached head.

There is more information about detached heads here.  Remember, don’t fight your tools, just git ‘er done.

  • James Blackburn
    Posted at 5:57 pm, May 29, 2011

    The graph you’ve drawn is confusing – and in particular your image of the detached HEAD is wrong.

    In your DAG you’ve labelled the edge between B and the subsequent node (D,G,E,C) with the branch name. This isn’t how git works. The branch names refer to the tip of the branch, and each commit refers to the previous commit (the parent commit). A Branch is just a label which point to a particular node, and the ancestor nodes make the branch. In you graph the branch names should be pointers to C, D & F.

    For the detached HEAD case: G & B are connected in the graph. It’s just H that’s not labelled / visible from a branch. This is because the set of commits that make up a branch, is just the set of reachable nodes from a particular branch label.

    See also:

    As an asid there’s no reason that the history view shouldn’t show the location of HEAD even if it’s detached. After all the commit you’re on has B as a grand-parent…

  • James Blackburn
    Posted at 10:23 pm, May 29, 2011

    Cool, looks great!

  • Matthias Sohn
    Posted at 5:53 pm, June 7, 2011

    good idea, please file bugs for EGit, we’ll look into that

  • Clive van Hilten
    Posted at 6:52 pm, September 1, 2011

    An Egit newbie, I found myself confronted with the legend ‘NO-HEAD’ against my project. I was baffled by it for a while then realised I hadn’t done the initial commit. For other newbies: right-click the project, select Team, then Commit and insert a commit message like ‘Initial commit’.


Post a Comment