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

[John Tapsell <johnflux@gmail.com>]

2009/3/3 Jeff King <peff@peff.net>:
> The existing text was very vague about what exactly it means
> for difference to "contain" a change. This seems to cause
> confusion on the mailing list every month or two.
>
> To fix it we:
>
>  1. use "introduce or remove an instance of" instead of
>     "contain"

I would read this to mean that it doesn't include modifying a line
containing that string.  But I also know that underneath the hood, a
change is a remove then an addition, so I would be confused :)

What about saying "modifies" rather than "contain" ?

>
>  2. point the user to gitdiffcore(7), which contains a more
>     complete explanation
>
> Signed-off-by: Jeff King <peff@peff.net>
> ---
> 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.
>
>  Documentation/diff-options.txt |    5 ++++-
>  1 files changed, 4 insertions(+), 1 deletions(-)
>
> diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt
> index 813a7b1..9276fae 100644
> --- a/Documentation/diff-options.txt
> +++ b/Documentation/diff-options.txt
> @@ -176,7 +176,10 @@ override configuration settings.
>        number.
>
>  -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.
>
>  --pickaxe-all::
>        When -S finds a change, show all the changes in that
> --
> 1.6.2.rc2.330.gba39e
>
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>