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

[Junio C Hamano <gitster@pobox.com>]

"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.