What is Git HEAD? A Practical Guide Explained with Examples

by

There are chances you have been working with Git version control for a while and recently saw an article using the keyword HEAD after using a git command such as revert to rollback to the last commit after you unintentionally made a commit you were not intending to do.

The HEAD in Git is a file that references the current branch you are currently on. Hence, if you are currently are in a master branch, the HEAD will have as a reference the master branch. If you checkout a different branch called styles, the HEAD reference will be updated to the styles branch.

Ways to see the HEAD reference

Using the symbolic-ref command

There are different ways to verify the branch that HEAD is referencing. One option git documentation uses to read the value of the HEAD is to use the symbolic-ref command.

git symbolic-ref HEAD

You should see a similar output to the following if you currently are in the master branch:

refs/heads/master

Let’s say we are going to checkout the styles to verify if the value of HEAD is updated.

git checkout styles
git symbolic-ref HEAD

You should see the following output:

refs/heads/styles

Using the log command

Another alternative to find the reference of HEAD is by using the log command and check the first commit record. It should show the HEAD pointer in the first output record displayed in the terminal. Feel free to include the --oneline config when using the log command if you don’t need to get additional information of commits such as the author and date of the commit.

git log --oneline

Once you run the log --oneline command, you should a similar output like this:

Location of HEAD using git log

One disadvantage of this approach is the log command will show the log of every commit you have had in your repository, which might be too large and unnecessary to determine the branch HEAD is referencing.

Reading the content of the HEAD file

Knowing the HEAD file stores the reference of the current branch, we can read the file by manually opening the file or using the terminal.

If you decide to open the HEAD file using the OS interface, you will find it inside the .git folder generated in the repository.

Location of HEAD file

On the other hand, if you rather check the content of the HEAD file using the terminal, make sure you open the terminal in the root of the folder and run the cat command to read the content of HEAD.

cat .git/HEAD

For instance, I had previously checked out the styles branch. Then, after running the cat command, this is the output my terminal shows.

Location of HEAD using cat command

Example of using the HEAD

Luckily, we can use the HEAD when running other git commands. For instance, you can revert the last commit of your current branch in case you made a mistake or didn’t intend to commit changes using the revert command.

git revert HEAD

In this case, using HEAD is convenient to reference the last commit of the current branch. Otherwise, you would need to get the SHA-1 or mechanism to identify commits in git, which you have probably seen in a 7-character id as the following id: bbe9073.

What is Git HEAD^ (with caret)?

Git HEAD^ or git HEAD followed by a caret is a shorthand for git HEAD^1. Git HEAD^1 means the commit’s first parent. Hence, git HEAD^2 is the commit’s second parent.

What does a commit’s parent mean?

The concept of a commit’s parent is easier to understand if we have a branch merged into another branch as well as having a git tree diagram with the commits of each branch. For the following diagram, we are going to have two branches:

  • Master branch (green color)
  • Other_branch branch (yellow color)
Understanding git HEAD^ (with caret)

We are currently in commit A in the master branch. Notice how commit E from the other_branch branch merged onto the master branch. Hence, commit A has two parent commits, B and E. Another way to visualize the parents is to remove one branch from the tree diagram.

Parents of commit A

Therefore, in the master branch, commit A has a parent commit B. In the other_branch branch, commit E is the parent commit of A. A parent commit is the previous commit of a commit.

Whenever there is a merge into a branch, in our case, the master branch, the last commit of the branch merged onto will be the first parent commit. Therefore, if we are in commit A after merging into the master branch and we use HEAD^ or HEAD^1, we will get commit B.

git show HEAD^ --oneline

Hence, the second parent is the left to the last commit of the “other_branch” branch or commit E.

git show HEAD^2 --oneline

Notice there are only two parents committed off of commit A. Hence, attempting to use HEAD^3 will lead to git throwing the following error:

fatal: ambiguous argument 'HEAD^3': unknown revision or path not in the working tree

Use '--' to separate paths from revisions, like this: 'git […] -- […]'

What is Git HEAD~ (with tilde)?

Git HEAD~ or git HEAD followed by a tilde is a shorthand for git HEAD~1. Git HEAD~1 means the previous commit of the last commit. Contrary to using the caret, git HEAD~ or HEAD with a tilde is simpler to understand as it references the previous commit of a specific branch. Another way to think about this is to go backward in a straightline.

To understand this concept, we are going to take a look at the following diagram.

Undertstanding git HEAD~ (with tilde)

In the previous diagram, notice the green color sequence of commits is the master branch. Hence, if we use the HEAD with the tilde we will have the following results:

  • HEAD~ or HEAD~1 is commit B
  • HEAD~2 is commit C
  • HEAD~3 is commit D

Let’s say the HEAD is no longer in commit A, but instead in commit E in the “other_branch” branch. If we would want to get the reference of the previous commits using the HEAD with the tilde, we would get the following results:

  • HEAD~ or HEAD~1 would be commit F
  • HEAD~2 would be commit G

What is Git HEAD@{} (with at symbol)?

Git HEAD@{} or git HEAD followed by the at symbol and curly braces displays where the reference or HEAD was pointing at different times in the local repository. If you saw HEAD@{}, you probably used the reflog git command. The reflog shows the reference logs.

Reference logs using git reflog command

Conclusion

All in all, the HEAD serves as a guide, pointer, or reference to tell the current branch we are working on. It is useful to learn what is the HEAD and all of its different variations such as using it with a caret (HEAD^), with a tilde (HEAD~), or with the at symbol and curly braces (HEAD@{}) in case you need to go back in history to checkout previous commits or revert the last commit.

Interested in Learning more about Git?

I wrote other articles explaining how to use other git commands, and I thought you might be interested in reading some of them since you are reading this.

Did you like this article?

Share your thoughts by replying on Twitter of Become A Better Programmer or to personal my Twitter account.