Re: [PATCH v5 05/10] docs: gitdiffcore: -G and -S: Use regex/string placeholders

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

Illia Bobyr <illia.bobyr@gmail.com> writes:

Show 12 quoted lines

> In the rest of the documentation (and in the code) we use `regex` and
> `string` as `-G` and `-S` argument placeholders.  While
> `regular-expression` and `block-of-text` are a bit easier to read, it is
> a bit consistent.
>
> And we could assume that everyone who uses git should be able to
> understand that a "string" and a "block-of-text", as well as a "regex"
> and "regular-expression" are the same thing.  So, using a shorter
> version is also more consistent.
> ---
>  Documentation/gitdiffcore.txt | 23 +++++++++++------------
>  1 file changed, 11 insertions(+), 12 deletions(-)

I am with one reservation. <block-of-text> was written to stress the fact that most of the time the string is expected to be a multi-line block of text (like a function body) [*1*] that is unique within the codebase. I do not think replacing a short-and-sweet <string> with <block-of-text> is a good idea, but if we are to go this route, we should mention that to compensate for the diminished stress on that block-ness of the text, as <string> would imply something quite short and would fit on a single line.

[Footnote]

*1* Go back to Linus's message I cited earlier;
    https://lore.kernel.org/git/Pine.LNX.4.58.0504150753440.7211@ppc970.osdl.org/