--stdin::
When '--stdin' is specified, the command does not take
<tree-ish> arguments from the command line. Instead, it
- reads either one <commit> or a pair of <tree-ish>
- separated with a single space from its standard input.
+ reads lines containing either two <tree>, one <commit>, or a
+ list of <commit> from its standard input. (Use a single space
+ as separator.)
+
-When a single commit is given on one line of such input, it compares
-the commit with its parents. The following flags further affects its
-behavior. This does not apply to the case where two <tree-ish>
-separated with a single space are given.
+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
+parents. The remaining commits, when given, are used as if they are
+parents of the first commit.
++
+When comparing two trees, the ID of both trees (separated by a space
+and terminated by a newline) is printed before the difference. When
+comparing commits, the ID of the first (or only) commit, followed by a
+newline, is printed.
++
+The following flags further affects the behavior when comparing
+commits (but not trees).
-m::
By default, 'git-diff-tree --stdin' does not show