[v2,4/8] grep docs: de-duplicate configuration sections

Commit Message

Ævar Arnfjörð Bjarmason Nov. 10, 2021, 1:43 a.m. UTC

Include the "config/grep.txt" file in "git-grep.txt", instead of
repeating an almost identical description of the "grep" configuration
variables in two places. In a subsequent commit we'll amend this
documentation, and can now do so in one place instead of two.

Let's also add a short blurb at the top indicating that this is
included documentation, so users won't think that they need to read
the two versions and compare them.

That wording is copy/pasted from the change I made in b6a8d09f6d8 (gc
docs: include the "gc.*" section from "config" in "gc", 2019-04-07),
eventually we'll want to include this via template, and indeed this
change is extracted from a WIP series that fixes all these
"CONFIGURATION" includes which does that. But doing that would require
build system changes, so let's punt on it for now.

There is no loss of information here that isn't shown in the addition
to "grep.txt". This change was made by copying the contents of
"git-grep.txt"'s version over the "grep.txt" version. Aside from the
change "grep.txt" being made here the two were identical.

This documentation started being copy/pasted around in
b22520a37c8 (grep: allow -E and -n to be turned on by default via
configuration, 2011-03-30). After that in e.g. 6453f7b3486 (grep: add
grep.fullName config variable, 2014-03-17) they started drifting
apart, with only grep.fullName being described in the command
documentation.

In 434e6e753fe (config.txt: move grep.* to a separate file,
2018-10-27) we gained the include, but didn't do this next step, let's
do it now.

Signed-off-by: Ævar Arnfjörð Bjarmason <[e-mail]>
---
 Documentation/config/grep.txt |  7 +++++--
 Documentation/git-grep.txt    | 30 +++---------------------------
 2 files changed, 8 insertions(+), 29 deletions(-)

Comments

Junio C Hamano Nov. 12, 2021, 5:15 p.m. UTC | #1

Ævar Arnfjörð Bjarmason  <[e-mail]> writes:

> Include the "config/grep.txt" file in "git-grep.txt", instead of
> repeating an almost identical description of the "grep" configuration
> variables in two places. In a subsequent commit we'll amend this
> documentation, and can now do so in one place instead of two.

Good find.  They are indeed almost identical.  I am not sure about
the value of ...

> +The below documentation is the same as what's found in
> +linkgit:git-config[1]:

... when everybody becomes consistent, but in the meantime, while
some documentation pages are consistent while others are not, I can
see how it might help.

The patch looks good.

Thanks.

Patch

diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt
index 44abe45a7ca..ae51f2d91c8 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. 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
diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt
index 3d393fbac1b..29d5ce04f5a 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -334,34 +334,10 @@  performance in this case, it might be desirable to use `--threads=1`.
 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.
+The below documentation is the same as what's found in
+linkgit:git-config[1]:
 
+include::config/grep.txt[]
 
 GIT
 ---