[RFC,1/3] doc: grep: unify info on configuration variables
diff mbox series

Message ID 7ba5caf10de75a2e0909318b04c62f5827a3fa56.1585027716.git.matheus.bernardino@usp.br
State New
Headers show
Series
  • grep: honor sparse checkout and add option to ignore it
Related show

Commit Message

Matheus Tavares Bernardino March 24, 2020, 6:11 a.m. UTC
Explanations about the configuration variables for git-grep are
duplicated in "Documentation/git-grep.txt" and
"Documentation/config/grep.txt". Let's unify the information in the
second file and include it in the first.

Signed-off-by: Matheus Tavares <matheus.bernardino@usp.br>
---
 Documentation/config/grep.txt |  7 +++++--
 Documentation/git-grep.txt    | 35 +++++------------------------------
 2 files changed, 10 insertions(+), 32 deletions(-)

Comments

Elijah Newren March 24, 2020, 7:57 a.m. UTC | #1
On Mon, Mar 23, 2020 at 11:11 PM Matheus Tavares
<matheus.bernardino@usp.br> wrote:
>
> Explanations about the configuration variables for git-grep are
> duplicated in "Documentation/git-grep.txt" and
> "Documentation/config/grep.txt". Let's unify the information in the
> second file and include it in the first.
>
> Signed-off-by: Matheus Tavares <matheus.bernardino@usp.br>
> ---
>  Documentation/config/grep.txt |  7 +++++--
>  Documentation/git-grep.txt    | 35 +++++------------------------------
>  2 files changed, 10 insertions(+), 32 deletions(-)
>
> diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt
> index 44abe45a7c..76689771aa 100644
> --- a/Documentation/config/grep.txt
> +++ b/Documentation/config/grep.txt
> @@ -16,8 +16,11 @@ 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` in
> +       linkgit:git-grep[1] for more information.
> +
> +grep.fullName::
> +       If set to true, enable `--full-name` option by default.
>
>  grep.fallbackToNoIndex::
>         If set to true, fall back to git grep --no-index if git grep
> diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
> index ddb6acc025..97e25d7b1b 100644
> --- a/Documentation/git-grep.txt
> +++ b/Documentation/git-grep.txt
> @@ -41,34 +41,7 @@ characters.  An empty string as search expression matches all lines.
>  CONFIGURATION
>  -------------
>
> -grep.lineNumber::
> -       If set to true, enable `-n` option by default.
> -
> -grep.column::
> -       If set to true, enable the `--column` option by default.
> -
> -grep.patternType::
> -       Set the default matching behavior. Using a value of 'basic', 'extended',
> -       'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,
> -       `--fixed-strings`, or `--perl-regexp` option accordingly, while the
> -       value 'default' will return to the default matching behavior.
> -
> -grep.extendedRegexp::
> -       If set to true, enable `--extended-regexp` option by default. This
> -       option is ignored when the `grep.patternType` option is set to a value
> -       other than 'default'.
> -
> -grep.threads::
> -       Number of grep worker threads to use. If unset (or set to 0), Git will
> -       use as many threads as the number of logical cores available.
> -
> -grep.fullName::
> -       If set to true, enable `--full-name` option by default.
> -
> -grep.fallbackToNoIndex::
> -       If set to true, fall back to git grep --no-index if git grep
> -       is executed outside of a git repository.  Defaults to false.
> -
> +include::config/grep.txt[]
>
>  OPTIONS
>  -------
> @@ -267,8 +240,10 @@ providing this option will cause it to die.
>         found.
>
>  --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 (see linkgit:git-config[1]).

I'm possibly showing my ignorance here, but doesn't the
"include::config/grep.txt[]" you added above mean that the user
doesn't have to see an external manpage but can see the definition
earlier within this same manpage?

>
>  -f <file>::
>         Read patterns from <file>, one per line.
> --
> 2.25.1
>
Junio C Hamano March 24, 2020, 9:26 p.m. UTC | #2
Elijah Newren <newren@gmail.com> writes:

>> diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt
>> index 44abe45a7c..76689771aa 100644
>> --- a/Documentation/config/grep.txt
>> +++ b/Documentation/config/grep.txt
>> @@ -16,8 +16,11 @@ grep.extendedRegexp::
>> ...
>> +       Number of grep worker threads to use. See `--threads` in
>> +       linkgit:git-grep[1] for more information.
>> ...
>> diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
>> index ddb6acc025..97e25d7b1b 100644
>> --- a/Documentation/git-grep.txt
>> +++ b/Documentation/git-grep.txt
>> @@ -41,34 +41,7 @@ characters.  An empty string as search expression matches all lines.
>> ...
>> +include::config/grep.txt[]
>> ...
>>  --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 (see linkgit:git-config[1]).
>
> I'm possibly showing my ignorance here, but doesn't the
> "include::config/grep.txt[]" you added above mean that the user
> doesn't have to see an external manpage but can see the definition
> earlier within this same manpage?

I think so.  Also, the new reference "See `--threads` in git-grep"
added to grep.threads to config/grep.txt would become somewhat
redundant in the context of "git grep --help" (only "See --threads"
is relevant when it appears in this same manual page).

Readers who finds the reference in "git config --help" still needs
to see that --threads is an option to git-grep, though.
Matheus Tavares Bernardino March 24, 2020, 11:38 p.m. UTC | #3
On Tue, Mar 24, 2020 at 6:26 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Elijah Newren <newren@gmail.com> writes:
>
> >> diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt
> >> index 44abe45a7c..76689771aa 100644
> >> --- a/Documentation/config/grep.txt
> >> +++ b/Documentation/config/grep.txt
> >> @@ -16,8 +16,11 @@ grep.extendedRegexp::
> >> ...
> >> +       Number of grep worker threads to use. See `--threads` in
> >> +       linkgit:git-grep[1] for more information.
> >> ...
> >> diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
> >> index ddb6acc025..97e25d7b1b 100644
> >> --- a/Documentation/git-grep.txt
> >> +++ b/Documentation/git-grep.txt
> >> @@ -41,34 +41,7 @@ characters.  An empty string as search expression matches all lines.
> >> ...
> >> +include::config/grep.txt[]
> >> ...
> >>  --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 (see linkgit:git-config[1]).
> >
> > I'm possibly showing my ignorance here, but doesn't the
> > "include::config/grep.txt[]" you added above mean that the user
> > doesn't have to see an external manpage but can see the definition
> > earlier within this same manpage?

You are right. I added the "(see linkgit:git-config[1])" here more as a
reference to the config system itself (for a user that is possibly not familiar
with git-config). But if this is not necessary, we can remove the reference.

> I think so.  Also, the new reference "See `--threads` in git-grep"
> added to grep.threads to config/grep.txt would become somewhat
> redundant in the context of "git grep --help" (only "See --threads"
> is relevant when it appears in this same manual page).

Thanks for pointing that out. I think we can solve this issue with the
following:

diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt
index c1d49484c8..ac06db4206 100644
--- a/Documentation/config/grep.txt
+++ b/Documentation/config/grep.txt
@@ -16,8 +16,11 @@ grep.extendedRegexp::
 	other than 'default'.

 grep.threads::
-	Number of grep worker threads to use. See `--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.
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 5c5c66c056..192aab4cba 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -41,6 +41,7 @@ characters.  An empty string as search expression matches all lines.
 CONFIGURATION
 -------------

