{"thread":{"id":"30711","subject":"[PATCH] Documentation: have ls-files and ls-tree \"see also\" each other","startedAt":"2012-06-05T05:10:37Z","lastAt":"2012-06-05T15:03:38Z","messageCount":4,"participants":["Matthew Ogilvie","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"192865","messageId":"1338873037-4343-1-git-send-email-mmogilvi_git@miniinfo.net","threadId":"30711","inReplyTo":null,"subject":"[PATCH] Documentation: have ls-files and ls-tree \"see also\" each other","fromName":"Matthew Ogilvie","fromEmail":"mmogilvi_git@miniinfo.net","sentAt":"2012-06-05T05:10:37Z","receivedAt":"2012-06-05T05:10:37Z","isPatch":true,"sender":{"key":"mmogilvi_git@miniinfo.net","avatar":null},"body":"Signed-off-by: Matthew Ogilvie <mmogilvi_git@miniinfo.net>\n---\n\nI could have used these references when I was looking at git-ls-files\ndocumentation and trying to figure out how to make it list files\nfrom a specific commit like git-ls-tree.\n\n(This is a resend.  I sent this patch a couple of weeks ago,\nbut it apparently slipped through the cracks.)\n\n Documentation/git-ls-files.txt |    2 +-\n Documentation/git-ls-tree.txt  |    4 ++++\n 2 files changed, 5 insertions(+), 1 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 4b28292..8ce3c3b 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -207,7 +207,7 @@ pattern file appears in.\n \n SEE ALSO\n --------\n-linkgit:git-read-tree[1], linkgit:gitignore[5]\n+linkgit:git-ls-tree[1], linkgit:git-read-tree[1], linkgit:gitignore[5]\n \n GIT\n ---\ndiff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt\nindex 16e87fd..1cd52cc 100644\n--- a/Documentation/git-ls-tree.txt\n+++ b/Documentation/git-ls-tree.txt\n@@ -95,6 +95,10 @@ Object size identified by <object> is given in bytes, and right-justified\n with minimum width of 7 characters.  Object size is given only for blobs\n (file) entries; for other entries `-` character is used in place of size.\n \n+SEE ALSO\n+--------\n+linkgit:git-ls-files[1]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\n-- \n"},{"id":"192867","messageId":"7vehpuqpob.fsf@alter.siamese.dyndns.org","threadId":"30711","inReplyTo":"1338873037-4343-1-git-send-email-mmogilvi_git@miniinfo.net","subject":"Re: [PATCH] Documentation: have ls-files and ls-tree \"see also\" each other","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-06-05T05:43:32Z","receivedAt":"2012-06-05T05:43:32Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthew Ogilvie <mmogilvi_git@miniinfo.net> writes:\n\n> Signed-off-by: Matthew Ogilvie <mmogilvi_git@miniinfo.net>\n> ---\n>\n> I could have used these references when I was looking at git-ls-files\n> documentation and trying to figure out how to make it list files\n> from a specific commit like git-ls-tree.\n\nI do not like this kind of patches in general.  Where will it end?\n\n\"I wanted to know how to list objects recorded in a commit, and I\ncould have used a reference to git-ls-tree from git-commit, so here\nis a patch to make them refer to each other\"?\n\nThat kind of overfiew is what the tutorial (for concepts like the\nindex, tree objects, commit objects, etc.) and the list of commands\nin git(1).  Is there compelling reason other than \"I didn't bother\nto look, and it is likely other people wouldn't\" to apply patches\nlike this?\n"},{"id":"192869","messageId":"20120605062935.GA4683@comcast.net","threadId":"30711","inReplyTo":"7vehpuqpob.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Documentation: have ls-files and ls-tree \"see also\" each other","fromName":"Matthew Ogilvie","fromEmail":"mmogilvi_git@miniinfo.net","sentAt":"2012-06-05T06:29:35Z","receivedAt":"2012-06-05T06:29:35Z","isPatch":true,"sender":{"key":"mmogilvi_git@miniinfo.net","avatar":null},"body":"On Mon, Jun 04, 2012 at 10:43:32PM -0700, Junio C Hamano wrote:\n> Matthew Ogilvie <mmogilvi_git@miniinfo.net> writes:\n> \n> > Signed-off-by: Matthew Ogilvie <mmogilvi_git@miniinfo.net>\n> > ---\n> >\n> > I could have used these references when I was looking at git-ls-files\n> > documentation and trying to figure out how to make it list files\n> > from a specific commit like git-ls-tree.\n> \n> I do not like this kind of patches in general.  Where will it end?\n> \n> \"I wanted to know how to list objects recorded in a commit, and I\n> could have used a reference to git-ls-tree from git-commit, so here\n> is a patch to make them refer to each other\"?\n> \n> That kind of overfiew is what the tutorial (for concepts like the\n> index, tree objects, commit objects, etc.) and the list of commands\n> in git(1).  Is there compelling reason other than \"I didn't bother\n> to look, and it is likely other people wouldn't\" to apply patches\n> like this?\n\nNot really.  Certainly this is a low priority change.\n\nBut why do many of the man pages have \"SEE ALSO\"\nsections?  Should we just get rid of such sections?  Does anyone\nhave any guidelines/rules for what makes sense to be in a\n\"SEE ALSO\" section?\n\nMy personal impression is that git-ls-files (which lists files\nin the working directory or index) and git-ls-tree (which lists files in\na commit or tree object) are so similar that they could almost be\nmerged into a single command.  Linking them together in the \ndocumentation seemed obvious, but maybe that's just me.\n"},{"id":"192910","messageId":"7v62b5reb9.fsf@alter.siamese.dyndns.org","threadId":"30711","inReplyTo":"20120605062935.GA4683@comcast.net","subject":"Re: [PATCH] Documentation: have ls-files and ls-tree \"see also\" each other","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-06-05T15:03:38Z","receivedAt":"2012-06-05T15:03:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matthew Ogilvie <mmogilvi_git@miniinfo.net> writes:\n\n> On Mon, Jun 04, 2012 at 10:43:32PM -0700, Junio C Hamano wrote:\n>> ...\n>> That kind of overfiew is what the tutorial (for concepts like the\n>> index, tree objects, commit objects, etc.) and the list of commands\n>> in git(1).  Is there compelling reason other than \"I didn't bother\n>> to look, and it is likely other people wouldn't\" to apply patches\n>> like this?\n>\n> Not really.  Certainly this is a low priority change.\n>\n> But why do many of the man pages have \"SEE ALSO\"\n> sections?  Should we just get rid of such sections?  Does anyone\n> have any guidelines/rules for what makes sense to be in a\n> \"SEE ALSO\" section?\n\nTwo questions that sound similar, somewhat related to each other,\nbut fundamentally different are [*1*]:\n\n - Does it help knowing B to make good use of A?\n\n - Do you need to know what is in the documentation for B in order\n   to understand what is in the documentation for A?\n\nIf the answer to either one is yes, it may be a good idea to have\n\"See also B\" in the documentation for A.\n\nThe ls-files and ls-tree pair does not pass either of the above two\ntests. They both give list of paths (but so do \"diff --name-only\"\nand other things), but the similarity between them stops there, and\nmore importantly, similarity does not play any role in the above two\ntests.\n\nIf we had a third test:\n\n - Does it help knowing B to avoid wasting time attempting to use A\n   for a task for which A is not a suitable tool?\n\nthen ls-files and ls-tree pair would qualify.  I however am not\nconvinced it is particularly a good test.\n\n\n[Footnote]\n\n*1* Note that the latter is a sign that A is described in terms of B\n(i.e. \"We assume you understand B; otherwise stop now, go there and\nlearn B, and come back. Now we will describe A\"); it is preferrable\nto avoid it if we can do so without duplication of the information\nat the source level.\n"}]}