threads / bug / 44866
Subject: Bug report: Documentation error in git-bisect man description
Hi,
there is a mistake in the git-bisect description. The second paragraph of it says ‘the terms "old" and "new" can be used in place of "good" and "bad"’. So from a logical point of view the description part stating the usage syntax should be:
git bisect (bad|good) [<rev>] git bisect (old|new) [<rev>...]
instead of
git bisect (bad|new) [<rev>] git bisect (good|old) [<rev>...]
Checked man page version of 2.11.0, but it is in my local 2.10.2 git as well.
Best regards, Manuel
Junio C HamanoRe: Bug report: Documentation error in git-bisect man description
Manuel Ullmann <ullman.alias@posteo.de> writes:
> Hi, > > there is a mistake in the git-bisect description. > The second paragraph of it says ‘the terms "old" and "new" can be used > in place of "good" and "bad"’. So from a logical point of view the > description part stating the usage syntax should be: > > git bisect (bad|good) [<rev>] > git bisect (old|new) [<rev>...] > > instead of > > git bisect (bad|new) [<rev>] > git bisect (good|old) [<rev>...] > > Checked man page version of 2.11.0, but it is in my local 2.10.2 git as well.
Hmmm, I tend to agree, modulo a minor fix.
If the description were in a context inside a paragraph like this:
When you want to tell 'git bisect' that a <rev> belongs to the newer half of the history, you say
git bisect (bad|new) [<rev>]
On the other hand, when you want to tell 'git bisect' that a <rev> belongs to the older half of the history, you can say
git bisect (good|old) [<rev>]
then the pairing we see in the current text makes quite a lot of sense.
But in the early part of the description section, listing the information that logically belongs to the synopsis section, I think the current one is misleading. You are painting commits with two colors, and if you are from the "older vs newer" school, you say either 'old' or 'new' as the names of these two colors, and do not use 'bad' or 'good'. A line with "git bisect (old|new) [<rev>]" in the list would make more sense.
Similarly, if you are from the "still good vs already bad" school, you would either say 'good' or 'bad' so you would want to see a line with "git bisect (good|bad) [<rev>]" in the list (not "bad|good" in that order, but opposite).
Christian, am I talking nonsense?
Junio C HamanoRe: Bug report: Documentation error in git-bisect man description
Junio C Hamano <gitster@pobox.com> writes:
> Manuel Ullmann <ullman.alias@posteo.de> writes: > > Hmmm, I tend to agree, modulo a minor fix. > > If the description were in a context inside a paragraph like this: > > When you want to tell 'git bisect' that a <rev> belongs to > the newer half of the history, you say > > git bisect (bad|new) [<rev>] > > On the other hand, when you want to tell 'git bisect' that a > <rev> belongs to the older half of the history, you can say > > git bisect (good|old) [<rev>] > > then the pairing we see in the current text makes quite a lot of > sense.
Actually, the above is _exactly_ what was intended. I misread the current documentation when I made the comment, and I think that the current one _IS_ correct. The latter half of the above is not about a single rev. You can paint multiple commits with the "older half" color, i.e.
On the other hand, when you want to tell 'git bisect' that one or more <rev>s belong to the older half of the history, you can say
git bisect (good|old) [<rev>...]
In contrast, you can mark only one <rev> as newer (or "already bad"). So pairing (bad|good) and (new|old) like you suggested breaks the correctness of the command line description.
If (bad|new) and (good|old) bothers you because they may mislead the readers to think bad is an opposite of new (and good is an opposite of old), the only solution I can think of to that problem is to expand these two lines into four and list them like this:
git bisect bad [<rev>]
git bisect good [<rev>...]
git bisect new [<rev>]
git bisect old [<rev>...]Re: Bug report: Documentation error in git-bisect man description
I see. Thanks for the clarification. The pairing not being pairs of opposites was indeed, what confused me. So that description was not meant in the sense, that you use these pairs when working with bisect, but instead they are ordered according to the argument possibilities.
Sorry for spreading confusion. I think the second paragraph should be sufficient for documentation.
Best regards Manuel
> Junio C Hamano <gitster@pobox.com> writes: > >> Manuel Ullmann <ullman.alias@posteo.de> writes: >> >> Hmmm, I tend to agree, modulo a minor fix. >> >> If the description were in a context inside a paragraph like this: >> >> When you want to tell 'git bisect' that a <rev> belongs to >> the newer half of the history, you say >> >> git bisect (bad|new) [<rev>] >> >> On the other hand, when you want to tell 'git bisect' that a >> <rev> belongs to the older half of the history, you can say >> >> git bisect (good|old) [<rev>] >> >> then the pairing we see in the current text makes quite a lot of >> sense. > > Actually, the above is _exactly_ what was intended. I misread the > current documentation when I made the comment, and I think that the > current one _IS_ correct. The latter half of the above is not about > a single rev. You can paint multiple commits with the "older half" > color, i.e. > > On the other hand, when you want to tell 'git bisect' that > one or more <rev>s belong to the older half of the history, > you can say > > git bisect (good|old) [<rev>...] > > In contrast, you can mark only one <rev> as newer (or "already > bad"). So pairing (bad|good) and (new|old) like you suggested > breaks the correctness of the command line description. > > If (bad|new) and (good|old) bothers you because they may mislead the > readers to think bad is an opposite of new (and good is an opposite > of old), the only solution I can think of to that problem is to > expand these two lines into four and list them like this: > > git bisect bad [<rev>] > git bisect good [<rev>...] > git bisect new [<rev>] > git bisect old [<rev>...]
Christian CouderRe: Bug report: Documentation error in git-bisect man description
On Fri, Jan 13, 2017 at 12:42 AM, Junio C Hamano <gitster@pobox.com> wrote:
> Junio C Hamano <gitster@pobox.com> writes: > >> Manuel Ullmann <ullman.alias@posteo.de> writes: >> >> Hmmm, I tend to agree, modulo a minor fix. >> >> If the description were in a context inside a paragraph like this: >> >> When you want to tell 'git bisect' that a <rev> belongs to >> the newer half of the history, you say >> >> git bisect (bad|new) [<rev>] >> >> On the other hand, when you want to tell 'git bisect' that a >> <rev> belongs to the older half of the history, you can say >> >> git bisect (good|old) [<rev>] >> >> then the pairing we see in the current text makes quite a lot of >> sense. > > Actually, the above is _exactly_ what was intended. I misread the > current documentation when I made the comment, and I think that the > current one _IS_ correct. The latter half of the above is not about > a single rev. You can paint multiple commits with the "older half" > color, i.e. > > On the other hand, when you want to tell 'git bisect' that > one or more <rev>s belong to the older half of the history, > you can say > > git bisect (good|old) [<rev>...] > > In contrast, you can mark only one <rev> as newer (or "already > bad"). So pairing (bad|good) and (new|old) like you suggested > breaks the correctness of the command line description.
Yeah, I agree.
> If (bad|new) and (good|old) bothers you because they may mislead the > readers to think bad is an opposite of new (and good is an opposite > of old), the only solution I can think of to that problem is to > expand these two lines into four and list them like this: > > git bisect bad [<rev>] > git bisect good [<rev>...] > git bisect new [<rev>] > git bisect old [<rev>...]
Maybe it would be more complete and a bit clearer if it was:
git bisect (bad|new|<term-new>) [<rev>]
git bisect (good|old|<term-old>) [<rev>...]Re: Bug report: Documentation error in git-bisect man description
> On Fri, Jan 13, 2017 at 12:42 AM, Junio C Hamano <gitster@pobox.com> wrote: >> Junio C Hamano <gitster@pobox.com> writes: >> >>> Manuel Ullmann <ullman.alias@posteo.de> writes: >>> >>> Hmmm, I tend to agree, modulo a minor fix. >>> >>> If the description were in a context inside a paragraph like this: >>> >>> When you want to tell 'git bisect' that a <rev> belongs to >>> the newer half of the history, you say >>> >>> git bisect (bad|new) [<rev>] >>> >>> On the other hand, when you want to tell 'git bisect' that a >>> <rev> belongs to the older half of the history, you can say >>> >>> git bisect (good|old) [<rev>] >>> >>> then the pairing we see in the current text makes quite a lot of >>> sense. >> >> Actually, the above is _exactly_ what was intended. I misread the >> current documentation when I made the comment, and I think that the >> current one _IS_ correct. The latter half of the above is not about >> a single rev. You can paint multiple commits with the "older half" >> color, i.e. >> >> On the other hand, when you want to tell 'git bisect' that >> one or more <rev>s belong to the older half of the history, >> you can say >> >> git bisect (good|old) [<rev>...] >> >> In contrast, you can mark only one <rev> as newer (or "already >> bad"). So pairing (bad|good) and (new|old) like you suggested >> breaks the correctness of the command line description. > > Yeah, I agree. > >> If (bad|new) and (good|old) bothers you because they may mislead the >> readers to think bad is an opposite of new (and good is an opposite >> of old), the only solution I can think of to that problem is to >> expand these two lines into four and list them like this: >> >> git bisect bad [<rev>] >> git bisect good [<rev>...] >> git bisect new [<rev>] >> git bisect old [<rev>...] > > Maybe it would be more complete and a bit clearer if it was: > > git bisect (bad|new|<term-new>) [<rev>] > git bisect (good|old|<term-old>) [<rev>...]
That would clarify the intention quite a bit (at least for me).
Best regards, Manuel