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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 13, 2025, 04:26 UTC
Message-ID: <xmqqzfiqpj13.fsf@gitster.g>
In-Reply-To: <20250212032657.1807939-4-illia.bobyr@gmail.com>

Illia Bobyr <illia.bobyr@gmail.com> 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]

Show 13 quoted lines

>  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/Pine.LNX.4.58.0504150753440.7211@ppc970.osdl.org
     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"