Re: [PATCH 1/3] doc: grep: unify configuration variables definitions

From: Junio C Hamano <gitster@pobox.com>
To: Matheus Tavares <matheus.bernardino@usp.br>
Cc: git@vger.kernel.org
Subject: Re: [PATCH 1/3] doc: grep: unify configuration variables definitions
Date: Thu, 14 Jul 2022 11:46:30 -0700	[thread overview]
Message-ID: <xmqqfsj35y7t.fsf@gitster.g> (raw)
In-Reply-To: <439cfdf858f5b1917ae7ca3ca327bb33b42f71c7.1657819649.git.matheus.bernardino@usp.br> (Matheus Tavares's message of "Thu, 14 Jul 2022 14:44:02 -0300")

Matheus Tavares <matheus.bernardino@usp.br> writes:

> The configuration variables for git-grep are duplicated in
> "Documentation/git-grep.txt" and "Documentation/config/grep.txt", which
> gqcan make maintenance difficult. The first also contains a definition

gqcan?

> that is not present in the latter (grep.fullName), and the latter
> received a wording improvement that was not replicated in the former:
> see 91028f765 ("grep: clarify what `grep.patternType=default` means",
> 2021-12-05).
>
> To avoid such problems, unify the information in one file and include it
> in the other.

OK.

> Signed-off-by: Matheus Tavares <matheus.bernardino@usp.br>
> ---
>  Documentation/config/grep.txt | 10 ++++++++--
>  Documentation/git-grep.txt    | 37 ++++++-----------------------------
>  2 files changed, 14 insertions(+), 33 deletions(-)
>
> diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt
> index 182edd813a..6996e64574 100644
> --- a/Documentation/config/grep.txt
> +++ b/Documentation/config/grep.txt
> @@ -17,8 +17,14 @@ grep.extendedRegexp::
>  	other than 'default'.
>  
>  grep.threads::
> -	Number of grep worker threads to use.
> -	See `grep.threads` in linkgit:git-grep[1] for more information.
> +	Number of grep worker threads to use. See `--threads`
> +ifndef::git-grep[]
> +	in linkgit:git-grep[1]
> +endif::git-grep[]
> +	for more information.
> +
> +grep.fullName::
> +	If set to true, enable `--full-name` option by default.

All of the above makes sense.

>  --threads <num>::
> -	Number of grep worker threads to use.
> -	See `grep.threads` in 'CONFIGURATION' for more information.
> +	Number of grep worker threads to use. If not provided (or set to
> +	0), Git will use as many worker threads as the number of logical
> +	cores available. The default value can also be set with the
> +	`grep.threads` configuration.

This change is clearly outside of the "unify 'git config --help' and
'git grep --help'" theme, isn't it?

I wonder if you want to leave this untouched, and instead put more
work and words in the description of grep.threads in the other file?