Re: [PATCH v2] Document -B<n>[/<m>], -M<n> and -C<n> variants of -B, -M and -C

From: Junio C Hamano <gitster@pobox.com>
Date: Aug 2, 2010, 18:18 UTC
Message-ID: <7vsk2wlvxv.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1280747527-30444-1-git-send-email-Matthieu.Moy@imag.fr>

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

Show 11 quoted lines

> These options take an optional argument, but this optional argument was
> not documented.
>
> While we're there, fix a typo in a comment in diffcore.h.
>
> Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
> ---
> Here's a new version. I've eliminated "line" from the wording. I'm
> still not sure I'm technically correct, especially about the
> interaction between "n" and "m" (the "A rewrite is considered when
> both thresholds are reached par of the patch).

I think they are technically correct, but I doubt diff-options.txt is a place to be more technically correct than to be useful to the end users.

What does an end user want to know from the list of options?

Show 14 quoted lines

> +-B[<n>]::
> +-B<n>/<m>::
> +	Break complete rewrite changes into pairs of delete and
> +	create. When `n` and/or `m` are specified, they give threshold
> +	(as a percentage of changed content) above which a change is
> +	considered as complete rewrite. `n` is a threshold on the
> +	similarity index (i.e. amount of addition/deletions compared
> +	to the file's size). For example, `-B90%` means git will
> +	detect a rewrite if more than 90% of the file's content have
> +	been modified. `m` is a threshold on the disimilarity index
> +	(i.e. amount of deletions from the old version). A rewrite is
> +	considered when both thresholds are reached. When either `n`
> +	or `m` is not specified, the default applies (`n` = 50% and
> +	`m` = 60%). See linkgit:gitdiffcore[7] for more details.

After reading this, we know that with magic numbers given to -B, we can "break" changes into "pairs of delete and create". What does it mean in the practical terms? That is a lot more essential information than how the magic numbers affect the decision to break or not break. The user does not get a motivation to help git "break" a pair from the above.

    The -B option serves two purposes.

    It affects the way a change that amounts to a total rewrite of a file
    not as a series of deletion and insertion mixed together with a very
    few lines that happen to match textually as the context, but as a
    single deletion of everything old followed by a single insertion of
    everything new, and the number <m> controls this aspect of the -B
    option (defaults to 60%).  `-B/70%` specifies that less than 30% of
    the original should remain in the result for git to consider it a
    total rewrite (i.e. otherwise the resulting patch will be a series of
    deletion and insertion mixed together with context lines).

    When used with -M, a totally-rewritten file is also considered as the
    source of a rename (usually -M only considers a file that disappeared
    as the source of a rename), and the number <n> controls this aspect of
    the -B option (defaults to 50%).  `-B20%` specifies that a change with
    addition and deletion compared to 20% or more of the file's size are
    eligible for being picked up as a possible source of a rename to
    another file.