[PATCH v2] doc: clarify that "git bisect" accepts one or more good commits

[PATCH v2] doc: clarify that "git bisect" accepts one or more good commits

[Robert P. J. Day]

Reword the man page for "git bisect" to emphasize that, in the general
case, this command can take more than one good commit to define the
initial range of commits to examine.

Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>

---

diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt
index 4a1417bdc..2afbd9562 100644
--- a/Documentation/git-bisect.txt
+++ b/Documentation/git-bisect.txt
@@ -30,10 +30,10 @@ on the subcommand:
  git bisect help

 This command uses a binary search algorithm to find which commit in
-your project's history introduced a bug. You use it by first telling
-it a "bad" commit that is known to contain the bug, and a "good"
-commit that is known to be before the bug was introduced. Then `git
-bisect` picks a commit between those two endpoints and asks you
+your project's history introduced a bug. You use it by first telling it
+a "bad" commit that is known to contain the bug, and one or more "good"
+commits that are known to be before the bug was introduced. Then `git
+bisect` picks a commit somewhere in between those commits and asks you
 whether the selected commit is "good" or "bad". It continues narrowing
 down the range until it finds the exact commit that introduced the
 change.
@@ -58,7 +58,7 @@ $ git bisect bad                 # Current version is bad
 $ git bisect good v2.6.13-rc2    # v2.6.13-rc2 is known to be good
 ------------------------------------------------

-Once you have specified at least one bad and one good commit, `git
+Once you have specified one bad and one or more good commits, `git
 bisect` selects a commit in the middle of that range of history,
 checks it out, and outputs something similar to the following:

@@ -137,7 +137,7 @@ respectively, in place of "good" and "bad". (But note that you cannot
 mix "good" and "bad" with "old" and "new" in a single session.)

 In this more general usage, you provide `git bisect` with a "new"
-commit that has some property and an "old" commit that doesn't have that
+commit with some property and some "old" commits that don't have that
 property. Each time `git bisect` checks out a commit, you test if that
 commit has the property. If it does, mark the commit as "new";
 otherwise, mark it as "old". When the bisection is done, `git bisect`
@@ -145,19 +145,19 @@ will report which commit introduced the property.

 To use "old" and "new" instead of "good" and bad, you must run `git
 bisect start` without commits as argument and then run the following
-commands to add the commits:
+commands to identify the commits:

 ------------------------------------------------
-git bisect old [<rev>]
+git bisect old [<rev>...]
 ------------------------------------------------

-to indicate that a commit was before the sought change, or
+to identify one or more commits before the sought change, or

 ------------------------------------------------
-git bisect new [<rev>...]
+git bisect new [<rev>]
 ------------------------------------------------

-to indicate that it was after.
+to indicate a single commit after that change.

 To get a reminder of the currently used terms, use


-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: [PATCH v2] doc: clarify that "git bisect" accepts one or more good commits

[Junio C Hamano]

"Robert P. J. Day" <rpjday@crashcourse.ca> writes:

>  This command uses a binary search algorithm to find which commit in
> -your project's history introduced a bug. You use it by first telling
> -it a "bad" commit that is known to contain the bug, and a "good"
> -commit that is known to be before the bug was introduced. Then `git
> -bisect` picks a commit between those two endpoints and asks you
> +your project's history introduced a bug. You use it by first telling it
> +a "bad" commit that is known to contain the bug, and one or more "good"
> +commits that are known to be before the bug was introduced. Then `git
> +bisect` picks a commit somewhere in between those commits and asks you

Good.

> -Once you have specified at least one bad and one good commit, `git
> +Once you have specified one bad and one or more good commits, `git
>  bisect` selects a commit in the middle of that range of history,
>  checks it out, and outputs something similar to the following:

Good.

> @@ -137,7 +137,7 @@ respectively, in place of "good" and "bad". (But note that you cannot
>  mix "good" and "bad" with "old" and "new" in a single session.)
>
>  In this more general usage, you provide `git bisect` with a "new"
> -commit that has some property and an "old" commit that doesn't have that
> +commit with some property and some "old" commits that don't have that
>  property. Each time `git bisect` checks out a commit, you test if that

Good.

> @@ -145,19 +145,19 @@ will report which commit introduced the property.
>
>  To use "old" and "new" instead of "good" and bad, you must run `git
>  bisect start` without commits as argument and then run the following
> -commands to add the commits:
> +commands to identify the commits:

I am not sure if this is an improvement (see below).

>
>  ------------------------------------------------
> -git bisect old [<rev>]
> +git bisect old [<rev>...]
>  ------------------------------------------------

Good.

> -to indicate that a commit was before the sought change, or
> +to identify one or more commits before the sought change, or
>
>  ------------------------------------------------
> -git bisect new [<rev>...]
> +git bisect new [<rev>]
>  ------------------------------------------------

Good.

> -to indicate that it was after.
> +to indicate a single commit after that change.

As to "identify", I would say it is better to consistently use
"indicate" like the original of these two hunks at the end says,
i.e. "indicate that it is bad/new (or they are good/old)".

Regarding the earlier "add the commits", I do not think the original
is confusing and any reasonable reader would get that the verb is a
casually (or "carelessly") used short-hand for "add the commits to
the set of commits the bisect algorithm cares about", and turning it
to "identify" adds much clarity.

As it is immediately followed by two illustrations to use old and
new, I would think that we could just stop the sentence at "then run
the following commands:" without saying anything else.

If you really want to phrase it differently from the two sentences
to describe use of old and new, because this is acting as a headline
for these two, perhaps it is an improvement to say something like
"then run the following commands to limit the bisection range"; that
would explain _why_ these commits are "added" and would give additional
information to the readers.


   

	

