Table of Contents

• Tag
• Git Object

• Detached HEAD
• HEAD

A local repository which has only a commit history, but not a working tree nor a staging area

• Local Repository
• Repository
• Three Trees

A bare repository is typically setup and used by a Git server in a server-client setup of Git.

The Git directory normally contains the working tree user files and the .git directory, but in a bare repository, it contains neither. Instead, the Git directory contains all the files normally contained in the .git directory and no user files. In this kind of setup, user files are committed by clients using git push instead of git commit.

A bare respository can be setup using the git init --bare command.

Beyond this basic description, a bare repository is beyond the scope of this document.

The term "bare repository" is an official Git term and the concept is described in more detail in Git Pro, Chapter 4.1.

1. A reference that points to a commit object
2. The entire chain of commit objects (where each commit object is linked to at least one another commit object as if in a chain)

• a single commit object
• the files indexed on commit objects
• A combination of two or more of the formal and informal definitions

A "branch" defined as a "reference that points to a commit object" is also known as head. (The other definitions of "branch" are not synonyms to "head".)

The term branch reference is refers to only one definition of "branch"

A "branch" is never a synonym to HEAD. ("head" and "HEAD" are two different terms.)

• Branch Reference
• Commit
• Commit Object
• head
• HEAD
• Local Branch
• Reference
• Remote Branch
• Remote-Tracking Branch
• Tracking Branch

• A reference that points to a commit object
• A "synonym" for head (but not for HEAD)
• Sometimes a "synonym" of branch, but not always

• Branch
• head
• Reference

• "Branch reference" is an alternative name for the definition of branch that is also a reference. "Branch reference" is not a synonym of "branch", but rather a clarification to which definition of "branch" is being referred to. With "branch reference", we're speaking about the part of the branch where the reference is, not the chain of commit objects nor a single commit object nor files indexed on the commit object.
• "Branch reference" and head are always synonyms of one another; Do not confuse this with the term HEAD which is never a synonym
• As stated in Too Many Unclear Terms, use of synonyms is strongly discouraged in technical documentation. It's also unfortunate how confusing it can be to determine when "branch", "branch reference", and "head" are synonyms.

• Index
• Staging
• Staging Area
• Staging Index
• Three Trees

• Commit Object
• Git Object
• Index
• Staging Area
• Staging Index
• Tree Object

• Commit
• Reference
• Three Trees

• The commit history is detailed in Pro Git, Chapter 2.3
• It's unclear if official Git documentation includes references as part of the definition of commit history or not

The Commit History is considered to be one of the three trees.

• Commit
• Git Object

"Commit object" is an official Git term and is defined in official Git Glossary and Pro Git, Chapter 10.2.

Git objects / Commit objects go by several names in Git documentation. In the glossary, it can be found under hash, object, and SHA-1. In Pro Git, the terms "commit object", "commit hash" and "SHA-1 Hash" are used. As stated in Too Many Unclear Terms, use of synonyms is strongly discouraged in technical documentation -- and as we see here, the terms "Git Object", "Commit Object", and "Commit hash" are confused by official Git documentation, although there is a difference between these three terms.

• Attached HEAD
• HEAD

When determining whether a HEAD is detached or not, it's irrelevant whether a branch reference points to the same commit object as the HEAD. (In other words, it's possible for a "detached HEAD" and a "branch reference" to point to the same "commit object".) What makes a HEAD attached or detached is whether HEAD points to a reference or to a Git object.

Be careful with detached HEADs! When new commits are committed to the commit history under the detached HEAD, the new commits can be lost if no branches point to the commit object and HEAD is directed to point somewhere else (like a different branch or another commit). There is no good way to later go back to these new commits. Eventually, the garbage collection will destroy the unreferenced commits.

Detached HEADs are safe for viewing "commit objects" in the "commit history", but dangerous for development.

It's possible to turn a detached HEAD into an attached HEAD by creating a branch.

• Branch
• External Repository
• Remote Branch

• Local Repository
• Remote Name
• Remote Repository
• Repository
• Shortname
• Tracked Repository

Git Objects are similar to (but not exactly like) objects found in common programming langauges like Java or C#. The specifics aren't important for casual users, but if you're curious, you can find the information in Pro Git, Chapter 10.2. According to Pro Git, Chapter 10.3, there are four major types of Git objects: tree objects and commit objects, tags, and blobs. Blobs are not relevant to the casual Git user and are therefore not discussed on this website. Tree objects form the underlying structure of certain parts of Git and sometimes are used to organize and store user files within Git. For this reason, commit objects use tree objects to store user files. Tags sometimes (but not always) do something similar.

