Re: [PATCH 3/8] docs: use <sha1> to mean unabbreviated ID

[Jonathan Nieder <jrnieder@gmail.com>]

Mark Lodato wrote:

> There are some places that literally require a full, 40-character SHA-1
> ID, rather than a generic revision specifier.

One name I have seen for these is "object IDs", as in git get-tar-commit-id
(to avoid putting too much emphasis on precisely how the identifiers are
chosen).

>                                   Use <sha1> in git-diff-tree(1) to note
> that --stdin only takes <sha1>s, not generic <tree>s or <commit>s.

In this example, maybe it would be cleanest to spell out "40-digit
object identifier".

Perhaps something like this?  (The text is more verbose than I'd
like and it would be nicer to include an example, though.)

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index a7e37b8..85ce185 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -49,9 +49,11 @@ include::diff-options.txt[]
 --stdin::
 	When '--stdin' is specified, the command does not take
 	<tree-ish> arguments from the command line.  Instead, it
-	reads lines containing either two <tree>, one <commit>, or a
-	list of <commit> from its standard input.  (Use a single space
-	as separator.)
+	reads lines, each naming two trees, one commit, or multiple
+	commits, from its standard input.  Each line consists of a
+	list of full 40-digit object identifiers with a single space
+	as separator.  Objects must be named directly; for example,
+	a tag ID cannot be used to represent a commit.
 +
 When two trees are given, it compares the first tree with the second.
 When a single commit is given, it compares the commit with its