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

[Junio C Hamano <gitster@pobox.com>]

Ramkumar Ramachandra <artagnon@gmail.com> writes:

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