Re: [PATCH] doc: clarify how -S works

Jeff King [off-list ref] writes:

I wonder if "gitdiffcore" is a little scary for new people who just want
to use "-S", but hopefully point (1) above will get rid of most of the
confusion, and those who follow the link want to learn all about diff.

As I mentioned in the other message, what --pickaxe achieves is very
different from what people would naturally want from --search, an
option that does not exist.

I do not mind a patch that adds a diffcore transformation that internally
generates a diff and searches the string given by the user in it, and
triggers that with --search option.  The transformation should come just
after (or before) the pickaxe in the call sequence inside diffcore_std();
name it diffcore_search() or something.

In retrospect, because --pickaxe was designed primarily for Porcelain use,
it was a mistake for it to have taken a short-and-sweet -S synonym.

Look for differences that change the number of occurrences of <string>?

On Tue, Mar 03, 2009 at 08:42:12AM -0800, Junio C Hamano wrote:

In retrospect, because --pickaxe was designed primarily for Porcelain use,
it was a mistake for it to have taken a short-and-sweet -S synonym.

Hmm. I actually like the pickaxe behavior and find it useful for
searching. IOW, I consider it a porcelain feature, just perhaps not the
one that some people are expecting.

quoted

 -S<string>::
-	Look for differences that contain the change in <string>.
+	Look for differences that introduce or remove an instance of
+	<string>. Note that this is different than the string simply
+	appearing in diff output; see the 'pickaxe' entry in
+	linkgit:gitdiffcore[7] for more details.

Look for differences that change the number of occurrences of <string>?

Yes, that is technically correct. I was trying to find a wording that
was a little less "this is literally what it does" and more "this is
what you might find it useful for".

But I don't care overly much; I just think what was there was quite
misleading. And I've already provided my paint color, so feel free to
apply mine, use what you wrote above, or whatever. Just don't leave it
as-is. ;)

-Peff

2009/3/3 Jeff King [off-list ref]:

On Tue, Mar 03, 2009 at 08:42:12AM -0800, Junio C Hamano wrote:

quoted

In retrospect, because --pickaxe was designed primarily for Porcelain use,
it was a mistake for it to have taken a short-and-sweet -S synonym.

Hmm. I actually like the pickaxe behavior and find it useful for
searching. IOW, I consider it a porcelain feature, just perhaps not the
one that some people are expecting.

quoted

quoted

 -S<string>::
-   Look for differences that contain the change in <string>.
+   Look for differences that introduce or remove an instance of
+   <string>. Note that this is different than the string simply
+   appearing in diff output; see the 'pickaxe' entry in
+   linkgit:gitdiffcore[7] for more details.

Look for differences that change the number of occurrences of <string>?

Yes, that is technically correct. I was trying to find a wording that
was a little less "this is literally what it does" and more "this is
what you might find it useful for".

Is there any way to have an option to also match any line containing
the string?  That might be the best way to document it, as well as
being very useful:

-s<string>
   Look for any additions, removals or changes in any line containing <string>
-S<string>
   Look only for any additions or removals of the <string> in any line

John

On Tue, Mar 03, 2009 at 05:39:38PM +0000, John Tapsell wrote:

quoted

Yes, that is technically correct. I was trying to find a wording that
was a little less "this is literally what it does" and more "this is
what you might find it useful for".

Is there any way to have an option to also match any line containing
the string?  That might be the best way to document it, as well as
being very useful:

-s<string>
   Look for any additions, removals or changes in any line containing <string>
-S<string>
   Look only for any additions or removals of the <string> in any line

Yes, that would be possible (though it is still not foolproof against
moves, as I mentioned elsewhere), and I think it would be simple to
explain the two together.  It just needs somebody to code it.

Unfortunately "-s" is already taken for "no output".

-Peff