Git objects / Commit objects go by several names in Git documentation. In the glossary, it can be found under hash, object, and SHA-1. In Pro Git, the terms "commit object", "commit hash" and "SHA-1 Hash" are used. As stated in Too Many Unclear Terms, use of synonyms is strongly discouraged in technical documentation -- and as we see here, the terms "Git Object", "Commit Object", and "Commit hash" are confused by official Git documentation, although there is a difference between these three terms.

• A reference that points to a commit object
• A "synonym" for branch reference
• Sometimes a "synonym" of branch, but not always

• Branch
• Branch Reference
• HEAD
• Reference

• Do not confuse with the term HEAD
• The terms "head" and "branch reference" are always synonyms of each other.
• The definition of branch has multiple definitions, but "head" is only a synonym to one of those definitions. (It is a synonym to "a reference that points to a commit object".) This means that "head" is always a "branch", but a "branch" may or may not be a "head".
• The idea that "branch" and "head" are synonyms may surprise some people. A more detailed explanation can be found under the detailed definition of branch
• As stated in Too Many Unclear Terms, use of synonyms is strongly discouraged in technical documentation. It's also unfortunate how confusing it can be to determine when "branch", "branch reference", and "head" are synonyms.

• Do not confuse with the term head
• Because the definition of "reference" is unclear, HEAD must 1) have two separate definitions or 2) the two definitions can be combined into one. See the detailed definition of reference for more information about references and symbolic references.

There are two types of HEADs:

1. Attached HEAD -- A symbolic reference that points to a reference in the commit history; Most of the time, HEAD points to a branch reference.
2. Detached HEAD -- A reference that points to a Git object

• Attached HEAD
• Branch
• Branch Reference
• Detached HEAD
• head
• Reference
• Symbolic Reference

• Cache
• Commit
• Ref
• Reference
• Refspec
• Remote Reference
• Staging
• Staging Area
• Tag
• Three Trees

• Tag

• Branch
• Local Repository
• Remote Branch
• Remote-Tracking Branch
• Tracking Branch
• Upstream Branch

• Local Repository
• Reference
• Refspec
• Remote Reference

• External Repository
• Local Reference
• Remote Name
• Remote Repository
• Repository
• Three Trees

• Tracking Branch
• Remote-tracking Branch

Having a "local tracking branch" implies having a "remote tracking branch", but the term remote-tracking branch already exists and the two terms could easily be confused.

Relative to a given repository, the terms tracking branch and remote-tracking branch are always stored on a local repository.

• Tracking Branch
• Local Branch

A tracking branch is always a local branch, but a local branch is not necessarily a tracking branch. On the surface, it seems logical that the term non-tracking local branch should exist, but the term "tracking" is actually undefined by Git and undefined by Git documentation. Strangely, even though the term is undefined, the term "tracking" is in heavy use. Because of this, the term "tracking branch" is on very shaky ground. Without a firm, official definition of what a "tracking branch" is, we shouldn't use the term "non-tracking local branch". For detailed information, see my dedicated section of What is Tracking?

• Reference

As I described in Too Many Unclear Terms, synonyms are not acceptable. Unfortunately, the term "ref" (or the plural "refs") is used a lot in the official Git documentation and glossary.

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

• Branch
• Branch Reference
• Commit History
• Detached HEAD
• Git Object
• head
• HEAD
• Index
• Local Reference
• Ref
• Refspec
• Remote Reference
• Symbolic Reference
• Symref
• Tag

Whether a term qualifies as a reference or not can be very confusing. (For instance, "HEAD" may or may not be a reference, but "detached HEAD" is definitively a reference. A tag is sometimes a reference and sometimes not.) Under "More Details", I provide a list of terms, whether they classify as references, and why.

A mapping between references in a remote repository (known as the "source") and references in a local repository (known as the "destination"); refspecs can be used in Git commands like git pull or git push; refspecs are stored in .git/config

• Branch
• Local Reference
• Ref
• Reference
• Remote Name
• Remote Reference
• Remote-Tracking Branch
• Tracking Branch

