Re: [PATCH v8 5/5] bisect: allow any terms set by user

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

Matthieu Moy <Matthieu.Moy@imag.fr> writes:

> +Alternative terms: use your own terms
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +If the builtins terms bad/good and new/old do not satisfy you, you can
> +set your own terms.
> +
> +------------------------------------------------
> +git bisect terms term1 term2
> +------------------------------------------------
> +
> +This command has to be used before a bisection has started.
> +The term1 must be associated with the latest revisions and term2 with the
> +ancestors of term1.

While this is not incorrect per-se, it would be more helpful to tell
the readers that they are hunting for a commit that changes the state
they would call "term2" into "term1" somewhere.  e.g.

	-ancestors of term1.
	+ancestors of term1.  For example, if something was buggy in
        +the old part of the history, you know somewhere the bug was
	+fixed, and you want to find the exact commit that fixed it,
        +you may want to say `git bisect terms fixed broken`; this
        +way, you would mark a commit that still has the bug with
        +`broken`, and a newer one after the fix with `fixed`.

or something?

> -USAGE='[help|start|bad|good|new|old|skip|next|reset|visualize|replay|log|run]'
> +USAGE='[help|start|bad|good|new|old|terms|skip|next|reset|visualize|replay|log|run]'
>  LONG_USAGE='git bisect help
>  	print this long help message.
>  git bisect start [--no-checkout] [<bad> [<good>...]] [--] [<pathspec>...]
> @@ -11,6 +11,8 @@ git bisect (bad|new) [<rev>]
>  git bisect (good|old) [<rev>...]
>  	mark <rev>... known-good revisions/
>  		revisions before change in a given property.
> +git bisect terms term1 term2
> +	set up term1 and term2 as bisection terms.

This will not help those who cannot remember which one between these
two they want:

	git bisect terms new old
        git bisect terms old new

I am wondering (together with the documentation patch) if it would
be better to be more explicit, instead of term[12], like this:

	git bisect terms new old

or even

	git bisect terms bad good

assuming that the only reason they use 'terms' is because they are
sufficiently familiar with 'git bisect' and (intellectually) know
that 'bad' is more recent and 'good' is what it used to be, but have
trouble remembering which one is which during a hunt for a fix.

> +bisect_terms () {
> +	case "$#" in
> +	0)
> +		if test -s "$GIT_DIR/BISECT_TERMS"
> +		then
> +			{
> +			read term1
> +			read term2
> +			}<"$GIT_DIR/BISECT_TERMS"
> +			gettextln "Your current terms are $term1 and $term2."

The same comment on this part.  Instead of "git bisect terms" that
just says "You are using $term1 and $term2", the users would benefit
if it said "You are using $term1 for newer state and $term2 for
older state" [*1*].

Thanks.


[Footnote]

*1* It is funny that I had to rewrite this "if it said..." a few
times to make sure I got newer and older right, even though I had
the relevant pieces (and only releavant pieces) of information for
the doc and help text in a single patch form while composing this
response.  I suspect that an end user without such material would be
a lot more confused than I was.