Re: [PATCH v2 3/3] grep docs: describe --no-index further and improve formatting a bit

From: Dragan Simic <dsimic@manjaro.org>
To: Junio C Hamano <gitster@pobox.com>
Cc: git@vger.kernel.org, sunshine@sunshineco.com, jn.avila@free.fr
Subject: Re: [PATCH v2 3/3] grep docs: describe --no-index further and improve formatting a bit
Date: Mon, 25 Mar 2024 20:53:36 +0100	[thread overview]
Message-ID: <d741fe83f01b0a7b19ba5e1871855737@manjaro.org> (raw)
In-Reply-To: <xmqqa5mmjf2f.fsf@gitster.g>

On 2024-03-25 20:18, Junio C Hamano wrote:
> Dragan Simic <dsimic@manjaro.org> writes:
> 
>> +--no-index::
>> +	Search files in the current directory that is not managed by Git,
>> +	or by ignoring that the current directory is managed by Git.  This
>> +	is rather similar to running the regular `grep(1)` utility with its
>> +	`-r` option specified, but with some additional benefits, such as
>> +	using multiple worker threads to speed up searches.
> 
> Sorry for not mentioning this earlier, but I do not think
> multi-threaded grep has to be something we own and others cannot
> implement.  A richer pathspec globbing [*1*] and logical operation
> on match results may be better examples of "additional benefits" if
> we really wanted to mention why people might want to use
> "--no-index" in a directory that is outside Git.

No worries.  Furthermore, multi-threaded searches may actually not
be faster for some workloads, or on some systems (the resulting speed
depends heavily on the I/O speed and available CPU power, which not
all systems have plenty of), so I agree that it's better not to mention
it.  I'll send the v3 with adjusted wording.

> [Footnote]
> 
>  *1* When you want to look for something in files whose name begins
>      with "g" but does not have "rc" in it, you'd do
> 
>      $ git grep --no-index -c . ':(exclude)*rc*' 'g*'
> 
>>  --threads <num>::
>> -	Number of grep worker threads to use.
>> -	See `grep.threads` in 'CONFIGURATION' for more information.
>> +	Number of `grep` worker threads to use, to speed up searches.
>> +	See 'NOTES ON THREADS' and `grep.threads` in 'CONFIGURATION'
>> +	for more information.
> 
> I actually do not think adding ", to speed up searches" is an
> improvement.  But referring to NOTES ON THREADS is a good idea, and
> by reading that NOTES ON THREADS section, readers can tell why it
> sometimes does not speed things up or even slow them down.

Agreed, as noted above.  Will be adjusted in the v3.

> Other than that, looking great.

Nice, that makes me happy. :)