• Don't EVER use this term
• Don't assume you know what "remote" means until you you've read Demystifying Remotes
• Don't assume the word "remote" modifies another word in a term (i.e., reference and remote reference can be two very different concepts)
• If you see the term "remote" as a single word by itself in official or unofficial Git documentation, it probably means remote repository or remote reference, but not always

• Remote Name
• Remote Repository
• Repository
• Shortname
• Tracked Repository

Official Git documentation also uses the term "remote" like the regular English term "remote", but this is also used incorrectly. Again, this explained in Demystifying Remotes.

I've seen more than one unofficial website say git remote adds and removes "remote references". As explained in Demystifying Remotes, it does not.

In the official documentation, I spotted one place in Pro Git where it might be utilized like this, but I believe it to merely be either an unclear statement or an error. This anomaly can be found in Chapter 3.5 with the quote "You can add it as a new remote reference to the project you’re currently working on by running the git remote add command...". Looking at the quote just as I copied here, it looks like this is an error, but in full context of the chapter, I think they are trying to say that a side effect of running git remote creates a remote reference -- and this is correct. The primary function of git remote is to create or remove remote names, but part of that process also includes creating or removing remote references in the local repository. (The other possibility is that the author meant to use the term "remote repository" instead of "remote reference".)

Other commands have similar side effects on remote references. git clone creates remote references as a side effect. Remote references are also added, remoted, or altered by the git commands git fetch, git push, and git pull. Other commands like git branch can also have a direct influence over the remote references.

So, no, git remote does not add and remove "remote references".

• reference and remote reference can be two very different concepts
• The terms tracking branch and remote-tracking branch are both stored in the local repository (but remote branch is stored on a remote repository)
• Two or more remote repositories can be stored "locally" on the same computer and on the same hard drive
• I found the term "remote-management skills" used one time in the Pro Git documentation, but I can only guess as to what that really means
• I make an argument that a remote repository is always an external repository, but an external repository is not necessarily a remote repository

• Do not confuse this with an external branch
• Do not confuse this with an upstream branch

• Branch
• External Branch
• Local Branch
• Remote Repository
• Remote-Tracking Branch
• Tracking Branch
• Upstream Branch

• External Repository
• Local Repository
• Ref
• Reference
• Refspec
• Remote
• Remote Branch
• Remote Reference
• Remote Repository
• Remote-Tracking Branch
• Shortname
• Tracked Repository
• Tracking Branch
• Upstream
• Upstream Branch

There are two official definitions, and both definitions are widely used on the internet. It's confusing, but unfortunately, I don't see a way to fix this problem, so I have left both defined here.

1. a reference in an external repository which points to a Git object on that same external repository; the local repository merely observes the reference
2. a reference in a local repository which points to a Git object on an external repository; the local repository actively stores the reference

• External Repository
• Local Reference
• Local Repository
• Ref
• Reference
• Refspec
• Remote
• Remote Branch
• Remote Repository
• Remote-Tracking Branch
• Shortname
• Tracked Repository
• Tracking Branch
• Upstream
• Upstream Branch

• External Repository
• Local Repository
• Remote
• Remote Name
• Repository
• Shortname
• Tracked Repository

• Branch
• Remote Branch
• Remote Reference
• Remote Tracking Branch
• Tracking Branch
• Upstream Branch
• Refspec

The use of this term in the official Git documentation must be incorrect.

The man pages of git fetch and git pull use the term "remote-tracking reference" in their pruning sections. However, by definition of what a reference is, orphaned Git references cannot exist. Instead, pruning refers to the process of cleaning up orphaned Git objects. (You can see that in the man pages of git prune. Atlassian also has a good article about the command.)

