Rather counterintuitively,
$ git rev-parse --verify aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
does *not* fail. The check is based solely on whether we can come up
with something that "looks like" a SHA1, not whether the object
actually exists. To wit:
# this cannot be done with update-ref as that *does* check
$ echo aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa > .git/refs/heads/nonexistent
$ git rev-parse --verify nonexistent
aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
Note that the commit message of 79162bb makes clear that this is
exactly the intended behaviour:
git-rev-parse: Allow a "zeroth" parent of a commit - the commit itself.
This sounds nonsensical, but it's useful to make sure that the result is
a commit.
[...]
Also, since the "parent" code will actually parse the commit, this,
together with the "--verify" flag, will verify not only that the result
is a single SHA1, but will also have verified that it's a proper commit
that we can see.
Document this clearly in the description for --verify.
Furthermore the second item in EXAMPLES
* Print the commit object name from the revision in the $REV shell variable:
seems to imply that rev-parse should actually check that the object
exists *and* is a commit, when in reality it does neither. We could
suggest the ^0 trick alluded to above, but instead document the more
verbose (and clear)
$ git rev-parse --verify "$REV^{commit}"
Observe that if you ran
$ git rev-parse --verify "nonexistent^{commit}"
after the above setup, the failure would come from the ^{} peeling
operator and not from --verify.
Noticed-by: Zachery Hostens <zacheryph@xxxxxxxxx>
Signed-off-by: Thomas Rast <trast@xxxxxxxxxxxxxxx>
---
Documentation/git-rev-parse.txt | 23 +++++++++++++++++------
1 files changed, 17 insertions(+), 6 deletions(-)
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index ff23cb0..779fa87 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -59,8 +59,9 @@ OPTIONS
instead.
--verify::
- The parameter given must be usable as a single, valid
- object name. Otherwise barf and abort.
+ The parameter must either be formed like an object name, or
+ dereference to an object name. This does 'not' verify that
+ the object actually exists! See EXAMPLES below.
-q::
--quiet::
@@ -292,21 +293,31 @@ EXAMPLES
$ git rev-parse --verify HEAD
------------
-* Print the commit object name from the revision in the $REV shell variable:
+* Print the object name from the revision in the $REV shell variable:
+
------------
$ git rev-parse --verify $REV
------------
+
-This will error out if $REV is empty or not a valid revision.
+This will error out if $REV does not dereference to a well-formed
+object name (i.e., SHA1).
-* Same as above:
+* Same as above, but also verify that the object exists and is a commit:
++
+------------
+$ git rev-parse --verify "$REV^{commit}"
+------------
++
+This works because the `{caret}\{commit\}` peeling operator will fail
+unless the object exists and can be peeled into a commit.
+
+* Print the object name from $REV, but default to master:
+
------------
$ git rev-parse --default master --verify $REV
------------
+
-but if $REV is empty, the commit object name from master will be printed.
+If $REV is empty, the commit object name from master will be printed.
Author
--
1.7.4.rc1.309.g58aa0
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html