On 06/26/2015 02:50 PM, Matthieu Moy wrote: > Michael Haggerty <mhag...@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 mhag...@alum.mit.edu -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
