From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 5 Apr 2013 21:15:20 +0000 (-0700)
Subject: Merge branch 'mh/rev-parse-verify-doc'
X-Git-Tag: v1.8.3-rc0~110
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/7cd895e59e6a3322551b6c0b1cbe6b6aeb85f06e?ds=inline;hp=-c

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
---

7cd895e59e6a3322551b6c0b1cbe6b6aeb85f06e
diff --combined Documentation/git-rev-parse.txt
index 10a116faf8,757d195962..1f9ed6cfd2
--- a/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