ref [git]

A ref is just a pointer to an object.

It could be a file with a string in it.

A ref is a name that begins with refs/ (for example refs/heads/master) that points to an object name or another ref. (The latter is called a symbolic ref)

For convenience, a ref can sometimes be abbreviated when used as an argument to a Git command (see man gitrevisions for details).

Refs are stored in the repository, apparently under .git/refs.

The ref namespace is hierarchical. Different subhierarchies are used for different purposses (e.g. the refs/heads hierarchy is used to represent local branches).

There are a few special-purpose refs that do not begin with refs/, for example HEAD.

The available local refs are shown with git show-ref.

reflog

A reflog shows the local history of a ref.

remote-tracking branch

A ref that is used to follow changes from another repository. It typically looks like refs/remotes/foo/bar (which indicates that it traces a branch named bar in a remote named foo), and matches the right-hand-side of a configured fetch refspec.

A remote-tracking branch should not contain directmodifications or have local commits made to it.

Symbolic reference

Instead of containing the SHA 1 id itself, a symbolic reference is of the format ref: refs/some/thing and when referenced, it recursively dereferences to this reference.

HEAD is a prime example of a symref. Others are:

.git/FETCH_HEAD
.git/ORIG_HEAD
MERGE_HEAD
CHERRY_PICK_HEAD

Symbolic references are manipulated with the git-symbolic-ref command.

refspec

A refspec maps a reference from a remote to the local repository.

The format of a refspec consists of three parts: an optional +, an optional source-ref which is separated by a colon from the (also optional?) remote ref-spec.

+source:destination

An example of a refspec with an empty source-ref is the following push command which deletes the remote branch V1.1 (because it pushes «nothing» there).

git push :V1.1

ref namespaces

refs.c fills the struct ref_namespace_info ref_namespace (whose indices correspond to the enum ref_namespace) like so

			exact
`NAMESPACE_HEAD`	`HEAD`	`DECORATION_REF_HEAD`	✓
`NAMESPACE_BRANCHES`	`refs/heads/`	`DECORATION_REF_LOCAL`	✗
`NAMESPACE_TAGS`	`refs/tags/`	`DECORATION_REF_TAG`	✗
`NAMESPACE_REMOTE_REFS`	`refs/remotes/`	`DECORATION_REF_REMOTE`	✗	The default refspec for new remotes copies refs from `refs/heads/` on the remote into `refs/remotes/<remote>/`. As such, `refs/remotes/` has special handling.
`NAMESPACE_STASH`	`refs/stash`	`DECORATION_REF_STASH`	✓	The single ref `refs/stash` stores the latest stash. Older stashes can be found in the reflog.
`NAMESPACE_REPLACE`	`refs/replace/`	`DECORATION_GRAFTED`	✗	This namespace allows Git to act as if one object ID points to the content of another. Unlike the other ref namespaces, this one can be changed by the GIT_REPLACE_REF_BASE environment variable. This `.namespace` value will be overwritten in `setup_git_env()`.
`NAMESPACE_NOTES`	`refs/notes/commit`	n/a	✓	The `refs/notes/commit` ref points to the tip of a parallel commit history that adds metadata to commits in the normal history. This ref can be overwritten by the core.notesRef config variable or the `GIT_NOTES_REFS` environment variable.
`NAMESPACE_PREFETCH`	`refs/prefetch/`	n/a	✗	Prefetch refs are written by the background `fetch` maintenance task. It allows faster foreground fetches by advertising these previously-downloaded tips without updating refs/remotes/ without user intervention.
`NAMESPACE_REWRITTEN`	`refs/rewritten/`	n/a	✗	Rewritten refs are used by the 'label' command in the sequencer. These are particularly useful during an interactive rebase that uses the 'merge' command.

TODO

$ git clone https://github.com/git/git
$ cd git
$ git config --get-regexp branch.master
branch.master.remote origin
branch.master.merge refs/heads/master
$ cd .git
$ find -name origin
./refs/remotes/origin
./logs/refs/remotes/origin
$ cat refs/remotes/origin/HEAD
ref: refs/remotes/origin/master
$ cat logs/refs/remotes/origin/HEAD
…