Re: [PATCH] diffcore-pickaxe doc: document -S and -G properly

Ramkumar Ramachandra [off-list ref] writes:

quoted

quoted

+The S kind detects filepairs whose "result" side and "origin" side
+have different number of occurrences of specified string.  While
+rename detection works as usual, 'git log -S' cannot omit commits

The "cannot omit" feels like a confusing double-negative.  How about
"includes" instead?

Intended.  Omission is expected.

I think what makes this paragraph unnecessarily hard to read is the
"While rename works".

With that, you are implying "if you rename a file as a whole without
changing the block of text you identify with the -S parameter, then
such a change is not interesting as far as pickaxe is concerned".
while that statement is logically correct, normal people are not
that generous to read that much between your lines.

I think that is one of the reasons why "If you moved a string from
file A to file B, log -S will flag that change as worth inspecting"
does not seem to logically follow and made Phil find your
description confusing.

Finding such a change indeed is a feature [*1*]; we need to flag
such a change as worth inspecting to find where the code came from
in order to dig deeper, so at least this "cannot omit" should be
"does not omit".


[Footnote]

*1* I suspect that your confusion may stem from not understanding
    what pickaxe was invented for. It is _not_ about finding the
    final answer, but is about stopping at a commit that is worth
    investigating further.  

    It may help to read
    http://article.gmane.org/gmane.comp.version-control.git/217 and
    then its follow-up http://gitster.livejournal.com/35628.html

Junio C Hamano wrote:

I think what makes this paragraph unnecessarily hard to read is the
"While rename works".

With that, you are implying "if you rename a file as a whole without
changing the block of text you identify with the -S parameter, then
such a change is not interesting as far as pickaxe is concerned".
while that statement is logically correct, normal people are not
that generous to read that much between your lines.

Yes, I'm exactly implying that.  But I don't want to lose meaning: in
the previous sentence, I talk about filepairs.  I want to point out
that rename detection working at the filepair level is a perfectly
normal thing.

I think that is one of the reasons why "If you moved a string from
file A to file B, log -S will flag that change as worth inspecting"
does not seem to logically follow and made Phil find your
description confusing.

Sure, we can elaborate a bit more.

Finding such a change indeed is a feature [*1*]; we need to flag
such a change as worth inspecting to find where the code came from
in order to dig deeper, so at least this "cannot omit" should be
"does not omit".

What I was trying to say is that it's an accidental feature: the
reason this "feature" exists is because diffcore is tied to filepairs
(and rename detection works at the filepair level).  You may argue
that there's nothing wrong with this design, but consider what happens
if you rebase on top of a big code move: it's completely broken.  If
git were a true content tracker, and file boundaries really did not
matter, isn't this feature actually a deficiency?

Ofcourse, the user doesn't need to know all this, and "does not omit"
is a good suggestion.