{"thread":{"id":"26312","subject":"Parameter --color-words not documented for \"git show\"","startedAt":"2011-01-20T19:58:34Z","lastAt":"2011-01-23T10:35:45Z","messageCount":14,"participants":["Sebastian Pipping","Thomas Rast","Junio C Hamano","Nicolas Sebrecht","Jeff King","Maaartin","Jakub Narebski"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"159706","messageId":"4D3893EA.5090907@hartwork.org","threadId":"26312","inReplyTo":null,"subject":"Parameter --color-words not documented for \"git show\"","fromName":"Sebastian Pipping","fromEmail":"webmaster@hartwork.org","sentAt":"2011-01-20T19:58:34Z","receivedAt":"2011-01-20T19:58:34Z","isPatch":false,"sender":{"key":"webmaster@hartwork.org","avatar":null},"body":"Hello,\n\n\nI noticed that\n\n git show --color-words\n\nworks just fine, but it's not listed in\n\n man git-show\n\nI am referring to this version:\n\n $ git --version\n git version 1.7.4.rc2\n\nThanks,\n\n\n\nSebastian\n"},{"id":"159709","messageId":"201101202127.39962.trast@student.ethz.ch","threadId":"26312","inReplyTo":"4D3893EA.5090907@hartwork.org","subject":"Re: Parameter --color-words not documented for \"git show\"","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2011-01-20T20:27:39Z","receivedAt":"2011-01-20T20:27:39Z","isPatch":false,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Sebastian Pipping wrote:\n> \n> I noticed that\n> \n> git show --color-words\n> \n> works just fine, but it's not listed in\n> \n> man git-show\n\nQuote from the latter:\n\n This manual page describes only the most frequently used options.\n\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"159712","messageId":"4D389E69.608@hartwork.org","threadId":"26312","inReplyTo":"201101202127.39962.trast@student.ethz.ch","subject":"Re: Parameter --color-words not documented for \"git show\"","fromName":"Sebastian Pipping","fromEmail":"webmaster@hartwork.org","sentAt":"2011-01-20T20:43:21Z","receivedAt":"2011-01-20T20:43:21Z","isPatch":false,"sender":{"key":"webmaster@hartwork.org","avatar":null},"body":"On 01/20/11 21:27, Thomas Rast wrote:\n> Quote from the latter:\n> \n> This manual page describes only the most frequently used options.\n\nOkay. Is that a good a idea? Is --abbrev-commit really used more\nfrequently with \"git show\" than --color-words is?\n\n\n\nSebastian\n"},{"id":"159716","messageId":"7vk4hzqnbx.fsf@alter.siamese.dyndns.org","threadId":"26312","inReplyTo":"4D389E69.608@hartwork.org","subject":"Re: Parameter --color-words not documented for \"git show\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-01-20T21:25:54Z","receivedAt":"2011-01-20T21:25:54Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sebastian Pipping writes:\n\n> On 01/20/11 21:27, Thomas Rast wrote:\n>> Quote from the latter:\n>> \n>> This manual page describes only the most frequently used options.\n>\n> Okay. Is that a good a idea?\n\nYes; the alternative is to list everything.\n\n> Is --abbrev-commit really used more\n> frequently with \"git show\" than --color-words is?\n\nI see this as a not-so-helpful-but-still-interesting question.\n\nIt depends on who you are, and if one wants to pick the most often used\nones, that selection may or may not coincide with _your_ usage pattern nor\nmine. The original author apparently thought so, you seem to think\ncolor-words is used a lot more often, and I personally think neither is\nused often at all. So should we swap them, keep things as-is, or remove\nboth?\n\nWe obviously cannot take a poll to update the list every time a new user\nstarts using git, but it might make sense to review them every once in a\nwhile.\n"},{"id":"159720","messageId":"20110120231649.GC14184@vidovic","threadId":"26312","inReplyTo":"7vk4hzqnbx.fsf@alter.siamese.dyndns.org","subject":"Re: Parameter --color-words not documented for \"git show\"","fromName":"Nicolas Sebrecht","fromEmail":"nicolas.s.dev@gmx.fr","sentAt":"2011-01-20T23:16:49Z","receivedAt":"2011-01-20T23:16:49Z","isPatch":false,"sender":{"key":"nicolas.s.dev@gmx.fr","avatar":null},"body":"The 20/01/11, Junio C Hamano wrote:\n> Sebastian Pipping writes:\n> \n> > On 01/20/11 21:27, Thomas Rast wrote:\n> >> Quote from the latter:\n> >> \n> >> This manual page describes only the most frequently used options.\n> >\n> > Okay. Is that a good a idea?\n> \n> Yes; the alternative is to list everything.\n\nWould it be bad? I tend to think that a manual page is the good place to\nlist everything the program accepts as parameters and how to use them.\nFMHO, Manual page is not where newcomers look to learn but it should\nhelp everybody to find and understand all of the available options.\n\n-- \nNicolas Sebrecht\n"},{"id":"159722","messageId":"20110120233429.GB9442@sigill.intra.peff.net","threadId":"26312","inReplyTo":"20110120231649.GC14184@vidovic","subject":"Re: Parameter --color-words not documented for \"git show\"","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2011-01-20T23:34:29Z","receivedAt":"2011-01-20T23:34:29Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Jan 21, 2011 at 12:16:49AM +0100, Nicolas Sebrecht wrote:\n\n> The 20/01/11, Junio C Hamano wrote:\n> > Sebastian Pipping writes:\n> > \n> > > On 01/20/11 21:27, Thomas Rast wrote:\n> > >> Quote from the latter:\n> > >> \n> > >> This manual page describes only the most frequently used options.\n> > >\n> > > Okay. Is that a good a idea?\n> > \n> > Yes; the alternative is to list everything.\n> \n> Would it be bad? I tend to think that a manual page is the good place to\n> list everything the program accepts as parameters and how to use them.\n> FMHO, Manual page is not where newcomers look to learn but it should\n> help everybody to find and understand all of the available options.\n\nThe problem is that we have a bazillion diff options that appear in many\nmanpages, so you are stuck with one of:\n\n 1. repeat them all in each manpage (usually via some automagic\n include), which dwarfs the original content, and makes it hard for\n users to see subtle differences between commands\n\n 2. Say \"this describes only the most frequently used options\", which\n leaves the user wondering which infrequently used options exist.\n\n 3. Say \"we also take diff options, and you can find out more about\n diff options in git-diff(1).\" This at least points the user in the\n right direction, but you can't search for \"--color-words\" in the\n page.\n\n 4. Do (3), but also list the all (or common) diff options in a succint\n list without descriptions, and refer the user to git-diff(1). Then\n they can grep if they like, and while they won't get the immediate\n answer, they will get referred to the right place.\n\nAs you can probably guess, I favor option (4), though we already do (3)\nin some places.\n\n-Peff\n"},{"id":"159725","messageId":"4D38CDC4.6010803@hartwork.org","threadId":"26312","inReplyTo":"20110120233429.GB9442@sigill.intra.peff.net","subject":"Re: Parameter --color-words not documented for \"git show\"","fromName":"Sebastian Pipping","fromEmail":"webmaster@hartwork.org","sentAt":"2011-01-21T00:05:24Z","receivedAt":"2011-01-21T00:05:24Z","isPatch":false,"sender":{"key":"webmaster@hartwork.org","avatar":null},"body":"On 01/21/11 00:34, Jeff King wrote:\n>>> Yes; the alternative is to list everything.\n>>\n>> Would it be bad? I tend to think that a manual page is the good place to\n>> list everything the program accepts as parameters and how to use them.\n>> FMHO, Manual page is not where newcomers look to learn but it should\n>> help everybody to find and understand all of the available options.\n> \n> The problem is that we have a bazillion diff options that appear in many\n> manpages, so you are stuck with one of:\n> \n> 1. repeat them all in each manpage (usually via some automagic\n> include), which dwarfs the original content, and makes it hard for\n> users to see subtle differences between commands\n> \n> 2. Say \"this describes only the most frequently used options\", which\n> leaves the user wondering which infrequently used options exist.\n> \n> 3. Say \"we also take diff options, and you can find out more about\n> diff options in git-diff(1).\" This at least points the user in the\n> right direction, but you can't search for \"--color-words\" in the\n> page.\n> \n> 4. Do (3), but also list the all (or common) diff options in a succint\n> list without descriptions, and refer the user to git-diff(1). Then\n> they can grep if they like, and while they won't get the immediate\n> answer, they will get referred to the right place.\n> \n> As you can probably guess, I favor option (4), though we already do (3)\n> in some places.\n\nI agree with Thomas here. (1) is the only option I find acceptable,\npersonally. If you'd rather not do that, then at least know I now.\nGreat to have --color-words around btw.\n\nBest,\n\n\n\nSebastian\n"},{"id":"159727","messageId":"20110121002020.GA7874@sigill.intra.peff.net","threadId":"26312","inReplyTo":"4D38CDC4.6010803@hartwork.org","subject":"Re: Parameter --color-words not documented for \"git show\"","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2011-01-21T00:20:20Z","receivedAt":"2011-01-21T00:20:20Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Jan 21, 2011 at 01:05:24AM +0100, Sebastian Pipping wrote:\n\n> > The problem is that we have a bazillion diff options that appear in many\n> > manpages, so you are stuck with one of:\n> > \n> > 1. repeat them all in each manpage (usually via some automagic\n> > include), which dwarfs the original content, and makes it hard for\n> > users to see subtle differences between commands\n> > \n> > 2. Say \"this describes only the most frequently used options\", which\n> > leaves the user wondering which infrequently used options exist.\n> > \n> > 3. Say \"we also take diff options, and you can find out more about\n> > diff options in git-diff(1).\" This at least points the user in the\n> > right direction, but you can't search for \"--color-words\" in the\n> > page.\n> > \n> > 4. Do (3), but also list the all (or common) diff options in a succint\n> > list without descriptions, and refer the user to git-diff(1). Then\n> > they can grep if they like, and while they won't get the immediate\n> > answer, they will get referred to the right place.\n> > \n> > As you can probably guess, I favor option (4), though we already do (3)\n> > in some places.\n> \n> I agree with Thomas here. (1) is the only option I find acceptable,\n> personally. If you'd rather not do that, then at least know I now.\n> Great to have --color-words around btw.\n\nI'm curious why (4) doesn't work for you. I assumed you came to the\nproblem by one of:\n\n - you wanted to know which options \"git show\" had, so you looked in\n the manpage. Nothing told you about \"--color-words\", nor referred\n you to a list of diff options. With (4), you would find that it\n accepted all diff options, and then go read the list of diff options\n (if you weren't already familiar with it).\n\n - you knew about --color-words, and wondered if \"git show\" supported\n it. In the current case, searching the page turns up nothing. In\n option (4), a search would find it (with a reference to diff options\n if you wanted more details).\n\nThe downside is that you sometimes have to be referred. The upside to me\nis that it becomes explicit that there is a concept of \"diff options\"\nthat you can look up easily and which we can refer to easily in other\nparts of the manual. That helps establish a mental model of how git's\noptions work.\n\nSo is it just that being referred is annoying, or something else?\n\n-Peff\n"},{"id":"159729","messageId":"4D38D30A.3040707@hartwork.org","threadId":"26312","inReplyTo":"20110121002020.GA7874@sigill.intra.peff.net","subject":"Re: Parameter --color-words not documented for \"git show\"","fromName":"Sebastian Pipping","fromEmail":"webmaster@hartwork.org","sentAt":"2011-01-21T00:27:54Z","receivedAt":"2011-01-21T00:27:54Z","isPatch":false,"sender":{"key":"webmaster@hartwork.org","avatar":null},"body":"On 01/21/11 01:20, Jeff King wrote:\n>> I agree with Thomas here. (1) is the only option I find acceptable,\n>> personally. If you'd rather not do that, then at least know I now.\n>> Great to have --color-words around btw.\n> \n> I'm curious why (4) doesn't work for you. I assumed you came to the\n> problem by one of:\n> \n> - you wanted to know which options \"git show\" had, so you looked in\n> the manpage. Nothing told you about \"--color-words\", nor referred\n> you to a list of diff options. With (4), you would find that it\n> accepted all diff options, and then go read the list of diff options\n> (if you weren't already familiar with it).\n> \n> - you knew about --color-words, and wondered if \"git show\" supported\n> it. In the current case, searching the page turns up nothing. In\n> option (4), a search would find it (with a reference to diff options\n> if you wanted more details).\n> \n> The downside is that you sometimes have to be referred. The upside to me\n> is that it becomes explicit that there is a concept of \"diff options\"\n> that you can look up easily and which we can refer to easily in other\n> parts of the manual. That helps establish a mental model of how git's\n> options work.\n> \n> So is it just that being referred is annoying, or something else?\n\nActually that approach is perfect. I misunderstood (4) on the first\nread somehow. Really not my day today, sorry. I would love to see you\npush (4) forward.\n\nBest,\n\n\n\nSebastian\n"},{"id":"159731","messageId":"7vy66epz4r.fsf@alter.siamese.dyndns.org","threadId":"26312","inReplyTo":"20110120233429.GB9442@sigill.intra.peff.net","subject":"Re: Parameter --color-words not documented for \"git show\"","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-01-21T06:08:36Z","receivedAt":"2011-01-21T06:08:36Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> The problem is that we have a bazillion diff options that appear in many\n> manpages, so you are stuck with one of:\n>\n> 1. repeat them all in each manpage (usually via some automagic\n> include), which dwarfs the original content, and makes it hard for\n> users to see subtle differences between commands\n>\n> 2. Say \"this describes only the most frequently used options\", which\n> leaves the user wondering which infrequently used options exist.\n>\n> 3. Say \"we also take diff options, and you can find out more about\n> diff options in git-diff(1).\" This at least points the user in the\n> right direction, but you can't search for \"--color-words\" in the\n> page.\n>\n> 4. Do (3), but also list the all (or common) diff options in a succint\n> list without descriptions, and refer the user to git-diff(1). Then\n> they can grep if they like, and while they won't get the immediate\n> answer, they will get referred to the right place.\n>\n> As you can probably guess, I favor option (4), though we already do (3)\n> in some places.\n\nWe attempt to do 1 to solve it \"nicely\" in some manual pages, and indeed\nthere are many \"exclude this option from the command X's manpage\" magic\nthat causes the problem of subtle differences you mentioned (which I\nagree).\n\nOne complication in either 3 or 4 is that they sometimes need to be\naccompanied with \"... except these diff options do not make sense in the\ncontext of this command, so they are no-op\". That is probably a price\nworth paying to be more helpful than 2 is.\n"},{"id":"159738","messageId":"4D395B15.2040406@seznam.cz","threadId":"26312","inReplyTo":"20110120233429.GB9442@sigill.intra.peff.net","subject":"Re: Parameter --color-words not documented for \"git show\"","fromName":"Maaartin","fromEmail":"grajcar1@seznam.cz","sentAt":"2011-01-21T10:08:21Z","receivedAt":"2011-01-21T10:08:21Z","isPatch":false,"sender":{"key":"grajcar1@seznam.cz","avatar":null},"body":"On 11-01-21 00:34, Jeff King wrote:\n> On Fri, Jan 21, 2011 at 12:16:49AM +0100, Nicolas Sebrecht wrote:\n\n> 4. Do (3), but also list the all (or common) diff options in a succint\n> list without descriptions, and refer the user to git-diff(1). Then\n> they can grep if they like, and while they won't get the immediate\n> answer, they will get referred to the right place.\n> \n> As you can probably guess, I favor option (4), though we already do (3)\n> in some places.\n\nI also favor (4), for the following reasons:\n\n- sometimes you want to read the whole manpage, e.g., it's good for\nbeginners to get feeling what is it all about.\n\n- repeated information makes the page too long and reading too boring.\n\n- too long manpages may scare beginners.\n\nMaybe there could be sort-of extended manpage, containing everything,\nbut it would need some markup beyond the capabilities of a terminal (a\ngrayed or collapsed area in html, or whatever). However, this could be a\nlot of additional work, and I don't claim it should be done, just an idea.\n"},{"id":"159754","messageId":"20110121161646.GA21840@sigill.intra.peff.net","threadId":"26312","inReplyTo":"7vy66epz4r.fsf@alter.siamese.dyndns.org","subject":"Re: Parameter --color-words not documented for \"git show\"","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2011-01-21T16:16:46Z","receivedAt":"2011-01-21T16:16:46Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Jan 20, 2011 at 10:08:36PM -0800, Junio C Hamano wrote:\n\n> > 3. Say \"we also take diff options, and you can find out more about\n> > diff options in git-diff(1).\" This at least points the user in the\n> > right direction, but you can't search for \"--color-words\" in the\n> > page.\n> >\n> > 4. Do (3), but also list the all (or common) diff options in a succint\n> > list without descriptions, and refer the user to git-diff(1). Then\n> > they can grep if they like, and while they won't get the immediate\n> > answer, they will get referred to the right place.\n> [...]\n> One complication in either 3 or 4 is that they sometimes need to be\n> accompanied with \"... except these diff options do not make sense in the\n> context of this command, so they are no-op\". That is probably a price\n> worth paying to be more helpful than 2 is.\n\nYeah, I took a quick look at diff-options.txt. I think many of those\nspecial cases can be handled by just mentioning the exceptions in the\ntext. They are usually simple and obvious special cases, like \"for -M,\nif you are in a command which is traversing, you might be interested in\n--follow\". I don't think it will hurt people to read that, even if they\nare looking at the diff-options because they want to know about \"git\ndiff\".\n\nI'll this to my documentation cleanup todo list. It's lower priority\nthan many other things, but believe it or not I am working towards it.\n:)\n\n-Peff\n"},{"id":"159755","messageId":"20110121161737.GB21840@sigill.intra.peff.net","threadId":"26312","inReplyTo":"4D395B15.2040406@seznam.cz","subject":"Re: Parameter --color-words not documented for \"git show\"","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2011-01-21T16:17:37Z","receivedAt":"2011-01-21T16:17:37Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Jan 21, 2011 at 11:08:21AM +0100, Maaartin wrote:\n\n> Maybe there could be sort-of extended manpage, containing everything,\n> but it would need some markup beyond the capabilities of a terminal (a\n> grayed or collapsed area in html, or whatever). However, this could be a\n> lot of additional work, and I don't claim it should be done, just an idea.\n\nYeah, that would be nice, but it is beyond the manpage format. For HTML\nversions, we can (and will) hyperlink, which at least makes following\nthe reference easy to do.\n\n-Peff\n"},{"id":"159797","messageId":"m38vybc3id.fsf@localhost.localdomain","threadId":"26312","inReplyTo":"7vk4hzqnbx.fsf@alter.siamese.dyndns.org","subject":"Re: Parameter --color-words not documented for \"git show\"","fromName":"Jakub Narebski","fromEmail":"jnareb@gmail.com","sentAt":"2011-01-23T10:35:45Z","receivedAt":"2011-01-23T10:35:45Z","isPatch":false,"sender":{"key":"jnareb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2706?v=4"},"body":"Junio C Hamano writes:\n> Sebastian Pipping writes:\n>> On 01/20/11 21:27, Thomas Rast wrote:\n>>> Quote from the latter:\n>>> \n>>> This manual page describes only the most frequently used options.\n>>\n>> Okay. Is that a good a idea?\n> \n> Yes; the alternative is to list everything.\n> \n>> Is --abbrev-commit really used more\n>> frequently with \"git show\" than --color-words is?\n> \n> I see this as a not-so-helpful-but-still-interesting question.\n> \n> It depends on who you are, and if one wants to pick the most often used\n> ones, that selection may or may not coincide with _your_ usage pattern nor\n> mine. The original author apparently thought so, you seem to think\n> color-words is used a lot more often, and I personally think neither is\n> used often at all. So should we swap them, keep things as-is, or remove\n> both?\n> \n> We obviously cannot take a poll to update the list every time a new user\n> starts using git, but it might make sense to review them every once in a\n> while.\n\nThere is also additional problem, namely that because \"git show\" shows\ncommit and can show diff, therefore it accepts same formatting options\nas \"git log\", and when set to display patch it accepts any diff family\noptions.\n\nShould we then list most common porcelanish diff options, or just\nrefer to git-diff(1) manpage?\n\n-- \nJakub Narebski\nPoland\nShadeHawk on #git\n"}]}