The term "remote-tracking ref" can be found in the man pages of git push. (If there are other uses of this term in official Git documentation, I'm unaware of it.) The information in these man pages of "git push" is beyond my understanding, but for the same reasons I gave above, it should not exist here either.

• Repository

• External Repository
• Local Repository
• Remote
• Remote Repository
• Repo
• Tracked Repository

• External Repository
• Local Repository
• Remote
• Remote Name
• Remote Repository

• Staging
• Staging Area
• Staging Index

• Cache
• Index
• Staged Files
• Staging Area
• Staging Index
• Three Trees
• Working Directory
• Working Tree

• Cache
• Commit
• Index
• Staged Files
• Staging
• Staging Index
• Three Trees

• Cache
• Commit
• Index
• Ref
• Reference
• Refspec
• Staged Files
• Staging
• Staging Area
• Three Trees

• Reference

• Symbolic Reference

A user defined "label" which marks something in Git is important; Typically this is used to mark commit objects and name the releases of a program (like "v1.0", "v2.0.3", etc)

1. Annotated Tag -- Tag saved as a Git object
2. Lightweight Tag -- Tag saved as a reference

• Annotated Tag
• Git Object
• Index
• Lightweight Tag
• Reference

• Working Tree (or Working Directory)
• Staging Area (or Staging Index or Index or Cache)
• Commit History (or The HEAD)

• Cache
• Commit History
• HEAD
• Index
• Staging
• Staging Area
• Staging Index
• Tree Object
• Working Directory
• Working Tree

• In the staging area or
• In the commit history or
• Both the "staging area" and the "commit history"

• Commit History
• Staging Area
• Untracked File
• Working Tree

"Tracked Files" and untracked files have nothing to do with tracking, tracking branches, tracked repositories, or remote-tracking branches.

"Tracked files" and "untracked files" are very poorly defined by Git documentation and the information is contradictory. This means there is a chance that my definition is incorrect. You can read the details in What is "Tracking"?

• External Repository
• Remote
• Remote Name
• Remote Repository
• Repository
• Tracking Branch

• The idea that Git is somehow able to track branches in a remote repository
• The existence of a tracking branch

The existence of an unnamed link between a local branch and a remote branch; this unnamed link provides shortcuts to the user while typing in some Git commands like git fetch, git pull, or git push

Note: Although it is more difficult, "tracking" is not required to fetch, pull, or push

• Remote-Tracking Branch
• Tracked Repository
• Tracking Branch

I made up an official definition based on official information, because there is no official definition for "tracking" that I know of.

My unofficial definition is more accurate than the official definition I wrote, but the unofficial definition is still confusing, incomplete, inaccurate, and ultimately only marginally better than the official definition.

If the unofficial definition didn't make sense, a full understanding of "tracking" and its supporting terminology can be achieved by reading my article What is "Tracking"? Unfortunately, because the term "tracking" is used in such a poor way, I have to take the reader through a round-about trek in order to understand what "tracking" is and what its supporting terms actually mean.

In my opinion, the term "tracking" is defined so badly that it should never be used at all. Unfortunately, Git commands and Git documentation use the terms "tracking" or "tracked" frequently, so it will stay around for a long time.

• Branch
• Remote Branch
• Remote-Tracking Branch
• Tracked Repository
• Upstream Branch
• Refspec

• Commit
• Git Object
• Three Trees

• Tracked File
• Commit History
• Staging Area
• Working Tree

Tracked Files and "untracked files" have nothing to do with tracking, tracking branches, tracked repositories, or remote-tracking branches.

"Tracked files" and "untracked files" are very poorly defined by Git documentation and the information is contradictory. This means there is a chance that my definition is incorrect. You can read the details in What is "Tracking"?

• Remote Repository
• Upstream Branch
• Upstream Repository

• This term is basically a synonym for "remote repository" and as I described in Too Many Unclear Terms, synonyms are not acceptable. Additionally, at its heart, Git is a peer-to-peer program, not a server-client program. The term "upstream" in a peer-to-peer environment is clunky at best. For these reasons, I would love to see the term "upstream" purged from all official Git documentation and all Git commands, but unfortunately, the term "upstream" is widely used. Getting rid of this term will be very tough, if not impossible.
• There is no official definition for "upstream" that I'm aware of, but the definition is based on upstream branch and upstream repository.

• Remote Branch
• Remote-Tracking Branch
• Tracking Branch
• Upstream
• Upstream Repository

• Remote Repository
• Upstream
• Upstream Branch

• This term is a synonym for "remote repository" and as I described in Too Many Unclear Terms, synonyms are not acceptable. Additionally, at its heart, Git is a peer-to-peer program, not a server-client program. The term "upstream repository" in a peer-to-peer environment is clunky at best.
• To my knowledge, this term is not defined anywhere official, but it is used once in the Git glossary (under the term origin) and twice in Pro Git book (once in Chapter 6.2 and once in Chapter 7.11). My definition if based on these references and the definition of the term upstream branch.

• Staging
• Three Trees
• Working Tree

• Working Directory
• Three Trees
• Staging