From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 29 Jul 2010 16:10:28 GMT
Subject: Re: [RFC/PATCH] Document -B<n>[/<m>], -M<n> and -C<n> variants of -B, -M and -C
Message-ID: <7vk4oeuv4b.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1280310239-16897-1-git-send-email-Matthieu.Moy@imag.fr>

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

> I'm not really happy with my description of -Bn/m, which I essentially
> took from eeaa46031479 (Junio, Jun 3 2005, diff: Update -B
> heuristics). Someone with better understanding of how it works can
> probably propose something better.

Your explanation for '<n>' being the same across -B/-M/-C is reasonable.
Explanation of '<m>' might want to clarify why it counts only the deletion
and to mention that "100-similarity != dissimilarity", but as the end-user
level documentation, these probably are unnecessary.

> +-B[<n>]::
> +-B<n>/<m>::
>  	Break complete rewrite changes into pairs of delete and create.
> +	If `n` is specified, it gives the threshold (as a percentage
> +	of changed lines) above which a change is considered as
> +	complete rewrite.  For example, `-B90%` means git will detect a
> +	rewrite if more than 90% of the lines have been modified. ...

I am fine with the use of word "lines" if it is clear that we are giving a
simplified explanation (white lie) to the readers, but the (dis)similarity
numbers don't have much to do with "lines".  I would of course be happier
if we can come up with a phrase that tells the readers that these numbers
range between 0-100%, and the larger the <n> is, the larger the extent of
change has to be for the filepair to be considered for -B/-M processing,
without use of word "lines".

Thanks.