Hello,
I noticed that
git show --color-words
works just fine, but it's not listed in
man git-show
I am referring to this version:
$ git --version git version 1.7.4.rc2
Thanks,
Sebastian
threads / discuss / 26312
Parameter --color-words not documented for "git show"
Subject: Parameter --color-words not documented for "git show"
Thomas RastRe: Parameter --color-words not documented for "git show"
Sebastian Pipping wrote:
Show 8 quoted lines
> > I noticed that > > git show --color-words > > works just fine, but it's not listed in > > man git-show
Quote from the latter:
This manual page describes only the most frequently used options.
--
Thomas Rast
trast@{inf,student}.ethz.chRe: Parameter --color-words not documented for "git show"
On 01/20/11 21:27, Thomas Rast wrote:
> Quote from the latter: > > This manual page describes only the most frequently used options.
Okay. Is that a good a idea? Is --abbrev-commit really used more frequently with "git show" than --color-words is?
Sebastian
Junio C HamanoRe: Parameter --color-words not documented for "git show"
Sebastian Pipping <webmaster@hartwork.org> writes:
Show 6 quoted lines
> On 01/20/11 21:27, Thomas Rast wrote: >> Quote from the latter: >> >> This manual page describes only the most frequently used options. > > Okay. Is that a good a idea?
Yes; the alternative is to list everything.
> Is --abbrev-commit really used more > frequently with "git show" than --color-words is?
I see this as a not-so-helpful-but-still-interesting question.
It depends on who you are, and if one wants to pick the most often used ones, that selection may or may not coincide with _your_ usage pattern nor mine. The original author apparently thought so, you seem to think color-words is used a lot more often, and I personally think neither is used often at all. So should we swap them, keep things as-is, or remove both?
We obviously cannot take a poll to update the list every time a new user starts using git, but it might make sense to review them every once in a while.
Re: Parameter --color-words not documented for "git show"
The 20/01/11, Junio C Hamano wrote:
Show 10 quoted lines
> Sebastian Pipping <webmaster@hartwork.org> writes: > > > On 01/20/11 21:27, Thomas Rast wrote: > >> Quote from the latter: > >> > >> This manual page describes only the most frequently used options. > > > > Okay. Is that a good a idea? > > Yes; the alternative is to list everything.
Would it be bad? I tend to think that a manual page is the good place to list everything the program accepts as parameters and how to use them. FMHO, Manual page is not where newcomers look to learn but it should help everybody to find and understand all of the available options.
-- Nicolas Sebrecht
Jeff KingRe: Parameter --color-words not documented for "git show"
On Fri, Jan 21, 2011 at 12:16:49AM +0100, Nicolas Sebrecht wrote:
Show 16 quoted lines
> The 20/01/11, Junio C Hamano wrote: > > Sebastian Pipping <webmaster@hartwork.org> writes: > > > > > On 01/20/11 21:27, Thomas Rast wrote: > > >> Quote from the latter: > > >> > > >> This manual page describes only the most frequently used options. > > > > > > Okay. Is that a good a idea? > > > > Yes; the alternative is to list everything. > > Would it be bad? I tend to think that a manual page is the good place to > list everything the program accepts as parameters and how to use them. > FMHO, Manual page is not where newcomers look to learn but it should > help everybody to find and understand all of the available options.
The problem is that we have a bazillion diff options that appear in many manpages, so you are stuck with one of:
1. repeat them all in each manpage (usually via some automagic
include), which dwarfs the original content, and makes it hard for
users to see subtle differences between commands 2. Say "this describes only the most frequently used options", which
leaves the user wondering which infrequently used options exist. 3. Say "we also take diff options, and you can find out more about
diff options in git-diff(1)." This at least points the user in the
right direction, but you can't search for "--color-words" in the
page. 4. Do (3), but also list the all (or common) diff options in a succint
list without descriptions, and refer the user to git-diff(1). Then
they can grep if they like, and while they won't get the immediate
answer, they will get referred to the right place.As you can probably guess, I favor option (4), though we already do (3) in some places.
-Peff
Re: Parameter --color-words not documented for "git show"
On 01/21/11 00:34, Jeff King wrote:
Show 29 quoted lines
>>> Yes; the alternative is to list everything. >> >> Would it be bad? I tend to think that a manual page is the good place to >> list everything the program accepts as parameters and how to use them. >> FMHO, Manual page is not where newcomers look to learn but it should >> help everybody to find and understand all of the available options. > > The problem is that we have a bazillion diff options that appear in many > manpages, so you are stuck with one of: > > 1. repeat them all in each manpage (usually via some automagic > include), which dwarfs the original content, and makes it hard for > users to see subtle differences between commands > > 2. Say "this describes only the most frequently used options", which > leaves the user wondering which infrequently used options exist. > > 3. Say "we also take diff options, and you can find out more about > diff options in git-diff(1)." This at least points the user in the > right direction, but you can't search for "--color-words" in the > page. > > 4. Do (3), but also list the all (or common) diff options in a succint > list without descriptions, and refer the user to git-diff(1). Then > they can grep if they like, and while they won't get the immediate > answer, they will get referred to the right place. > > As you can probably guess, I favor option (4), though we already do (3) > in some places.
I agree with Thomas here. (1) is the only option I find acceptable, personally. If you'd rather not do that, then at least know I now. Great to have --color-words around btw.
Best,
Sebastian
Jeff KingRe: Parameter --color-words not documented for "git show"
On Fri, Jan 21, 2011 at 01:05:24AM +0100, Sebastian Pipping wrote:
Show 26 quoted lines
> > The problem is that we have a bazillion diff options that appear in many > > manpages, so you are stuck with one of: > > > > 1. repeat them all in each manpage (usually via some automagic > > include), which dwarfs the original content, and makes it hard for > > users to see subtle differences between commands > > > > 2. Say "this describes only the most frequently used options", which > > leaves the user wondering which infrequently used options exist. > > > > 3. Say "we also take diff options, and you can find out more about > > diff options in git-diff(1)." This at least points the user in the > > right direction, but you can't search for "--color-words" in the > > page. > > > > 4. Do (3), but also list the all (or common) diff options in a succint > > list without descriptions, and refer the user to git-diff(1). Then > > they can grep if they like, and while they won't get the immediate > > answer, they will get referred to the right place. > > > > As you can probably guess, I favor option (4), though we already do (3) > > in some places. > > I agree with Thomas here. (1) is the only option I find acceptable, > personally. If you'd rather not do that, then at least know I now. > Great to have --color-words around btw.
I'm curious why (4) doesn't work for you. I assumed you came to the problem by one of:
- you wanted to know which options "git show" had, so you looked in
the manpage. Nothing told you about "--color-words", nor referred
you to a list of diff options. With (4), you would find that it
accepted all diff options, and then go read the list of diff options
(if you weren't already familiar with it). - you knew about --color-words, and wondered if "git show" supported
it. In the current case, searching the page turns up nothing. In
option (4), a search would find it (with a reference to diff options
if you wanted more details).The downside is that you sometimes have to be referred. The upside to me is that it becomes explicit that there is a concept of "diff options" that you can look up easily and which we can refer to easily in other parts of the manual. That helps establish a mental model of how git's options work.
So is it just that being referred is annoying, or something else?
-Peff
Re: Parameter --color-words not documented for "git show"
On 01/21/11 01:20, Jeff King wrote:
Show 25 quoted lines
>> I agree with Thomas here. (1) is the only option I find acceptable, >> personally. If you'd rather not do that, then at least know I now. >> Great to have --color-words around btw. > > I'm curious why (4) doesn't work for you. I assumed you came to the > problem by one of: > > - you wanted to know which options "git show" had, so you looked in > the manpage. Nothing told you about "--color-words", nor referred > you to a list of diff options. With (4), you would find that it > accepted all diff options, and then go read the list of diff options > (if you weren't already familiar with it). > > - you knew about --color-words, and wondered if "git show" supported > it. In the current case, searching the page turns up nothing. In > option (4), a search would find it (with a reference to diff options > if you wanted more details). > > The downside is that you sometimes have to be referred. The upside to me > is that it becomes explicit that there is a concept of "diff options" > that you can look up easily and which we can refer to easily in other > parts of the manual. That helps establish a mental model of how git's > options work. > > So is it just that being referred is annoying, or something else?
Actually that approach is perfect. I misunderstood (4) on the first read somehow. Really not my day today, sorry. I would love to see you push (4) forward.
Best,
Sebastian
Junio C HamanoRe: Parameter --color-words not documented for "git show"
Jeff King <peff@peff.net> writes:
Show 22 quoted lines
> The problem is that we have a bazillion diff options that appear in many > manpages, so you are stuck with one of: > > 1. repeat them all in each manpage (usually via some automagic > include), which dwarfs the original content, and makes it hard for > users to see subtle differences between commands > > 2. Say "this describes only the most frequently used options", which > leaves the user wondering which infrequently used options exist. > > 3. Say "we also take diff options, and you can find out more about > diff options in git-diff(1)." This at least points the user in the > right direction, but you can't search for "--color-words" in the > page. > > 4. Do (3), but also list the all (or common) diff options in a succint > list without descriptions, and refer the user to git-diff(1). Then > they can grep if they like, and while they won't get the immediate > answer, they will get referred to the right place. > > As you can probably guess, I favor option (4), though we already do (3) > in some places.
We attempt to do 1 to solve it "nicely" in some manual pages, and indeed there are many "exclude this option from the command X's manpage" magic that causes the problem of subtle differences you mentioned (which I agree).
One complication in either 3 or 4 is that they sometimes need to be accompanied with "... except these diff options do not make sense in the context of this command, so they are no-op". That is probably a price worth paying to be more helpful than 2 is.
Jeff KingRe: Parameter --color-words not documented for "git show"
On Thu, Jan 20, 2011 at 10:08:36PM -0800, Junio C Hamano wrote:
Show 14 quoted lines
> > 3. Say "we also take diff options, and you can find out more about > > diff options in git-diff(1)." This at least points the user in the > > right direction, but you can't search for "--color-words" in the > > page. > > > > 4. Do (3), but also list the all (or common) diff options in a succint > > list without descriptions, and refer the user to git-diff(1). Then > > they can grep if they like, and while they won't get the immediate > > answer, they will get referred to the right place. > [...] > One complication in either 3 or 4 is that they sometimes need to be > accompanied with "... except these diff options do not make sense in the > context of this command, so they are no-op". That is probably a price > worth paying to be more helpful than 2 is.
Yeah, I took a quick look at diff-options.txt. I think many of those special cases can be handled by just mentioning the exceptions in the text. They are usually simple and obvious special cases, like "for -M, if you are in a command which is traversing, you might be interested in --follow". I don't think it will hurt people to read that, even if they are looking at the diff-options because they want to know about "git diff".
I'll this to my documentation cleanup todo list. It's lower priority than many other things, but believe it or not I am working towards it. :)
-Peff
Re: Parameter --color-words not documented for "git show"
On 11-01-21 00:34, Jeff King wrote:
> On Fri, Jan 21, 2011 at 12:16:49AM +0100, Nicolas Sebrecht wrote:
Show 7 quoted lines
> 4. Do (3), but also list the all (or common) diff options in a succint > list without descriptions, and refer the user to git-diff(1). Then > they can grep if they like, and while they won't get the immediate > answer, they will get referred to the right place. > > As you can probably guess, I favor option (4), though we already do (3) > in some places.
I also favor (4), for the following reasons:
- sometimes you want to read the whole manpage, e.g., it's good for beginners to get feeling what is it all about.
- repeated information makes the page too long and reading too boring.
- too long manpages may scare beginners.
Maybe there could be sort-of extended manpage, containing everything, but it would need some markup beyond the capabilities of a terminal (a grayed or collapsed area in html, or whatever). However, this could be a lot of additional work, and I don't claim it should be done, just an idea.
Jeff KingRe: Parameter --color-words not documented for "git show"
On Fri, Jan 21, 2011 at 11:08:21AM +0100, Maaartin wrote:
> Maybe there could be sort-of extended manpage, containing everything, > but it would need some markup beyond the capabilities of a terminal (a > grayed or collapsed area in html, or whatever). However, this could be a > lot of additional work, and I don't claim it should be done, just an idea.
Yeah, that would be nice, but it is beyond the manpage format. For HTML versions, we can (and will) hyperlink, which at least makes following the reference easy to do.
-Peff
Jakub NarebskiRe: Parameter --color-words not documented for "git show"
Junio C Hamano <gitster@pobox.com> writes:
Show 25 quoted lines
> Sebastian Pipping <webmaster@hartwork.org> writes: >> On 01/20/11 21:27, Thomas Rast wrote: >>> Quote from the latter: >>> >>> This manual page describes only the most frequently used options. >> >> Okay. Is that a good a idea? > > Yes; the alternative is to list everything. > >> Is --abbrev-commit really used more >> frequently with "git show" than --color-words is? > > I see this as a not-so-helpful-but-still-interesting question. > > It depends on who you are, and if one wants to pick the most often used > ones, that selection may or may not coincide with _your_ usage pattern nor > mine. The original author apparently thought so, you seem to think > color-words is used a lot more often, and I personally think neither is > used often at all. So should we swap them, keep things as-is, or remove > both? > > We obviously cannot take a poll to update the list every time a new user > starts using git, but it might make sense to review them every once in a > while.
There is also additional problem, namely that because "git show" shows commit and can show diff, therefore it accepts same formatting options as "git log", and when set to display patch it accepts any diff family options.
Should we then list most common porcelanish diff options, or just refer to git-diff(1) manpage?
-- Jakub Narebski Poland ShadeHawk on #git