[PATCH 1/4] rev-parse: deprecate use as an option sifter

[Michael J Gruber <git@drmicha.warpmail.net>]

This command used to be used to distinguish between parameters meant
for rev-list and others, but this is deprectated now, and one should not
rely on rev-parse keeping up to date with rev-list. State this in the
man page and reword the title according to the primary use (converting
symbolic names to SHA1's).

Reference: <http://permalink.gmane.org/gmane.comp.version-control.git/146118>

Signed-off-by: Michael J Gruber <git@drmicha.warpmail.net>
---
 Documentation/git-rev-parse.txt |   14 ++++++++++----
 1 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 8db600f..99d2a79 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -3,7 +3,7 @@ git-rev-parse(1)
 
 NAME
 ----
-git-rev-parse - Pick out and massage parameters
+git-rev-parse - Parse symbolic names into object names
 
 
 SYNOPSIS
@@ -13,12 +13,18 @@ SYNOPSIS
 DESCRIPTION
 -----------
 
-Many git porcelainish commands take mixture of flags
+The primary use of 'git rev-parse' is to turn symbolic object names into
+40-letter object names ("SHA-1").
+
+Also, many git porcelainish commands take a 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
-downstream of 'git rev-list'.  This command is used to
-distinguish between them.
+downstream of 'git rev-list'.  This command used to be used to
+distinguish between them, but this is deprectated now, and you should
+not expect 'git rev-parse' to keep up to date with newer parameters for
+'git rev-list'. You can use linkgit:git-rev-list[1] directly or
+linkgit:git-for-each-ref[1] for scripting.
 
 
 OPTIONS
-- 
1.7.1.240.geeaa4d