Reference
Definition:
  1. A pointer to a Git object; The official Git documentation is unclear about whether a reference can point to another reference
  2. A string representing a location where the reference is found under .git
Related Terms:

How Other Terms Relate to the Term "Reference"

References have been made very confusing by the Git documentation, so here is a list of terms and how they classify as references.

Sources of My Claims

I make a lot of bold claims as what is a reference and what isn't, so this entry is probably both surprising and confusing. If my explanations below do not satisfy you, it's best to read the information I provide in the individual terms.

The Difference Between Reference and Symbolic Reference:

It's clear that a symbolic reference is a pointer that points to another reference. The exact definition of reference, however, is unclear. In Pro Git, Chapter 10.3, it states "By symbolic reference, we mean that unlike a normal reference, it contains a pointer to another reference". This means that a reference cannot point to other references. However, in the Git glossary for the term "ref", it states that a reference points to an object or another reference. This means that a reference can point to other references. Both definitions cannot be true.

From a general perspective in the IT world, there is no standard definition for "reference" that I'm aware of, so "references" may or may not include "symbolic references", although most teams take a hard stance one way or another.

Personally, I don't care which definition the Git team decides upon so long as it is clear where the line is drawn. The question I would pose to them is "What is the purpose of distinguishing between the term 'reference' and the term 'symbolic reference'?" Once that question is clearly answered, then the definitions should fall into place. One thing to keep in mind: if the term "reference" includes the idea of "symbolic reference", then HEAD is not just a "symbolic reference" but also a "reference" (which I don't think was the intention of the Git team).

The Difference Between Reference and Branch:

My glossary is clear: a branch is a type of reference. Certain parts of the Git documentation are not as clear.

A casual user might read Pro Git, Chapter 10.3 to learn about references without reading the rest of the book. This chapter describes how to look at references in detail by looking just at a branch. This might cause some casual users to erroneously equate the terms "branch" and "reference", but this would be incorrect.

To be clear: a branch is a specific kind of reference that points only to a commit object. "References" in general may point to any kind of Git object.

Special Note About Tags, Git Objects, and References

Simplified, we can say there are two types of tags:

Git documentation about tags is confusing and unclear. Fortunately, I was able to (mostly) sort out the confusion. Details can be found in my detailed definition of tag.

Unfortunately, with the confusion about reference and symbolic reference (as indicated above), it's unclear how Lightweight tags are supposed to behave and how they actually behave.

Storage of References

Generally speaking, references (that are not symbolic references) are stored in the Git repository under the folder .git/refs. There are three subfolders for the three types of references:

The above is not always true, though. There are two instances I'm aware of:

Note: Sometimes, Git documentation talks about a reference like in terms of refs/ (like the Git glossary entry for ref). They are actually talking about the information located in the folder .git/refs.

Refs vs References

The Git glossary states that ref is only a string that represents where a reference can be found inside of .git. However, Pro Git, Chapter 10.3 explains that reference is both an actual pointer and the string representation. The chapter also states that "ref" and "reference" are synonyms:

In Git, these simple names are called “references” or “refs”
Synonym Problem
Synonyms should not be used in technical documentation. See Too Many Unclear Terms for a detailed explanation.
Final Thoughts

Concerning official Git documentation, I've made it fairly clear in other parts of this website that there are a lot of things I'm disappointed in. Although references are one of my bigger disappointments, I didn't specifically focus on references in the other parts of my website. (I certainly go into some detail in Demystifying Remotes, though.)

That's not to say that all of the documentation is horrible. Despite the severe terminology flaws and some organizational problems, Pro Git actually has a lot of good and helpful information. When used with my glossary, I believe it can be a very helpful resource.

Return to Glossary