Re: [PATCH] bisect: revise manpage

From: Michael Haggerty <mhagger@alum.mit.edu>
Date: Jun 26, 2015, 14:55 UTC
Message-ID: <558D67FD.2000607@alum.mit.edu>
In-Reply-To: <vpqwpyqws53.fsf@anie.imag.fr>

On 06/26/2015 02:50 PM, Matthieu Moy wrote:

Show 23 quoted lines

> Michael Haggerty <mhagger@alum.mit.edu> writes:
> 
>> * Remove the "Look for a fix instead of a regression in the code"
>>   example, as (1) it was in the "git bisect run" section, but it
>>   doesn't use that command, and (2) I think this usage is adequately
>>   explained in the "Alternate terms" section.
> [...]
>> -* Look for a fix instead of a regression in the code
>> -+
>> -------------
>> -$ git bisect start
>> -$ git bisect new HEAD    # current commit is marked as new
>> -$ git bisect old HEAD~10 # the tenth commit from now is marked as old
>> -------------
>> -+
>> -Let's consider the last commit has a given property, and that we are looking
>> -for the commit which introduced this property. For each commit the bisection
>> -guide us to, we will test if the property is present. If it is we will mark
>> -the commit as new with 'git bisect new', otherwise we will mark it as old.
>> -At the end of the bisect session, the result will be the first new commit (e.g
>> -the first one with the property).
> 
> I disagree with this one: it's in the example section, not bisect run.

Oh yeah, you're right. I mistakenly thought that the examples section was subsidiary to the `git bisect run` section.

> The other explanations are nice, but never show the full sequence of
> commands so I think an example to sum up does help.

I didn't like this example so much because (1) the code snippet is pretty trivial, and (2) the explanation afterwards is more of a general explanation of `git bisect` than a description of this particular example. (I added text elsewhere that retains the spirit of this explanation.)

If you want to keep this example, how about making it a little bit more interesting? Perhaps use `git bisect terms` instead of new/old, and a little motivational text showing how the alternate names make the commands clearer? As terms one could maybe use fast/slow and make the example about benchmark speeds or something?

By the way, when I was revising the text two things occurred to me that have probably been discussed to death elsewhere but let me mention them anyway:

1. I found it confusing that `git bisect terms` lists its arguments in
the order `<term-new> <term-old>`. I think that listing them in
"chronological" order would have been a lot more intuitive. But I expect
this choice was made because `git bisect start` takes optional arguments
in that order, so the inconsistency might be worse than the backwardness
of this single command's arguments.

2. When I was describing "old/new", I kept wishing that I could type
"before/after" instead, because those terms seemed to agree better with
the prose description of what "old/new" mean. I wonder if "before/after"
might be better names for commits determined to be before/after the
change being sought?

Oh and I just noticed that `git bisect terms` is missing from the synopsis at the top of the man page.

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu