{"thread":{"id":"2726","subject":"documentation issues","startedAt":"2005-12-01T20:28:53Z","lastAt":"2005-12-01T22:06:21Z","messageCount":5,"participants":["Chuck Lever","Chris Shoemaker","Junio C Hamano"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"13058","messageId":"438F5D05.4080101@citi.umich.edu","threadId":"2726","inReplyTo":null,"subject":"documentation issues","fromName":"Chuck Lever","fromEmail":"cel@citi.umich.edu","sentAt":"2005-12-01T20:28:53Z","receivedAt":"2005-12-01T20:28:53Z","isPatch":false,"sender":{"key":"cel@citi.umich.edu","avatar":null},"body":"i'd fix these myself, but i don't know what the right answers are.\n\nin the man page for git-diff-index (posted here):\n\n http://www.kernel.org/pub/software/scm/git/docs/git-diff-tree.html\n\nthere are several references to \"git-diff-tree\" where it seems like \n\"git-diff-index\" is really meant.\n\nalso, git-diff-index supports a \"-r\" option, but that doesn't seem to be \ndocumented on this page.\n\n\nbegin:vcard\nfn:Chuck Lever\nn:Lever;Charles\norg:Network Appliance, Incorporated;Open Source NFS Client Development\nadr:535 West William Street, Suite 3100;;Center for Information Technology Integration;Ann Arbor;MI;48103-4943;USA\nemail;internet:cel@citi.umich.edu\ntitle:Member of Technical Staff\ntel;work:+1 734 763 4415\ntel;fax:+1 734 763 4434\ntel;home:+1 734 668 1089\nx-mozilla-html:FALSE\nurl:http://www.monkey.org/~cel/\nversion:2.1\nend:vcard\n\n"},{"id":"13060","messageId":"20051201203411.GA12861@pe.Belkin","threadId":"2726","inReplyTo":"438F5D05.4080101@citi.umich.edu","subject":"Re: documentation issues","fromName":"Chris Shoemaker","fromEmail":"c.shoemaker@cox.net","sentAt":"2005-12-01T20:34:11Z","receivedAt":"2005-12-01T20:34:11Z","isPatch":false,"sender":{"key":"c.shoemaker@cox.net","avatar":null},"body":"On Thu, Dec 01, 2005 at 03:28:53PM -0500, Chuck Lever wrote:\n> also, git-diff-index supports a \"-r\" option, but that doesn't seem to be \n> documented on this page.\n\nI think it is \"supported\" in the sense that git-diff-index won't\ncomplain about \"-r\" argument, but it doesn't actually do anything, so\nit shouldn't be documented.\n\n-chris\n"},{"id":"13064","messageId":"7v64q8fqm8.fsf@assigned-by-dhcp.cox.net","threadId":"2726","inReplyTo":"438F5D05.4080101@citi.umich.edu","subject":"Re: documentation issues","fromName":"Junio C Hamano","fromEmail":"junkio@cox.net","sentAt":"2005-12-01T21:34:55Z","receivedAt":"2005-12-01T21:34:55Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Chuck Lever writes:\n\n> in the man page for git-diff-index (posted here):\n>\n> http://www.kernel.org/pub/software/scm/git/docs/git-diff-tree.html\n\nYou mean git-diff-index.html, not diff-tree.html, I suppose.\n\n> there are several references to \"git-diff-tree\" where it seems like \n> \"git-diff-index\" is really meant.\n\n Non-cached Mode\n ---------------\n The \"non-cached\" mode takes a different approach, and is potentially\n the more useful of the two in that what it does can't be emulated with\n a \"git-write-tree\" + \"git-diff-tree\". Thus that's the default mode.\n ...\n The non-cached version asks the question:\n\n show me the differences between HEAD and the currently checked out\n tree - index contents _and_ files that aren't up-to-date\n\n which is obviously a very useful question too, since that tells you what\n you *could* commit. Again, the output matches the \"git-diff-tree -r\"\n output to a tee, but with a twist.\n\nLinus does mean diff-tree here.\n\nWe had diff-files and diff-tree back then, but diff-index came\nmuch later under the name diff-cache. He is explaining what\ngit-diff-index does in terms of git-diff-tree in this paragraph.\n\nHe could have said:\n\n You *could* emulate it with first copying the index file\n into a temporary file, git-update-index all the modified\n paths in the working tree into that temporary index file and\n git-write-tree that, and then run git-diff-tree.\n\nbut that is not practical.\n\n> also, git-diff-index supports a \"-r\" option, but that doesn't seem to be \n> documented on this page.\n\nWhat Chris Shoemaker said is right.\n\nBut we could do this instead if you want. I am neutral myself.\n\n-- >8 --\n[PATCH] Documentation: mention -r for all commands from the diff family.\n\nWe did not mention 'git-diff-index' and friends take '-r' but\nsilently ignore it, because they always operate on the whole tree.\n\nSigned-off-by: Junio C Hamano \n\n---\ndiff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt\nindex 6b496ed..7299903 100644\n--- a/Documentation/diff-options.txt\n+++ b/Documentation/diff-options.txt\n@@ -58,5 +58,11 @@\n \tSwap two inputs; that is, show differences from index or\n \ton-disk file to tree contents.\n \n+-r::\n+ Recurse into sub-trees. Note that this makes difference\n+ only with `git-diff-tree`. Other commands in the `git-diff-\\*`\n+ family always operate on the whole project tree and this\n+ option is a no-op to them.\n+\n For more detailed explanation on these common options, see also\n link:diffcore.html[diffcore documentation].\ndiff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt\nindex 9a2947e..8f66119 100644\n--- a/Documentation/git-diff-tree.txt\n+++ b/Documentation/git-diff-tree.txt\n@@ -33,9 +33,6 @@ include::diff-options.txt[]\n \tNote that this parameter does not provide any wildcard or regexp\n \tfeatures.\n \n--r::\n- recurse into sub-trees\n-\n -t::\n \tshow tree entry itself as well as subtrees. Implies -r.\n \n"},{"id":"13067","messageId":"20051201215424.GA13016@pe.Belkin","threadId":"2726","inReplyTo":"7v64q8fqm8.fsf@assigned-by-dhcp.cox.net","subject":"Re: documentation issues","fromName":"Chris Shoemaker","fromEmail":"c.shoemaker@cox.net","sentAt":"2005-12-01T21:54:24Z","receivedAt":"2005-12-01T21:54:24Z","isPatch":false,"sender":{"key":"c.shoemaker@cox.net","avatar":null},"body":"On Thu, Dec 01, 2005 at 01:34:55PM -0800, Junio C Hamano wrote:\n> > also, git-diff-index supports a \"-r\" option, but that doesn't seem to be \n> > documented on this page.\n> \n> What Chris Shoemaker said is right.\n> \n> But we could do this instead if you want. I am neutral myself.\n\nI think it is more clear without this, since we imply elsewhere that\ndiff-* accepts the options in diff-options.txt. Documenting \"-r\" in\nthe only place it applies (diff-tree) means we don't need exceptions\nanywhere else.\n\nIncidentally, I think it would make more sense if diff-tree defaulted\nto recursive behavior and required a flag to produce non-recursive\nbehavior, but I realize that's impractical now, and only of minor\nbenefit.\n\n-chris\n"},{"id":"13071","messageId":"438F73DD.2000203@citi.umich.edu","threadId":"2726","inReplyTo":"7v64q8fqm8.fsf@assigned-by-dhcp.cox.net","subject":"Re: documentation issues","fromName":"Chuck Lever","fromEmail":"cel@citi.umich.edu","sentAt":"2005-12-01T22:06:21Z","receivedAt":"2005-12-01T22:06:21Z","isPatch":false,"sender":{"key":"cel@citi.umich.edu","avatar":null},"body":"Junio C Hamano wrote:\n>>also, git-diff-index supports a \"-r\" option, but that doesn't seem to be \n>>documented on this page.\n> \n> \n> What Chris Shoemaker said is right.\n> \n> But we could do this instead if you want. I am neutral myself.\n\nthanks for clarifying.\n\nStGIT does use \"git-diff-index -r\" in git.__tree_status(). i think it \ncan be safely removed.\n\n\nbegin:vcard\nfn:Chuck Lever\nn:Lever;Charles\norg:Network Appliance, Incorporated;Open Source NFS Client Development\nadr:535 West William Street, Suite 3100;;Center for Information Technology Integration;Ann Arbor;MI;48103-4943;USA\nemail;internet:cel@citi.umich.edu\ntitle:Member of Technical Staff\ntel;work:+1 734 763 4415\ntel;fax:+1 734 763 4434\ntel;home:+1 734 668 1089\nx-mozilla-html:FALSE\nurl:http://www.monkey.org/~cel/\nversion:2.1\nend:vcard\n\n"}]}