Score in diff-format

> Hi,
> 
> diff-format.txt says this:
> 
>   An output line is formatted this way:
>   (snip)
> 
>   That is, from the left to the right:
> 
>   (snip)
>   . status, followed by optional "score" number.
> 
>   (snip)
>   Status letters C and R are always followed by a score (denoting the
>   percentage of similarity between the source and target of the move or
>   copy), and are the only ones to be so.
>
> As I read this last paragraph, the following is not supposed to happen:
> $ git diff-tree 926b1ec63ee045503f609e88ca445b94c06bd5d7 --abbrev -r -C -B
> 926b1ec63ee045503f609e88ca445b94c06bd5d7
> :100644 100644 81ac702... 7ab0cf4... M087       contrib/subtree/INSTALL
> 
> It however makes sense that it happens, and it looks like a case of the
> documentation being outdated or confusing. Or am I interpreting it wrong?

> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
> > I'd say it depends on the definition of "so". The documentation is
> > correct if you read "so" as "*always* followed by a score". I guess you
> > read it as "followed by a score".
> 
> I read it so as well ;-)
> 
> > Percentages with M are not mentioned in diff-format, but they are a
> > consequence of "-B" processing. Maybe we could mention that?
> 
> -- >8 --
> Subject: diff-format doc: a score can follow M for rewrite
> 
> b6d8f309 (diff-raw format update take #2., 2005-05-23) started
> documenting the diff format, and it said
> 
>  ...
>  (8) sha1 for "dst"; 0{40} if creation, unmerged or "look at work tree".
>  (9) status, followed by similarlity index number only for C and R.
>  (10) a tab or a NUL when '-z' option is used.
>  ...
> 
> because C and R _were_ the only ones that came with a number back
> then.  This was corrected by ddafa7e9 (diff-helper: Fix R/C score
> parsing under -z flag., 2005-05-29) and we started saying "score"
> instead of "similarlity index" (because we can have other kind of
> score there), and stopped saying "only for C and R" (because Git is
> an ever evolving system).  Later f345b0a0 ([PATCH] Add -B flag to
> diff-* brothers., 2005-05-30) introduced a new concept,
> "dissimilarity" score and it did not have to fix any documentation.
> 
> The current text that says only C and R can have scores came
> independently from a5a323f3 (Add reference for status letters in
> documentation., 2008-11-02) and it was wrong from the day one.
> 
> Noticed-by: Mike Hommey
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
> 
>  Documentation/diff-format.txt | 3 ++-
>  1 file changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
> index 15c7e79..e6cfc9b 100644
> --- a/Documentation/diff-format.txt
> +++ b/Documentation/diff-format.txt
> @@ -66,7 +66,8 @@ be committed)
>  
>  Status letters C and R are always followed by a score (denoting the
>  percentage of similarity between the source and target of the move or
> -copy), and are the only ones to be so.
> +copy).  M may show how completely the modification rewrites the file
> +with a score (denoting the percentage of dissimilarity).

> On Wed, Jan 28, 2015 at 01:17:19PM -0800, Junio C Hamano wrote:
>> diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt
>> index 15c7e79..e6cfc9b 100644
>> --- a/Documentation/diff-format.txt
>> +++ b/Documentation/diff-format.txt
>> @@ -66,7 +66,8 @@ be committed)
>>  
>>  Status letters C and R are always followed by a score (denoting the
>>  percentage of similarity between the source and target of the move or
>> -copy), and are the only ones to be so.
>> +copy).  M may show how completely the modification rewrites the file
>> +with a score (denoting the percentage of dissimilarity).
>
> How about something like:
>
>   Status letter M may be followed by a score (denoting the percentage of
>   dissimilarity) for file rewrites.