@matheusbsbs / matheus-bagliano / commits / 18d89fe25c

docs: add and use include template for config/* includes

In b6a8d09f6d8 (gc docs: include the "gc.*" section from "config" in "gc", 2019-04-07) the "git gc" documentation was made to include the config/gc.txt in its "CONFIGURATION" section. We do that in several other places, but "git gc" was the only one with a blurb above the include to orient the reader. We don't want readers to carefully scrutinize "git-config(1)" and "git-gc(1)" looking for discrepancies, instead we should tell them that the latter includes a part of the former. This change formalizes that wording in two new templates to be included, one for the "git gc" case where the entire section is included from "git-config(1)", and another for when the inclusion of "git-config(1)" follows discussion unique to that documentation. In order to use that re-arrange the order of those being discussed in the "git-merge(1)" documentation. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Reviewed-by: Matheus Tavares <matheus.bernardino@usp.br> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Ævar Arnfjörð Bjarmason committed Sep 7, 2022 at 10:26 UTC 18d89fe25c80de269e8c6d14213ff400bc480e96
9 files changed +21 -3
Documentation/Makefile
+1
@@ -51,6 +51,7 @@ HOWTO_TXT += $(wildcard howto/*.txt)
51
52 DOC_DEP_TXT += $(wildcard *.txt)
53 DOC_DEP_TXT += $(wildcard config/*.txt)
54 +DOC_DEP_TXT += $(wildcard includes/*.txt)
55
56 ifdef MAN_FILTER
57 MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))
Documentation/git-fsck.txt
+2
@@ -107,6 +107,8 @@ care about this output and want to speed it up further.
107 CONFIGURATION
108 -------------
109
110 +include::includes/cmd-config-section-all.txt[]
111 +
112 include::config/fsck.txt[]
113
114 DISCUSSION
Documentation/git-gc.txt
+1 -2
@@ -110,8 +110,7 @@ users and their repositories.
110 CONFIGURATION
111 -------------
112
113 -The below documentation is the same as what's found in
114 -linkgit:git-config[1]:
113 +include::includes/cmd-config-section-all.txt[]
114
115 include::config/gc.txt[]
116
Documentation/git-imap-send.txt
+2
@@ -54,6 +54,8 @@ CONFIGURATION
54 To use the tool, `imap.folder` and either `imap.tunnel` or `imap.host` must be set
55 to appropriate values.
56
57 +include::includes/cmd-config-section-rest.txt[]
58 +
59 include::config/imap.txt[]
60
61 EXAMPLES
Documentation/git-merge.txt
+4 -1
@@ -386,13 +386,16 @@ include::merge-strategies.txt[]
386
387 CONFIGURATION
388 -------------
389 -include::config/merge.txt[]
389
390 branch.<name>.mergeOptions::
391 Sets default options for merging into branch <name>. The syntax and
392 supported options are the same as those of 'git merge', but option
393 values containing whitespace characters are currently not supported.
394
395 +include::includes/cmd-config-section-rest.txt[]
396 +
397 +include::config/merge.txt[]
398 +
399 SEE ALSO
400 --------
401 linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
Documentation/git-mergetool.txt
+3
@@ -102,6 +102,9 @@ success of the resolution after the custom tool has exited.
102 CONFIGURATION
103 -------------
104 :git-mergetool: 1
105 +
106 +include::includes/cmd-config-section-all.txt[]
107 +
108 include::config/mergetool.txt[]
109
110 TEMPORARY FILES
Documentation/git-rebase.txt
+2
@@ -1252,6 +1252,8 @@ merge cmake
1252 CONFIGURATION
1253 -------------
1254
1255 +include::includes/cmd-config-section-all.txt[]
1256 +
1257 include::config/rebase.txt[]
1258 include::config/sequencer.txt[]
1259
Documentation/includes/cmd-config-section-all.txt new
+3
@@ -0,0 +1,3 @@
1 +Everything below this line in this section is selectively included
2 +from the linkgit:git-config[1] documentation. The content is the same
3 +as what's found there:
Documentation/includes/cmd-config-section-rest.txt new
+3
@@ -0,0 +1,3 @@
1 +Everything above this line in this section isn't included from the
2 +linkgit:git-config[1] documentation. The content that follows is the
3 +same as what's found there: