Re: [PATCH] bisect: revise manpage
Michael Haggerty mhag...@alum.mit.edu writes: 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 agree that the explanations were redundant. I removed it. 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, I now have both. and a little motivational text showing how the alternate names make the commands clearer? Well, actually the motivational text would be essentially what was already said. 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. Yes, I think keeping the order of 'git bisect start' is good. Junio also mentionned alphabetic order (bad - good, new - old). 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? I like old/new essentially because they are very short. I would keep the code as-is for now, but it's very easy to add a before/after couple of terms later if needed. If others think before/after are better, it's still time to change it. Oh and I just noticed that `git bisect terms` is missing from the synopsis at the top of the man page. Fixed. -- Matthieu Moy http://www-verimag.imag.fr/~moy/ -- 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
Re: [PATCH] bisect: revise manpage
Christian Couder christian.cou...@gmail.com writes: On Fri, Jun 26, 2015 at 4:58 PM, Michael Haggerty mhag...@alum.mit.edu wrote: The reference `refs/bisect/bad` will be left pointing at that commit. Yeah ok. I took this one. -- Matthieu Moy http://www-verimag.imag.fr/~moy/ -- 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
Re: [PATCH] bisect: revise manpage
On Fri, Jun 26, 2015 at 4:58 PM, Michael Haggerty mhag...@alum.mit.edu wrote: On 06/26/2015 03:15 PM, Christian Couder wrote: On Fri, Jun 26, 2015 at 3:00 PM, Matthieu Moy matthieu@grenoble-inp.fr wrote: Christian Couder christian.cou...@gmail.com writes: On Fri, Jun 26, 2015 at 1:30 PM, Michael Haggerty mhag...@alum.mit.edu wrote: [...] +Eventually there will be no more revisions left to bisect, and the +command will print out a description of the first bad commit, and also +create a reference called `refs/bisect/bad` that points at that +commit. This could be understood as meaning that `refs/bisect/bad` is created only at the end of the bisection. -Eventually there will be no more revisions left to bisect, and you -will have been left with the first bad kernel revision in refs/bisect/bad. The original looks better to me in this regard. I'm changing it to: Eventually there will be no more revisions left to bisect, and the command will print out a description of the first bad commit. The reference `refs/bisect/bad` created by bisect will point at that commit. I agree that is better. For the last sentence I'd suggest: The reference called `refs/bisect/bad` will point at that commit. Or maybe The reference `refs/bisect/bad` will be left pointing at that commit. Yeah ok. -- 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
Re: [PATCH] bisect: revise manpage
On 06/26/2015 03:15 PM, Christian Couder wrote: On Fri, Jun 26, 2015 at 3:00 PM, Matthieu Moy matthieu@grenoble-inp.fr wrote: Christian Couder christian.cou...@gmail.com writes: On Fri, Jun 26, 2015 at 1:30 PM, Michael Haggerty mhag...@alum.mit.edu wrote: [...] +Eventually there will be no more revisions left to bisect, and the +command will print out a description of the first bad commit, and also +create a reference called `refs/bisect/bad` that points at that +commit. This could be understood as meaning that `refs/bisect/bad` is created only at the end of the bisection. -Eventually there will be no more revisions left to bisect, and you -will have been left with the first bad kernel revision in refs/bisect/bad. The original looks better to me in this regard. I'm changing it to: Eventually there will be no more revisions left to bisect, and the command will print out a description of the first bad commit. The reference `refs/bisect/bad` created by bisect will point at that commit. I agree that is better. For the last sentence I'd suggest: The reference called `refs/bisect/bad` will point at that commit. Or maybe The reference `refs/bisect/bad` will be left pointing at that commit. 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
Re: [PATCH] bisect: revise manpage
Michael Haggerty mhag...@alum.mit.edu writes: Eventually there will be no more revisions left to bisect, and the command will print out a description of the first bad commit. The reference `refs/bisect/bad` created by bisect will point at that commit. I agree that is better. For the last sentence I'd suggest: The reference called `refs/bisect/bad` will point at that commit. Or maybe The reference `refs/bisect/bad` will be left pointing at that commit. Sounds good. I had a trouble with will be no more reivsions left to bisect, though. left to check or left to inspect I would understand. -- 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
Re: [PATCH] bisect: revise manpage
Michael Haggerty mhag...@alum.mit.edu writes: 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. Consistency with 'start' is truly a good motivaition. And 'start' asking for 'bad' first is not backwardness but comes primarily from syntactic need. You need one and only one 'bad' and can give zero or more 'good' to the command, so start bad [good...] becomes a more natural way than start [good...] bad to form a command line. 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? Yeah, I like that, but I do not think replacing 'old/new' with 'before/after' is worth the trouble. Both would work equally well at least for me. -- 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
Re: [PATCH] bisect: revise manpage
Christian Couder christian.cou...@gmail.com writes: On Fri, Jun 26, 2015 at 1:30 PM, Michael Haggerty mhag...@alum.mit.edu wrote: [...] +Eventually there will be no more revisions left to bisect, and the +command will print out a description of the first bad commit, and also +create a reference called `refs/bisect/bad` that points at that +commit. This could be understood as meaning that `refs/bisect/bad` is created only at the end of the bisection. -Eventually there will be no more revisions left to bisect, and you -will have been left with the first bad kernel revision in refs/bisect/bad. The original looks better to me in this regard. I'm changing it to: Eventually there will be no more revisions left to bisect, and the command will print out a description of the first bad commit. The reference `refs/bisect/bad` created by bisect will point at that commit. -- Matthieu Moy http://www-verimag.imag.fr/~moy/ -- 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
Re: [PATCH] bisect: revise manpage
On Fri, Jun 26, 2015 at 1:30 PM, Michael Haggerty mhag...@alum.mit.edu wrote: [...] +Eventually there will be no more revisions left to bisect, and the +command will print out a description of the first bad commit, and also +create a reference called `refs/bisect/bad` that points at that +commit. This could be understood as meaning that `refs/bisect/bad` is created only at the end of the bisection. -Eventually there will be no more revisions left to bisect, and you -will have been left with the first bad kernel revision in refs/bisect/bad. The original looks better to me in this regard. Thanks, Christian. -- 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
Re: [PATCH] bisect: revise manpage
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. The other explanations are nice, but never show the full sequence of commands so I think an example to sum up does help. -- Matthieu Moy http://www-verimag.imag.fr/~moy/ -- 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
Re: [PATCH] bisect: revise manpage
On Fri, Jun 26, 2015 at 3:00 PM, Matthieu Moy matthieu@grenoble-inp.fr wrote: Christian Couder christian.cou...@gmail.com writes: On Fri, Jun 26, 2015 at 1:30 PM, Michael Haggerty mhag...@alum.mit.edu wrote: [...] +Eventually there will be no more revisions left to bisect, and the +command will print out a description of the first bad commit, and also +create a reference called `refs/bisect/bad` that points at that +commit. This could be understood as meaning that `refs/bisect/bad` is created only at the end of the bisection. -Eventually there will be no more revisions left to bisect, and you -will have been left with the first bad kernel revision in refs/bisect/bad. The original looks better to me in this regard. I'm changing it to: Eventually there will be no more revisions left to bisect, and the command will print out a description of the first bad commit. The reference `refs/bisect/bad` created by bisect will point at that commit. For the last sentence I'd suggest: The reference called `refs/bisect/bad` will point at that commit. -- 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
