From: Junio C Hamano Date: Tue, 14 May 2013 19:19:08 GMT Subject: Re: [PATCH] diffcore-pickaxe doc: document -S and -G properly Message-ID: <7vppwtid3n.fsf@alter.siamese.dyndns.org> In-Reply-To: Ramkumar Ramachandra 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