Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Revisions and Pathspecs

Revision syntax

Reference for how Git names commits: full and abbreviated IDs, HEAD, branches, tags, special refs, how ambiguous names are resolved and describe output.

A revision is any text Git can turn into an object ID. Almost every command that takes a commit accepts one: git show v1.2, git diff main, git reset --hard HEAD, git log abc1234. The simplest revisions are plain names: the full 40-character hash, a short prefix of it, a branch, a tag, or HEAD. More elaborate forms (HEAD~2, main@{1}, :/fix) build on these names and are covered on their own pages.

Understanding how plain names are resolved matters because they can be ambiguous. A branch and a tag can share a name, and a short ID can match more than one object. Git has fixed rules for which one wins, and knowing them avoids acting on the wrong commit.

Terminal
git rev-parse <revision>             # print the full object ID
git rev-parse --short=8 <revision>   # abbreviated ID
git rev-parse --verify --quiet <rev>^{commit}   # test whether a name resolves

Try it

Bash Different names for the same commit

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Ambiguous names and how Git resolves them

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

A plain revision is one of the following forms:

Form Meaning
<hash> The full object ID: 40 hexadecimal digits (64 in a SHA-256 repository).
<prefix> An abbreviated ID, at least 4 digits, that matches exactly one object.
<refname> A reference: a branch, tag or remote-tracking branch, resolved with the search order below.
HEAD, @ The commit you currently have checked out. @ alone is a shorthand for HEAD.
<describe-output> A name like v1.2-4-g1a2b3c4: the tag, the number of commits since it, and g plus an abbreviated ID.
FETCH_HEAD, ORIG_HEAD, MERGE_HEAD, CHERRY_PICK_HEAD, REVERT_HEAD Special refs written by commands. See below.

Name resolution order. For a name <x>, Git tries these in turn and uses the first that exists:

  1. <x> as a file in .git (such as HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD)
  2. refs/<x>
  3. refs/tags/<x>
  4. refs/heads/<x>
  5. refs/remotes/<x>
  6. refs/remotes/<x>/HEAD

Two consequences: a tag beats a branch of the same name, and origin alone resolves to origin/HEAD.

Special refs:

Name Set by Points to
ORIG_HEAD merge, reset, rebase, pull Where HEAD was before a risky operation. Handy for undoing it.
FETCH_HEAD fetch The tips just fetched; the first line is what pull will merge.
MERGE_HEAD an unfinished merge The commit(s) being merged in.
CHERRY_PICK_HEAD, REVERT_HEAD, REBASE_HEAD a stopped cherry-pick, revert, rebase The commit being applied.

Errors: an unknown name gives fatal: ambiguous argument '<x>': unknown revision or path not in the working tree; a short ID matching several objects gives short object ID <x> is ambiguous plus a list of candidates.

Usage notes

  • Abbreviation length. core.abbrev sets the default (7 characters minimum, growing automatically for large repositories). Never store a short ID long-term; it can become ambiguous later.
  • Disambiguate with full ref names. Use refs/heads/<x>, heads/<x> or tags/<x> in scripts that accept user-provided names. git branch -d and git tag -d only look at their own namespace, so they are unaffected.
  • Ambiguity warning. If a name matches both a tag and a branch, Git warns refname '<x>' is ambiguous on standard error, but uses the tag.
  • Hex-looking names. A branch called abcd can hide commit abcd...: Git prefers the ref. Avoid branch or tag names made only of hex digits.
  • Names with special characters. Branch names cannot contain spaces, ~, ^, :, ?, *, [, .. or @{, because those characters belong to revision syntax. See git check-ref-format.
  • HEAD can be detached. Then it holds a commit ID directly and git symbolic-ref HEAD fails.
  • Case. Ref names are case-sensitive on Linux, but on case-insensitive file systems Release and release can collide in the files backend.