[PATCH] Documentation/rev-parse: --verify does not check existence

[Thomas Rast <trast@student.ethz.ch>]

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@gmail.com>
Signed-off-by: Thomas Rast <trast@student.ethz.ch>
---
 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