Re: documentation issues

From: Junio C Hamano <junkio@cox.net>
Date: Dec 1, 2005, 21:34 UTC
Message-ID: <7v64q8fqm8.fsf@assigned-by-dhcp.cox.net>
In-Reply-To: <438F5D05.4080101@citi.umich.edu>

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.