From 18d89fe25c80de269e8c6d14213ff400bc480e96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Wed, 7 Sep 2022 10:26:57 +0200 Subject: [PATCH] docs: add and use include template for config/* includes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Reviewed-by: Matheus Tavares Signed-off-by: Junio C Hamano --- Documentation/Makefile | 1 + Documentation/git-fsck.txt | 2 ++ Documentation/git-gc.txt | 3 +-- Documentation/git-imap-send.txt | 2 ++ Documentation/git-merge.txt | 5 ++++- Documentation/git-mergetool.txt | 3 +++ Documentation/git-rebase.txt | 2 ++ Documentation/includes/cmd-config-section-all.txt | 3 +++ Documentation/includes/cmd-config-section-rest.txt | 3 +++ 9 files changed, 21 insertions(+), 3 deletions(-) create mode 100644 Documentation/includes/cmd-config-section-all.txt create mode 100644 Documentation/includes/cmd-config-section-rest.txt diff --git a/Documentation/Makefile b/Documentation/Makefile index 4f801f4e4c..85b2088b88 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -51,6 +51,7 @@ HOWTO_TXT += $(wildcard howto/*.txt) DOC_DEP_TXT += $(wildcard *.txt) DOC_DEP_TXT += $(wildcard config/*.txt) +DOC_DEP_TXT += $(wildcard includes/*.txt) ifdef MAN_FILTER MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)) diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index 5088783dcc..29318ea957 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -107,6 +107,8 @@ care about this output and want to speed it up further. CONFIGURATION ------------- +include::includes/cmd-config-section-all.txt[] + include::config/fsck.txt[] DISCUSSION diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 0af7540a0c..a65c9aa62d 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -110,8 +110,7 @@ users and their repositories. CONFIGURATION ------------- -The below documentation is the same as what's found in -linkgit:git-config[1]: +include::includes/cmd-config-section-all.txt[] include::config/gc.txt[] diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt index 63cf498ce9..f7b1851514 100644 --- a/Documentation/git-imap-send.txt +++ b/Documentation/git-imap-send.txt @@ -54,6 +54,8 @@ CONFIGURATION To use the tool, `imap.folder` and either `imap.tunnel` or `imap.host` must be set to appropriate values. +include::includes/cmd-config-section-rest.txt[] + include::config/imap.txt[] EXAMPLES diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 3125473cc1..6e5db8ef4c 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -386,13 +386,16 @@ include::merge-strategies.txt[] CONFIGURATION ------------- -include::config/merge.txt[] branch..mergeOptions:: Sets default options for merging into branch . The syntax and supported options are the same as those of 'git merge', but option values containing whitespace characters are currently not supported. +include::includes/cmd-config-section-rest.txt[] + +include::config/merge.txt[] + SEE ALSO -------- linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1], diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index f784027bc1..c44e205629 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -102,6 +102,9 @@ success of the resolution after the custom tool has exited. CONFIGURATION ------------- :git-mergetool: 1 + +include::includes/cmd-config-section-all.txt[] + include::config/mergetool.txt[] TEMPORARY FILES diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index a872ab0fbd..d9b6af8a57 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -1252,6 +1252,8 @@ merge cmake CONFIGURATION ------------- +include::includes/cmd-config-section-all.txt[] + include::config/rebase.txt[] include::config/sequencer.txt[] diff --git a/Documentation/includes/cmd-config-section-all.txt b/Documentation/includes/cmd-config-section-all.txt new file mode 100644 index 0000000000..296a239f2a --- /dev/null +++ b/Documentation/includes/cmd-config-section-all.txt @@ -0,0 +1,3 @@ +Everything below this line in this section is selectively included +from the linkgit:git-config[1] documentation. The content is the same +as what's found there: diff --git a/Documentation/includes/cmd-config-section-rest.txt b/Documentation/includes/cmd-config-section-rest.txt new file mode 100644 index 0000000000..b1e7682c1d --- /dev/null +++ b/Documentation/includes/cmd-config-section-rest.txt @@ -0,0 +1,3 @@ +Everything above this line in this section isn't included from the +linkgit:git-config[1] documentation. The content that follows is the +same as what's found there: