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

From: Junio C Hamano <gitster@pobox.com>
Date: May 14, 2013, 19:19 UTC
Message-ID: <7vppwtid3n.fsf@alter.siamese.dyndns.org>
In-Reply-To: <CALkWK0nR1=Pgv0AY78p7n17C-VVvbc6BfJ4y_Df1ciZoc-xR-Q@mail.gmail.com>

Ramkumar Ramachandra <artagnon@gmail.com> writes:

Show 8 quoted lines

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