Subject: Re: [PATCH v5 03/10] diff: short help: Correct -S description

From: Junio C Hamano <[email-masked]>
Date: Wed, 12 Feb 2025 20:26:16 -0800

Illia Bobyr <[email-masked]> writes:

> `-S` shows changes that modify the number of occurrences of the
> specified string, rather than only those that either completely remove
> it or add it for the first time.
> ---

[jc: title, sign-off, and this should be done outside the main topic
are shared with other patches, so I won't repeat them]

>  diff.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/diff.h b/diff.h
> index 0a566f..49ece3 100644
> --- a/diff.h
> +++ b/diff.h
> @@ -606,7 +606,7 @@ void diffcore_fix_diff_index(void);
>  "                try unchanged files as candidate for copy detection.\n" \
>  "  -l<n>         limit rename attempts up to <n> paths.\n" \
>  "  -O<file>      reorder diffs according to the <file>.\n" \
> -"  -S<string>    find filepair whose only one side contains the string.\n" \
> +"  -S<string>    find filepair who differ in the number of occurrences of string.\n" \

Given that the initial motivation of -S<block-of-text> was to find
"before it wasn't there in that shape, now there it is" [*1*] (and
<block-of-text> wasn meant to be something unique in the codebase),
the original conveys the intent better, but the updated text
describes the actual behaviour more correctly (in other words, the
behaviour of the option when a not-so-unique string that may produce
multiple hits is given is whatever it happens to do---which is "see
the number of occurrences are different").

So this is a good change.

[Foornote]

 *1* The original motivation of "-S<block-of-text>" was to be a
     building block for the tool Linus dreamed in his message
     https://lore.kernel.org/git/[email-masked]
     that explained why recording renames at the commit time is a
     bad idea.

>  "  --pickaxe-all\n" \
>  "                show all files diff when -S is used and hit is found.\n" \
>  "  -a  --text    treat all files as text.\n"