documentation issues

documentation issues

[Chuck Lever]

[-- Attachment #1: Type: text/plain, Size: 393 bytes --]

i'd fix these myself, but i don't know what the right answers are.

in the man page for git-diff-index (posted here):

   http://www.kernel.org/pub/software/scm/git/docs/git-diff-tree.html

there are several references to "git-diff-tree" where it seems like 
"git-diff-index" is really meant.

also, git-diff-index supports a "-r" option, but that doesn't seem to be 
documented on this page.

[-- Attachment #2: cel.vcf --]
[-- Type: text/x-vcard, Size: 445 bytes --]

begin:vcard
fn:Chuck Lever
n:Lever;Charles
org:Network Appliance, Incorporated;Open Source NFS Client Development
adr:535 West William Street, Suite 3100;;Center for Information Technology Integration;Ann Arbor;MI;48103-4943;USA
email;internet:cel@citi.umich.edu
title:Member of Technical Staff
tel;work:+1 734 763 4415
tel;fax:+1 734 763 4434
tel;home:+1 734 668 1089
x-mozilla-html:FALSE
url:http://www.monkey.org/~cel/
version:2.1
end:vcard

Re: documentation issues

[Chris Shoemaker]

On Thu, Dec 01, 2005 at 03:28:53PM -0500, Chuck Lever wrote:
> also, git-diff-index supports a "-r" option, but that doesn't seem to be 
> documented on this page.

I think it is "supported" in the sense that git-diff-index won't
complain about "-r" argument, but it doesn't actually do anything, so
it shouldn't be documented.

-chris

Re: documentation issues

[Junio C Hamano]

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.
 

Re: documentation issues

[Chris Shoemaker]

On Thu, Dec 01, 2005 at 01:34:55PM -0800, Junio C Hamano wrote:
> > 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.

I think it is more clear without this, since we imply elsewhere that
diff-* accepts the options in diff-options.txt.  Documenting "-r" in
the only place it applies (diff-tree) means we don't need exceptions
anywhere else.

Incidentally, I think it would make more sense if diff-tree defaulted
to recursive behavior and required a flag to produce non-recursive
behavior, but I realize that's impractical now, and only of minor
benefit.

-chris

Re: documentation issues

[Chuck Lever]

[-- Attachment #1: Type: text/plain, Size: 358 bytes --]

Junio C Hamano wrote:
>>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.

thanks for clarifying.

StGIT does use "git-diff-index -r" in git.__tree_status().  i think it 
can be safely removed.

[-- Attachment #2: cel.vcf --]
[-- Type: text/x-vcard, Size: 445 bytes --]

begin:vcard
fn:Chuck Lever
n:Lever;Charles
org:Network Appliance, Incorporated;Open Source NFS Client Development
adr:535 West William Street, Suite 3100;;Center for Information Technology Integration;Ann Arbor;MI;48103-4943;USA
email;internet:cel@citi.umich.edu
title:Member of Technical Staff
tel;work:+1 734 763 4415
tel;fax:+1 734 763 4434
tel;home:+1 734 668 1089
x-mozilla-html:FALSE
url:http://www.monkey.org/~cel/
version:2.1
end:vcard