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

From: Junio C Hamano <gitster@pobox.com>
Date: Jun 24, 2015, 17:46 UTC
Message-ID: <xmqqa8vp9ezq.fsf@gitster.dls.corp.google.com>
In-Reply-To: <1435159062-23468-6-git-send-email-Matthieu.Moy@imag.fr>

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

Show 13 quoted lines

> +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?

Show 11 quoted lines

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

Show 10 quoted lines

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