Parameter --color-words not documented for "git show"
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
Quoted 8 lines · Sebastian Pipping
I noticed that
git show --color-wordsworks 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.
Signature · 2 lines
Thomas Rast
trast@{inf,student}.ethz.chQuoted 3 lines · Thomas Rast
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
Quoted 6 lines · Sebastian Pipping
Quoted 3 lines · Thomas Rast
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.
Quoted 2 lines
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.
Quoted 10 lines · Junio C Hamano
Quoted 6 lines · Sebastian Pipping
Quoted 3 lines · Thomas Rast
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.
Signature · 1 line
Nicolas Sebrecht
Quoted 8 lines · Nicolas Sebrecht
Quoted 7 lines · Junio C Hamano
Quoted 5 lines · Sebastian Pipping
Quoted 3 lines · Thomas Rast
Quote from the latter:
This manual page describes only the most frequently used options.
Quoted 8 lines
Quoted 3 lines
Quoted 1 line
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
Quoted 22 lines · Jeff King
Quoted 6 lines
Quoted 1 line
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.
Quoted 7 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 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
Quoted 20 lines · Sebastian Pipping
Quoted 20 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.
Quoted 6 lines
Quoted 2 lines
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
Quoted 18 lines · Jeff King
Quoted 3 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).
Quoted 7 lines
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
Quoted 9 lines · Jeff King
On Fri, Jan 21, 2011 at 12:16:49AM +0100, Nicolas Sebrecht wrote:
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.
Quoted 4 lines · Maaartin
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
Quoted 15 lines · Jeff King
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.
Quoted 7 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.
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.
Quoted 9 lines · Junio C Hamano
Quoted 9 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.
Quoted 5 lines
[...]
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
Quoted 22 lines · Junio C Hamano
Quoted 6 lines · Sebastian Pipping
Quoted 3 lines · Thomas Rast
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.
Quoted 2 lines
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?
Quoted 3 lines
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?
Signature · 3 lines
Jakub Narebski Poland ShadeHawk on #git