Re: [PATCH v2] doc: clarify that "git bisect" accepts one or more good commits

[Robert P. J. Day]

On Fri, 24 Nov 2017, Junio C Hamano wrote:

> "Robert P. J. Day" <rpjday@crashcourse.ca> writes:

... snip ...

> > -to indicate that it was after.
> > +to indicate a single commit after that change.
>
> As to "identify", I would say it is better to consistently use
> "indicate" like the original of these two hunks at the end says,
> i.e. "indicate that it is bad/new (or they are good/old)".

  i'm going to ponder this, but let me explain why i am such an
annoying stickler for the choice of words at times, and you can read
all about it here:

  http://twain.lib.virginia.edu/projects/rissetto/offense.html

in particular, i draw your attention to twain's trashing of cooper
for, in many cases, using *almost* the right word, but not *quite* the
right word:

"Cooper's word-sense was singularly dull. When a person has a poor ear
for music he will flat and sharp right along without knowing it. He
keeps near the tune, but is not the tune. When a person has a poor ear
for words, the result is a literary flatting and sharping; you
perceive what he is intending to say, but you also perceive that he
does not say it. This is Cooper. He was not a word-musician. His ear
was satisfied with the approximate words. I will furnish some
circumstantial evidence in support of this charge. My instances are
gathered from half a dozen pages of the tale called "Deerslayer." He
uses "Verbal" for "oral"; "precision" for "facility"; "phenomena" for
"marvels"; "necessary" for "predetermined"; "unsophisticated" for
"primitive"; "preparation" for "expectancy"; "rebuked" for "subdued";
"dependent on" for "resulting from"; "fact" for "condition"; "fact"
for "conjecture"; "precaution" for "caution"; "explain" for
"determine"; "mortified" for "disappointed"; "meretricious" for
"factitious"; "materially" for "considerably"; "decreasing" for
"deepening"; "increasing" for "disappearing"; "embedded" for
"inclosed"; "treacherous" for "hostile"; "stood" for "stooped";
"softened" for "replaced"; "rejoined" for "remarked"; "situation" for
"condition"; "different" for "differing"; "insensible" for
"unsentient"; "brevity" for "celerity"; "distrusted" for "suspicious";
"mental imbecility" for "imbecility"; "eyes" for "sight";
"counteracting" for "opposing"; "funeral obsequies" for "obsequies."

  in this sense, i don't think "indicate" and "identify" are
completely interchangeable. in my mind, the word "identify" does
nothing more than, you know, point at something and say, "that one,
that's the one i'm talking about;" it goes no further than that.

  on the other hand, the word "indicate" (in my mind) implies that
you're about to provide some *property* or *quality* of something, and
you do exactly that in the earlier quote:

> As to "identify", I would say it is better to consistently use
> "indicate" like the original of these two hunks at the end says,
> i.e. "indicate that it is bad/new (or they are good/old)".

  as in, you "identify" a commit, but you "indicate" that it
represents a good or bad commit. i know this sounds picky, but it is
exactly this tendency of using *almost* the right word that makes a
lot of documentation potentially confusing. given this distinction,
depending on the word to be used, i would write one of:

1) "first, identify the bad commit and one or more good commits..."

2) "first, indicate which commit is the bad commit, and which commits
are the good commits ..."

  the eventual meaning *should* be the same, but the choice of words
can make the meaning clear, or can confuse the reader.

  thoughts?

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: [PATCH v2] doc: clarify that "git bisect" accepts one or more good commits

[Junio C Hamano]

"Robert P. J. Day" <rpjday@crashcourse.ca> writes:

>   in this sense, i don't think "indicate" and "identify" are
> completely interchangeable. in my mind, the word "identify" does
> nothing more than, you know, point at something and say, "that one,
> that's the one i'm talking about;" it goes no further than that.
>
>   on the other hand, the word "indicate" (in my mind) implies that
> you're about to provide some *property* or *quality* of something, and
> you do exactly that in the earlier quote:

I do not think the two words have different connotations, so we are
in agreement.  You do not necessarily need a property in mind when
you "identify" a commit.  You could just "identify" this and that
commits to yourself, to keep them in mind.  You _also_ can have a
property in mind and "identify" this commit as a good one, and that
commit as a bad one.

But identifying a commit as bad (or another one as good) alone to
yourself does not get anything started.  In order to advance the
bisection process, you need to tell the "git bisect" machinery that
"this commit is good", "that commit is bad", etc.  I would think
"indicate" is a verb with better connotation than "identify" for
describing that action.  You indicate something *to* *somebody, and
in this case you indicate that this commit is good and that commit
is bad to git.

Re: [PATCH v2] doc: clarify that "git bisect" accepts one or more good commits

[Junio C Hamano]

Junio C Hamano <gitster@pobox.com> writes:

> "Robert P. J. Day" <rpjday@crashcourse.ca> writes:
>
>>   in this sense, i don't think "indicate" and "identify" are
>> completely interchangeable. in my mind, the word "identify" does
>> nothing more than, you know, point at something and say, "that one,
>> that's the one i'm talking about;" it goes no further than that.
>>
>>   on the other hand, the word "indicate" (in my mind) implies that
>> you're about to provide some *property* or *quality* of something, and
>> you do exactly that in the earlier quote:
>
> I do not think the two words have different connotations, so we are
> in agreement.  You do not necessarily need a property in mind when

Eek.  I do do think the two words are not interchangeable.
I should stop typing late at night.