summaryrefslogtreecommitdiff
path: root/Documentation/revisions.txt
diff options
context:
space:
mode:
authorJunio C Hamano <gitster@pobox.com>2013-03-31 15:24:12 -0700
committerJunio C Hamano <gitster@pobox.com>2013-03-31 15:57:42 -0700
commita6a3f2cc0761a347e8796280a1544e2a0d08cb51 (patch)
tree8bb80ef4a8b910802799776611462a85dd35de00 /Documentation/revisions.txt
parented1ca6025f965360e42ece66dcbc78bf0c2099a9 (diff)
downloadgit-a6a3f2cc0761a347e8796280a1544e2a0d08cb51.tar.gz
peel_onion(): teach $foo^{object} peeler
A string that names an object can be suffixed with ^{type} peeler to say "I have this object name; peel it until you get this type. If you cannot do so, it is an error". v1.8.2^{commit} asks for a commit that is pointed at an annotated tag v1.8.2; v1.8.2^{tree} unwraps it further to the top-level tree object. A special suffix ^{} (i.e. no type specified) means "I do not care what it unwraps to; just peel annotated tag until you get something that is not a tag". When you have a random user-supplied string, you can turn it to a bare 40-hex object name, and cause it to error out if such an object does not exist, with: git rev-parse --verify "$userstring^{}" for most objects, but this does not yield the tag object name when $userstring refers to an annotated tag. Introduce a new suffix, ^{object}, that only makes sure the given name refers to an existing object. Then git rev-parse --verify "$userstring^{object}" becomes a way to make sure $userstring refers to an existing object. This is necessary because the plumbing "rev-parse --verify" is only about "make sure the argument is something we can feed to get_sha1() and turn it into a raw 20-byte object name SHA-1" and is not about "make sure that 20-byte object name SHA-1 refers to an object that exists in our object store". When the given $userstring is already a 40-hex, by definition "rev-parse --verify $userstring" can turn it into a raw 20-byte object name. With "$userstring^{object}", we can make sure that the 40-hex string names an object that exists in our object store before "--verify" kicks in. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Diffstat (limited to 'Documentation/revisions.txt')
-rw-r--r--Documentation/revisions.txt5
1 files changed, 5 insertions, 0 deletions
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 013f0de798..e82a4db61c 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -116,6 +116,11 @@ some output processing may assume ref names in UTF-8.
object of that type is found or the object cannot be
dereferenced anymore (in which case, barf). '<rev>{caret}0'
is a short-hand for '<rev>{caret}\{commit\}'.
++
+'rev{caret}\{object\}' can be used to make sure 'rev' names an
+object that exists, without requiring 'rev' to be a tag, and
+without dereferencing 'rev'; because a tag is already an object,
+it does not have to be dereferenced even once to get to an object.
'<rev>{caret}\{\}', e.g. 'v0.99.8{caret}\{\}'::
A suffix '{caret}' followed by an empty brace pair