Score in diff-format

Score in diff-format

[Mike Hommey]

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?

Cheers,

Mike

Re: Score in diff-format

[Michael J Gruber]

Mike Hommey schrieb am 28.01.2015 um 07:23:
> 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?

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

Percentages with M are not mentioned in diff-format, but they are a
consequence of "-B" processing. Maybe we could mention that?

Michael

Re: Score in diff-format

[Junio C Hamano]

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).
 
 <sha1> is shown as all 0's if a file is new on the filesystem
 and it is out of sync with the index.

Re: Score in diff-format

[Mike Hommey]

On Wed, Jan 28, 2015 at 01:17:19PM -0800, Junio C Hamano wrote:
> 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).

How about something like:

  Status letter M may be followed by a score (denoting the percentage of
  dissimilarity) for file rewrites.

Mike

Re: Score in diff-format

[Junio C Hamano]

Mike Hommey <mh@glandium.org> writes:

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

OK.  That seems to make the end result sound more consistent by
repeated use of "status letter X".  Let's use that.

Thanks.

Re: Score in diff-format

[Junio C Hamano]

Mike Hommey <mh@glandium.org> writes:

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

Good eyes.  I _think_ what happened was that break-and-then-merge
(aka complete rewrite detection) came way after this was originally
written, and "the only ones to be so" is stale in the world with
complete rewrite feature enabled.

Perhaps update

    , and are the only ones to be so.

to

    ; M may be followed by a score to denote how complete a rewrite
    the change is.

or something like that?