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}.
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
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.
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
<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.0returns 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-refsshows peeled values for annotated tags on lines that start with^;ls-remoteprints the same asv1.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^0is an old spelling of "peel to commit". - Trees and paths:
HEAD^{tree}equalsHEAD:(the root tree) written with a colon; see rev:path and :N:path. Either works withgit ls-tree. - Signed tags: peeling does not verify the signature. Use
git verify-tagorgit tag -vfor that, as described in Signed commits and tags. for-each-reffields 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}") inzshand PowerShell to keep it intact.
Related
- Revision syntax, Caret and tilde, Tag objects
- git tag, git rev-parse, git cat-file
- Lessons: Tags, Objects