The old version could be read to mean that the argument has to refer
to a valid object, but that is incorrect:

* the object is not necessarily read (e.g., to check for corruption)

* if the argument is a 40-digit string of hex digits, then it is
  accepted whether or not is is the name of an existing object.

So reword the explanation to be less ambiguous.

Also fix the examples involving --verify: to be sure that the argument
refers to a commit (rather than some other kind of object), the
argument has to be suffixed with "^{commit}".  This trick is not
possible in the example involving --default, so don't imply that it is
exactly the same as the previous example.

Signed-off-by: Michael Haggerty <mhag...@alum.mit.edu>
---

This was discussed in the following thread:

    http://thread.gmane.org/gmane.comp.version-control.git/219409

Please note that the second example already reveals a fly in the
ointment:

    $ git rev-parse --default master --verify $REV

Following Junio's advice, we would like to change this to

    $ git rev-parse --default master --verify $REV^{commit}

but that defeats the purpose of the --default option.  Doing

    $ git rev-parse --verify $(git rev-parse --default master $REV)^{commit}

is just plain ugly.  Though honestly, I don't see the point of using
--default as opposed to

    $ git rev-parse --verify ${REV:-master}^{commit}

So maybe the second example should be removed entirely or converted to
use ${REV:-master} rather than --default.

 Documentation/git-rev-parse.txt | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 10a116f..6095227 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -60,8 +60,10 @@ OPTIONS
        instead.
 
 --verify::
-       The parameter given must be usable as a single, valid
-       object name.  Otherwise barf and abort.
+       If the parameter can be used as a single object name, output
+       that name; otherwise, emit an error message and exit with a
+       non-zero status.  Please note that the existence and validity
+       of the named object itself are not checked.
 
 -q::
 --quiet::
@@ -308,12 +310,12 @@ $ git rev-parse --verify HEAD
 * Print the commit object name from the revision in the $REV shell variable:
 +
 ------------
-$ git rev-parse --verify $REV
+$ git rev-parse --verify $REV^{commit}
 ------------
 +
 This will error out if $REV is empty or not a valid revision.
 
-* Same as above:
+* Similar to above:
 +
 ------------
 $ git rev-parse --default master --verify $REV
-- 
1.8.2

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to