Merge branch 'mh/rev-parse-verify-doc'

"rev-parse --verify" was documented in a misleading way.

* mh/rev-parse-verify-doc:
rev-parse: clarify documentation for the --verify option

diff --combined Documentation/git-rev-parse.txt
index 10a116faf8f681c9984c9b52949e84c227fdc26e,757d195962559e3fd18678bb7e27e0a9b916c4ad..1f9ed6cfd28622afcf269eb8dac05fb9414d9901
--- 1/Documentation/git-rev-parse.txt
--- 2/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@@ -14,7 -14,7 +14,7 @@@ SYNOPSI
  DESCRIPTION
  -----------
  
 -Many git porcelainish commands take mixture of flags
 +Many Git porcelainish commands take mixture of flags
  (i.e. parameters that begin with a dash '-') and parameters
  meant for the underlying 'git rev-list' command they use internally
  and flags and parameters for the other commands they use
@@@ -60,8 -60,19 +60,19 @@@ OPTION
        instead.
  
  --verify::
-       The parameter given must be usable as a single, valid
-       object name.  Otherwise barf and abort.
+       Verify that exactly one parameter is provided, and that it
+       can be turned into a raw 20-byte SHA-1 that can be used to
+       access the object database. If so, emit it to the standard
+       output; otherwise, error out.
+ +
+ If you want to make sure that the output actually names an object in
+ your object database and/or can be used as a specific type of object
+ you require, you can add "^{type}" peeling operator to the parmeter.
+ For example, `git rev-parse "$VAR^{commit}"` will make sure `$VAR`
+ names an existing object that is a commit-ish (i.e. a commit, or an
+ annotated tag that points at a commit).  To make sure that `$VAR`
+ names an existing object of any type, `git rev-parse "$VAR^{object}"`
+ can be used.
  
  -q::
  --quiet::
@@@ -147,7 -158,7 +158,7 @@@ shown.  If the pattern does not contai
        relative to the current working directory.
  +
  If `$GIT_DIR` is not defined and the current directory
 -is not detected to lie in a git repository or work tree
 +is not detected to lie in a Git repository or work tree
  print a message to stderr and exit with nonzero status.
  
  --is-inside-git-dir::
@@@ -187,11 -198,9 +198,11 @@@
        Flags and parameters to be parsed.
  
  --resolve-git-dir <path>::
 -      Check if <path> is a valid git-dir or a git-file pointing to a valid
 -      git-dir. If <path> is a valid git-dir the resolved path to git-dir will
 -      be printed.
 +      Check if <path> is a valid repository or a gitfile that
 +      points at a valid repository, and print the location of the
 +      repository.  If <path> is a gitfile then the resolved path
 +      to the real repository is printed.
 +
  
  include::revisions.txt[]
  
@@@ -308,12 -317,12 +319,12 @@@ $ git rev-parse --verify HEA
  * 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