Matthieu Moy <Matthieu.Moy@xxxxxxx> writes:
> 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@xxxxxxx>
> ---
> 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?
> +-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.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html