Re: documentation issues
Chuck Lever <cel@citi.umich.edu> writes:
> in the man page for git-diff-index (posted here):
>
> http://www.kernel.org/pub/software/scm/git/docs/git-diff-tree.html
You mean git-diff-index.html, not diff-tree.html, I suppose.
> there are several references to "git-diff-tree" where it seems like
> "git-diff-index" is really meant.
Non-cached Mode
---------------
The "non-cached" mode takes a different approach, and is potentially
the more useful of the two in that what it does can't be emulated with
a "git-write-tree" + "git-diff-tree". Thus that's the default mode.
...
The non-cached version asks the question: show me the differences between HEAD and the currently checked out
tree - index contents _and_ files that aren't up-to-date which is obviously a very useful question too, since that tells you what
you *could* commit. Again, the output matches the "git-diff-tree -r"
output to a tee, but with a twist.Linus does mean diff-tree here.
We had diff-files and diff-tree back then, but diff-index came much later under the name diff-cache. He is explaining what git-diff-index does in terms of git-diff-tree in this paragraph.
He could have said:
You *could* emulate it with first copying the index file
into a temporary file, git-update-index all the modified
paths in the working tree into that temporary index file and
git-write-tree that, and then run git-diff-tree.but that is not practical.
> also, git-diff-index supports a "-r" option, but that doesn't seem to be
> documented on this page.
What Chris Shoemaker said is right.
But we could do this instead if you want. I am neutral myself.
-- >8 -- [PATCH] Documentation: mention -r for all commands from the diff family.
We did not mention 'git-diff-index' and friends take '-r' but silently ignore it, because they always operate on the whole tree.
Signed-off-by: Junio C Hamano <junkio@cox.net>
---
diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
index 6b496ed..7299903 100644
--- a/Documentation/diff-options.txt
+++ b/Documentation/diff-options.txt
@@ -58,5 +58,11 @@
Swap two inputs; that is, show differences from index or
on-disk file to tree contents.
+-r::
+ Recurse into sub-trees. Note that this makes difference
+ only with `git-diff-tree`. Other commands in the `git-diff-\*`
+ family always operate on the whole project tree and this
+ option is a no-op to them.
+
For more detailed explanation on these common options, see also
link:diffcore.html[diffcore documentation].
diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt
index 9a2947e..8f66119 100644
--- a/Documentation/git-diff-tree.txt
+++ b/Documentation/git-diff-tree.txt
@@ -33,9 +33,6 @@ include::diff-options.txt[]
Note that this parameter does not provide any wildcard or regexp
features.
--r::
- recurse into sub-trees
-
-t::
show tree entry itself as well as subtrees. Implies -r.
