# documentation issues 5 messages from 2005-12-01 to 2005-12-01. Participants: Chuck Lever, Chris Shoemaker, Junio C Hamano. Thread: https://gitlist.dev/t/2726 ## Chuck Lever, 2005-12-01 20:28 Subject: documentation issues Message-ID: <438F5D05.4080101@citi.umich.edu> URL: https://gitlist.dev/e/438F5D05.4080101%40citi.umich.edu ``` 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. 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 ``` ## Chris Shoemaker, 2005-12-01 20:34 Subject: Re: documentation issues Message-ID: <20051201203411.GA12861@pe.Belkin> URL: https://gitlist.dev/e/20051201203411.GA12861%40pe.Belkin In-Reply-To: <438F5D05.4080101@citi.umich.edu> ``` 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 ``` ## Junio C Hamano, 2005-12-01 21:34 Subject: Re: documentation issues Message-ID: <7v64q8fqm8.fsf@assigned-by-dhcp.cox.net> URL: https://gitlist.dev/e/7v64q8fqm8.fsf%40assigned-by-dhcp.cox.net In-Reply-To: <438F5D05.4080101@citi.umich.edu> ``` Chuck Lever 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 --- 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. ``` ## Chris Shoemaker, 2005-12-01 21:54 Subject: Re: documentation issues Message-ID: <20051201215424.GA13016@pe.Belkin> URL: https://gitlist.dev/e/20051201215424.GA13016%40pe.Belkin In-Reply-To: <7v64q8fqm8.fsf@assigned-by-dhcp.cox.net> ``` 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 ``` ## Chuck Lever, 2005-12-01 22:06 Subject: Re: documentation issues Message-ID: <438F73DD.2000203@citi.umich.edu> URL: https://gitlist.dev/e/438F73DD.2000203%40citi.umich.edu In-Reply-To: <7v64q8fqm8.fsf@assigned-by-dhcp.cox.net> ``` 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. 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 ```