ORIG_HEAD, FETCH_HEAD, MERGE_HEAD etc

Question

There's a lot of useful git references (what is the exact name for this?), e.g. HEAD, ORIG_HEAD, FETCH_HEAD, MERGE_HEAD, @{upstream} etc.

Is there any reference for this? A complete list with explanations?

Caul

Also: https://mcmap.net/q/11804/-head-and-orig_head-in-git/6309 – Brunn

Did you have trouble searching for the answer online? It's readily available in the git-scm.com and official Linux Kernel Git documentation. – Regenerator

Answer 1

git help revisions brings up http://git-scm.com/docs/gitrevisions, which describes all the the most common ways to reference commits:

• HEAD names the commit on which you based the changes in the working tree.
• FETCH_HEAD records the branch which you fetched from a remote repository with your last git fetch invocation.
• ORIG_HEAD is created by commands that move your HEAD in a drastic way, to record the position of the HEAD before their operation, so that you can easily change the tip of the branch back to the state before you ran them.
• MERGE_HEAD records the commit(s) which you are merging into your branch when you run git merge.
• CHERRY_PICK_HEAD records the commit which you are cherry-picking when you run git cherry-pick.

From the git source, you can also find out about BISECT_HEAD, REVERT_HEAD, REJECT_NON_FF_HEAD and several others that you will almost certainly never need.

That reference also explains suffixes (^N, ~N, @{...}), ranges (.. vs ...), and more.

Embellish

Even though BISECT_HEAD at al are defined in the sources, you shouldn't assume those to be around. I would expect everything listed in git help revisions to be supported in long run. – Divagate

Answer 2

HEAD: The current ref that you’re looking at. In most cases it’s probably refs/heads/master

FETCH_HEAD: The SHAs of branch/remote heads that were updated during the last git fetch

ORIG_HEAD: When doing a merge, this is the SHA of the branch you’re merging into.

MERGE_HEAD: When doing a merge, this is the SHA of the branch you’re merging from.

CHERRY_PICK_HEAD: When doing a cherry-pick, this is the SHA of the commit which you are cherry-picking.

The complete list of these refs can be found by cloning git sources:

git clone https://github.com/git/git.git

and grepping the _HEAD" string in .c files. They are dispersed all over the place, but still can be easily found.

P.S.

git help revisions does not show the list of all possible named refs.

Burkey

Answer 3

This is what the official Linux Kernel Git documentation for Git revisions says:

HEAD names the commit on which you based the changes in the working tree.

FETCH_HEAD records the branch which you fetched from a remote repository with your last git fetch invocation.

ORIG_HEAD is created by commands that move your HEAD in a drastic way, to record the position of the HEAD before their operation, so that you can easily change the tip of the branch back to the state before you ran them.

MERGE_HEAD records the commit(s) which you are merging into your branch when you run git merge.

CHERRY_PICK_HEAD records the commit which you are cherry-picking when you run git cherry-pick.

Also, for @{upstream}:

<refname>@{upstream}, e.g. master@{upstream}, @{u}

The suffix @{upstream} to a ref (short form <refname>@{u}) refers to the branch the ref is set to build on top of. A missing ref defaults to the current branch.

Regenerator

Answer 4

These references are called pointers. They are just regular pointers in programmer terms to tree-ish entities that exist within Git. Note that a tree-ish is anything that consists of at least one commit, i.e. a branch, tag, stash or something like HEAD. Regarding a complete list, I think the only one that exists is the manual:

http://git-scm.com/documentation

While there is no complete list of the available special pointers like HEAD The manual does cover the complete list of available pointers therein, although they are kind of hard to find.

Darnelldarner

Try git help revisions for the documentation. – Divagate

Answer 5

In addition to HEAD and ORIG_HEAD in Git, note that Git 2.44 (Q1 2024), batch 11 defines "special ref" as a very narrow set that consists of FETCH_HEAD and MERGE_HEAD, and clarifies everything else that used to be classified as such are actually just pseudorefs.

See commit 8df4c5d, commit 2cd33f4, commit 3f921c7, commit 35122da, commit fd7c6ff, commit bb02e95, commit 821f663 (19 Jan 2024) by Patrick Steinhardt (pks-t).
^{(Merged by Junio C Hamano -- gitster -- in commit 8282f95, 29 Jan 2024)}

Documentation: add "special refs" to the glossary

^{Signed-off-by: Patrick Steinhardt}

Add the "special refs" term to our glossary.

glossary-content now includes in its man page:

special ref

A ref that has different semantics than normal refs. These refs can be accessed via normal Git commands but may not behave the same as a normal ref in some cases.

The following special refs are known to Git:

• "FETCH_HEAD" is written by git fetch or git pull. It may refer to multiple object IDs. Each object ID is annotated with metadata indicating where it was fetched from and its fetch status.

• "MERGE_HEAD" is written by git merge when resolving merge conflicts. It contains all commit IDs which are being merged.

So HEAD and ORIG_HEAD are pseudorefs, while FETCH_HEAD and MERGE_HEAD are "special refs".

Brunn