Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Revisions and Pathspecs

Peeling objects: ^{type} and ^{}

Reference for Git peel syntax: rev^{commit}, rev^{tree}, rev^{tag} and rev^{} to follow annotated tags down to the object they point at, with examples.

Some objects point at other objects. An annotated tag points at a commit (or another tag), and a commit points at a tree. Peeling follows those pointers until it reaches an object of the type you asked for. The suffix ^{type} means "peel this revision until it is a type", and ^{} means "peel through tags until the result is no longer a tag".

Peeling matters most for annotated tags. The name v1.0 resolves to the tag object itself, which is not a commit. Commands that need a commit usually peel for you, but when you script with git rev-parse or git cat-file you must say so explicitly with v1.0^{commit}.

Terminal
git rev-parse v1.0          # the tag object (annotated tag)
git rev-parse v1.0^{commit} # the commit it points at
git rev-parse HEAD^{tree}   # the root tree of HEAD

Try it

Bash Annotated tag, commit and tree

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 Peeling a tag of a tag, and failing politely

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

Terminal
<rev>^{<type>}   # peel until the object is of type <type>
<rev>^{}         # peel until the object is not a tag
Suffix Result
^{commit} The commit a tag points at. A commit stays as it is. A tree or blob fails.
^{tree} The root tree of a commit; works on a tag that leads to a commit.
^{tag} Requires the object to be a tag object already. Fails for lightweight tags, which are plain refs to commits.
^{blob} Only succeeds if the target already is a blob.
^{} Peel through nested tags and stop at the first non-tag object, whatever its type.

Errors and edge cases: an impossible peel makes the revision invalid. rev-parse --verify exits non-zero, and commands print fatal: ... cannot be peeled or unknown revision. Peeling a commit with ^{tree} never fails, because every commit has a tree.

Usage notes

  • Why scripts peel: git rev-parse v1.0 returns the tag's own ID for an annotated tag, so comparing it with a branch tip fails. git rev-parse v1.0^{commit} always returns a commit ID, for annotated and lightweight tags alike.
  • ^{} versus ^{commit}: ^{} stops at whatever the tag chain ends with, which is normally a commit but may be a tree or blob in unusual repositories. ^{commit} insists on a commit.
  • packed-refs shows peeled values for annotated tags on lines that start with ^; ls-remote prints the same as v1.0^{} entries. These are the peeled commits, so a client can learn the commit without fetching the tag.
  • Not the same as ^1. The caret with a number (HEAD^2) selects a parent; a caret followed by braces peels. See Caret and tilde for the numeric form. HEAD^0 is an old spelling of "peel to commit".
  • Trees and paths: HEAD^{tree} equals HEAD: (the root tree) written with a colon; see rev:path and :N:path. Either works with git ls-tree.
  • Signed tags: peeling does not verify the signature. Use git verify-tag or git tag -v for that, as described in Signed commits and tags.
  • for-each-ref fields with a star (%(*objectname), %(*objecttype)) are the peeled equivalents, handy when listing tags in a script.
  • The shell may eat braces. Quote the revision ("v1.0^{commit}") in zsh and PowerShell to keep it intact.