From: Mark Lodato <lodatom@gmail.com>
Date: Sat, 13 Mar 2010 04:52:58 GMT
Subject: [PATCH/RFC 06/12] docs: clarify <object>, <commit>, <tree-ish>, etc
Message-ID: <1268455984-19061-7-git-send-email-lodatom@gmail.com>
In-Reply-To: <1268455984-19061-1-git-send-email-lodatom@gmail.com>

In git(1), give more precise definitions of <object>, <commit>,
<tree-ish>, and so on.  In particular, differentiate <object> (which may
take generic revision specifiers) from <sha1>, which only accepts
a 40-character hex SHA-1 ID.

Also note that <rev> is another way to say <commit-ish>.

Signed-off-by: Mark Lodato <lodatom@gmail.com>
---
 Documentation/git.txt |   38 +++++++++++++++++++++-----------------
 1 files changed, 21 insertions(+), 17 deletions(-)

diff --git a/Documentation/git.txt b/Documentation/git.txt
index f06e4de..55f3842 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -418,32 +418,36 @@ Identifier Terminology
 	Abbreviated or symbolic identifiers cannot be used.
 
 <object>::
-	Indicates the object name for any type of object.
+	Indicates the object name for any type of object.  Symbolic name or
+	abbreviated SHA-1 identifiers may be used (see "SPECIFYING REVISIONS"
+	in linkgit:git-rev-parse[1] for details).
 
 <tag>::
-	Indicates a tag object name.  This is an annotated tag object, as
+	Indicates a tag-type <object>.  This is an annotated tag object, as
 	opposed to <tagname>, which can refer to any type of object.
 
-<blob>::
-	Indicates a blob object name.
+<commit>::
+	Indicates a commit-type <object>.
 
 <tree>::
-	Indicates a tree object name.
-
-<commit>::
-	Indicates a commit object name.
+	Indicates a tree-type <object>.
 
-<tree-ish>::
-	Indicates a tree, commit or tag object name.  A
-	command that takes a <tree-ish> argument ultimately wants to
-	operate on a <tree> object but automatically dereferences
-	<commit> and <tag> objects that point at a <tree>.
+<blob>::
+	Indicates a blob-type <object>.
 
+<rev>::
 <commit-ish>::
-	Indicates a commit or tag object name.  A
-	command that takes a <commit-ish> argument ultimately wants to
-	operate on a <commit> object but automatically dereferences
-	<tag> objects that point at a <commit>.
+	Indicates a <commit>, or a <tag> that points at a <commit-ish>.
+	A command that takes a <commit-ish> argument ultimately wants to
+	operate on a commit object but automatically dereferences objects
+	until it finds a commit.
+	A <rev> is another name for a <commit-ish>.
+
+<tree-ish>::
+	Indicates a <tree>, or a <tag> or <commit> that points at a
+	<tree-ish>.  A command that takes a <tree-ish> argument ultimately
+	wants to operate on a tree object but automatically dereferences
+	objects until it finds a tree.
 
 <type>::
 	Indicates that an object type is required.
-- 
1.7.0.2