+:git-grep: 1
 include::config/grep.txt[]

 OPTIONS

I will add these changes in v2.

Patch
diff mbox series

diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt
index 44abe45a7c..76689771aa 100644
--- a/Documentation/config/grep.txt
+++ b/Documentation/config/grep.txt
@@ -16,8 +16,11 @@  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` in
+	linkgit:git-grep[1] for more information.
+
+grep.fullName::
+	If set to true, enable `--full-name` option by default.
 
 grep.fallbackToNoIndex::
 	If set to true, fall back to git grep --no-index if git grep
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index ddb6acc025..97e25d7b1b 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -41,34 +41,7 @@  characters.  An empty string as search expression matches all lines.
 CONFIGURATION
 -------------
 
-grep.lineNumber::
-	If set to true, enable `-n` option by default.
-
-grep.column::
-	If set to true, enable the `--column` option by default.
-
-grep.patternType::
-	Set the default matching behavior. Using a value of 'basic', 'extended',
-	'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,
-	`--fixed-strings`, or `--perl-regexp` option accordingly, while the
-	value 'default' will return to the default matching behavior.
-
-grep.extendedRegexp::
-	If set to true, enable `--extended-regexp` option by default. This
-	option is ignored when the `grep.patternType` option is set to a value
-	other than 'default'.
-
-grep.threads::
-	Number of grep worker threads to use. If unset (or set to 0), Git will
-	use as many threads as the number of logical cores available.
-
-grep.fullName::
-	If set to true, enable `--full-name` option by default.
-
-grep.fallbackToNoIndex::
-	If set to true, fall back to git grep --no-index if git grep
-	is executed outside of a git repository.  Defaults to false.
-
+include::config/grep.txt[]
 
 OPTIONS
 -------
@@ -267,8 +240,10 @@  providing this option will cause it to die.
 	found.
 
 --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 (see linkgit:git-config[1]).
 
 -f <file>::
 	Read patterns from <file>, one per line.