* [PATCH v2 1/9] docs: add and use include template for config/* includes
2022-07-29 8:25 ` [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Ævar Arnfjörð Bjarmason
@ 2022-07-29 8:25 ` Ævar Arnfjörð Bjarmason
2022-07-30 13:29 ` Matheus Tavares
2022-07-29 8:25 ` [PATCH v2 2/9] grep docs: de-duplicate configuration sections Ævar Arnfjörð Bjarmason
` (9 subsequent siblings)
10 siblings, 1 reply; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-29 8:25 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
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>
---
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 4f801f4e4c9..85b2088b888 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 5088783dccb..29318ea957e 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 0af7540a0c8..a65c9aa62d6 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 63cf498ce9f..f7b18515141 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 3125473cc1d..6e5db8ef4c5 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.<name>.mergeOptions::
Sets default options for merging into branch <name>. 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 f784027bc13..c44e205629b 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 a872ab0fbd1..d9b6af8a571 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 00000000000..296a239f2ab
--- /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 00000000000..fe4721dac76
--- /dev/null
+++ b/Documentation/includes/cmd-config-section-rest.txt
@@ -0,0 +1,3 @@
+The discussion above this line is unique to this documentation, but
+everything below is included from section(s) in linkgit:git-config[1]
+aplicable to this command:
--
2.37.1.1196.g8af3636bc64
^ permalink raw reply related [flat|nested] 56+ messages in thread
* Re: [PATCH v2 1/9] docs: add and use include template for config/* includes
2022-07-29 8:25 ` [PATCH v2 1/9] docs: add and use include template for config/* includes Ævar Arnfjörð Bjarmason
@ 2022-07-30 13:29 ` Matheus Tavares
0 siblings, 0 replies; 56+ messages in thread
From: Matheus Tavares @ 2022-07-30 13:29 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Junio C Hamano
On Fri, Jul 29, 2022 at 5:25 AM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index 3125473cc1d..6e5db8ef4c5 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.<name>.mergeOptions::
> Sets default options for merging into branch <name>. 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[]
This will say that "everything above this line is unique to this
documentation", but `branch.<name>.mergeOptions` is in git-config(1)
with the same wording that it appears here (coming from
config/branch.txt).
Nevertheless, I'm not sure if it is worth moving this definition to a
separate file, to be included by both git-merge(1) and
git-config(1)...
> +
> +include::config/merge.txt[]
> +
> SEE ALSO
> --------
> linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],
^ permalink raw reply [flat|nested] 56+ messages in thread
* [PATCH v2 2/9] grep docs: de-duplicate configuration sections
2022-07-29 8:25 ` [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Ævar Arnfjörð Bjarmason
2022-07-29 8:25 ` [PATCH v2 1/9] docs: add and use include template for config/* includes Ævar Arnfjörð Bjarmason
@ 2022-07-29 8:25 ` Ævar Arnfjörð Bjarmason
2022-07-30 13:31 ` Matheus Tavares
2022-07-29 8:25 ` [PATCH v2 3/9] send-email " Ævar Arnfjörð Bjarmason
` (8 subsequent siblings)
10 siblings, 1 reply; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-29 8:25 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
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.
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 <avarab@gmail.com>
---
Documentation/config/grep.txt | 7 +++++--
Documentation/git-grep.txt | 29 ++---------------------------
2 files changed, 7 insertions(+), 29 deletions(-)
diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt
index 182edd813a5..e521f20390c 100644
--- a/Documentation/config/grep.txt
+++ b/Documentation/config/grep.txt
@@ -17,8 +17,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 58d944bd578..dabdbe8471d 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -343,34 +343,9 @@ 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.
+include::includes/cmd-config-section-all.txt[]
+include::config/grep.txt[]
GIT
---
--
2.37.1.1196.g8af3636bc64
^ permalink raw reply related [flat|nested] 56+ messages in thread
* Re: [PATCH v2 2/9] grep docs: de-duplicate configuration sections
2022-07-29 8:25 ` [PATCH v2 2/9] grep docs: de-duplicate configuration sections Ævar Arnfjörð Bjarmason
@ 2022-07-30 13:31 ` Matheus Tavares
0 siblings, 0 replies; 56+ messages in thread
From: Matheus Tavares @ 2022-07-30 13:31 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Junio C Hamano
On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
> 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.
>
> 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 <avarab@gmail.com>
> ---
> Documentation/config/grep.txt | 7 +++++--
> Documentation/git-grep.txt | 29 ++---------------------------
> 2 files changed, 7 insertions(+), 29 deletions(-)
LGTM. (And more elegant than my previous solution :)
^ permalink raw reply [flat|nested] 56+ messages in thread
* [PATCH v2 3/9] send-email docs: de-duplicate configuration sections
2022-07-29 8:25 ` [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Ævar Arnfjörð Bjarmason
2022-07-29 8:25 ` [PATCH v2 1/9] docs: add and use include template for config/* includes Ævar Arnfjörð Bjarmason
2022-07-29 8:25 ` [PATCH v2 2/9] grep docs: de-duplicate configuration sections Ævar Arnfjörð Bjarmason
@ 2022-07-29 8:25 ` Ævar Arnfjörð Bjarmason
2022-07-30 13:45 ` Matheus Tavares
2022-07-29 8:25 ` [PATCH v2 4/9] apply " Ævar Arnfjörð Bjarmason
` (7 subsequent siblings)
10 siblings, 1 reply; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-29 8:25 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
De-duplicate the discussion of "send-email" configuration, such that
the "git-config(1)" manual page becomes the source of truth, and
"git-send-email(1)" includes the relevant part.
Most commands that suffered from such duplication had diverging text
discussing the same variables, but in this case some config was also
only discussed in one or the other.
This is mostly a move-only change, the exception is a minor rewording
of changing wording like "see above" to "see linkgit:git-config[1]",
as well as a clarification about the big section of command-line
option tweaking config being discussed in git-send-email(1)'s main
docs.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/config/sendemail.txt | 40 +++++++++++++++++++++++++++---
Documentation/git-send-email.txt | 36 ++-------------------------
2 files changed, 39 insertions(+), 37 deletions(-)
diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt
index 50baa5d6bfb..51da7088a84 100644
--- a/Documentation/config/sendemail.txt
+++ b/Documentation/config/sendemail.txt
@@ -18,17 +18,49 @@ sendemail.<identity>.*::
identity is selected, through either the command-line or
`sendemail.identity`.
+sendemail.multiEdit::
+ If true (default), a single editor instance will be spawned to edit
+ files you have to edit (patches when `--annotate` is used, and the
+ summary when `--compose` is used). If false, files will be edited one
+ after the other, spawning a new editor each time.
+
+sendemail.confirm::
+ Sets the default for whether to confirm before sending. Must be
+ one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`
+ in the linkgit:git-send-email[1] documentation for the meaning of these
+ values.
+
sendemail.aliasesFile::
+ To avoid typing long email addresses, point this to one or more
+ email aliases files. You must also supply `sendemail.aliasFileType`.
+
sendemail.aliasFileType::
+ Format of the file(s) specified in sendemail.aliasesFile. Must be
+ one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.
++
+What an alias file in each format looks like can be found in
+the documentation of the email program of the same name. The
+differences and limitations from the standard formats are
+described below:
++
+--
+sendmail;;
+* Quoted aliases and quoted addresses are not supported: lines that
+ contain a `"` symbol are ignored.
+* Redirection to a file (`/path/name`) or pipe (`|command`) is not
+ supported.
+* File inclusion (`:include: /path/name`) is not supported.
+* Warnings are printed on the standard error output for any
+ explicitly unsupported constructs, and any other lines that are not
+ recognized by the parser.
+--
sendemail.annotate::
sendemail.bcc::
sendemail.cc::
sendemail.ccCmd::
sendemail.chainReplyTo::
-sendemail.confirm::
sendemail.envelopeSender::
sendemail.from::
-sendemail.multiEdit::
sendemail.signedoffbycc::
sendemail.smtpPass::
sendemail.suppresscc::
@@ -44,7 +76,9 @@ sendemail.thread::
sendemail.transferEncoding::
sendemail.validate::
sendemail.xmailer::
- See linkgit:git-send-email[1] for description.
+ These configuration variables all provide a default for
+ linkgit:git-send-email[1] command-line options. See its
+ documentation for details.
sendemail.signedoffcc (deprecated)::
Deprecated alias for `sendemail.signedoffbycc`.
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 41cd8cb4247..3290043053a 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -456,41 +456,9 @@ Information
CONFIGURATION
-------------
-sendemail.aliasesFile::
- To avoid typing long email addresses, point this to one or more
- email aliases files. You must also supply `sendemail.aliasFileType`.
+include::includes/cmd-config-section-all.txt[]
-sendemail.aliasFileType::
- Format of the file(s) specified in sendemail.aliasesFile. Must be
- one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.
-+
-What an alias file in each format looks like can be found in
-the documentation of the email program of the same name. The
-differences and limitations from the standard formats are
-described below:
-+
---
-sendmail;;
-* Quoted aliases and quoted addresses are not supported: lines that
- contain a `"` symbol are ignored.
-* Redirection to a file (`/path/name`) or pipe (`|command`) is not
- supported.
-* File inclusion (`:include: /path/name`) is not supported.
-* Warnings are printed on the standard error output for any
- explicitly unsupported constructs, and any other lines that are not
- recognized by the parser.
---
-
-sendemail.multiEdit::
- If true (default), a single editor instance will be spawned to edit
- files you have to edit (patches when `--annotate` is used, and the
- summary when `--compose` is used). If false, files will be edited one
- after the other, spawning a new editor each time.
-
-sendemail.confirm::
- Sets the default for whether to confirm before sending. Must be
- one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`
- in the previous section for the meaning of these values.
+include::config/sendemail.txt[]
EXAMPLES
--------
--
2.37.1.1196.g8af3636bc64
^ permalink raw reply related [flat|nested] 56+ messages in thread
* Re: [PATCH v2 3/9] send-email docs: de-duplicate configuration sections
2022-07-29 8:25 ` [PATCH v2 3/9] send-email " Ævar Arnfjörð Bjarmason
@ 2022-07-30 13:45 ` Matheus Tavares
0 siblings, 0 replies; 56+ messages in thread
From: Matheus Tavares @ 2022-07-30 13:45 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Junio C Hamano
On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
> De-duplicate the discussion of "send-email" configuration, such that
> the "git-config(1)" manual page becomes the source of truth, and
> "git-send-email(1)" includes the relevant part.
>
> Most commands that suffered from such duplication had diverging text
> discussing the same variables, but in this case some config was also
> only discussed in one or the other.
>
> This is mostly a move-only change, the exception is a minor rewording
> of changing wording like "see above" to "see linkgit:git-config[1]",
> as well as a clarification about the big section of command-line
> option tweaking config being discussed in git-send-email(1)'s main
> docs.
Makes sense. And this is easy to review with --color-moved.
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> Documentation/config/sendemail.txt | 40 +++++++++++++++++++++++++++---
> Documentation/git-send-email.txt | 36 ++-------------------------
> 2 files changed, 39 insertions(+), 37 deletions(-)
>
> diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt
> index 50baa5d6bfb..51da7088a84 100644
> --- a/Documentation/config/sendemail.txt
> +++ b/Documentation/config/sendemail.txt
> [...]
> sendemail.annotate::
> sendemail.bcc::
> sendemail.cc::
> sendemail.ccCmd::
> sendemail.chainReplyTo::
> -sendemail.confirm::
> sendemail.envelopeSender::
> sendemail.from::
> -sendemail.multiEdit::
> sendemail.signedoffbycc::
> sendemail.smtpPass::
> sendemail.suppresscc::
> @@ -44,7 +76,9 @@ sendemail.thread::
> sendemail.transferEncoding::
> sendemail.validate::
> sendemail.xmailer::
> - See linkgit:git-send-email[1] for description.
> + These configuration variables all provide a default for
> + linkgit:git-send-email[1] command-line options. See its
> + documentation for details.
Ok, I looked one by one and these are all indeed mentioned in the
git-send-email(1) cli option documentation.
The rest looks good too.
^ permalink raw reply [flat|nested] 56+ messages in thread
* [PATCH v2 4/9] apply docs: de-duplicate configuration sections
2022-07-29 8:25 ` [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Ævar Arnfjörð Bjarmason
` (2 preceding siblings ...)
2022-07-29 8:25 ` [PATCH v2 3/9] send-email " Ævar Arnfjörð Bjarmason
@ 2022-07-29 8:25 ` Ævar Arnfjörð Bjarmason
2022-07-30 13:50 ` Matheus Tavares
2022-07-29 8:25 ` [PATCH v2 5/9] notes " Ævar Arnfjörð Bjarmason
` (6 subsequent siblings)
10 siblings, 1 reply; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-29 8:25 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
The wording is not identical to Documentation/config/apply.txt, but
that version is better.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-apply.txt | 10 +++-------
1 file changed, 3 insertions(+), 7 deletions(-)
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index b6d77f42068..1d478cbe9b5 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -263,13 +263,9 @@ has no effect when `--index` or `--cached` is in use.
CONFIGURATION
-------------
-apply.ignoreWhitespace::
- Set to 'change' if you want changes in whitespace to be ignored by default.
- Set to one of: no, none, never, false if you want changes in
- whitespace to be significant.
-apply.whitespace::
- When no `--whitespace` flag is given from the command
- line, this configuration item is used as the default.
+include::includes/cmd-config-section-all.txt[]
+
+include::config/apply.txt[]
SUBMODULES
----------
--
2.37.1.1196.g8af3636bc64
^ permalink raw reply related [flat|nested] 56+ messages in thread
* Re: [PATCH v2 4/9] apply docs: de-duplicate configuration sections
2022-07-29 8:25 ` [PATCH v2 4/9] apply " Ævar Arnfjörð Bjarmason
@ 2022-07-30 13:50 ` Matheus Tavares
0 siblings, 0 replies; 56+ messages in thread
From: Matheus Tavares @ 2022-07-30 13:50 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Junio C Hamano
On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
> The wording is not identical to Documentation/config/apply.txt, but
> that version is better.
Yeah, I agree. The only potential "loss" of information here is that
"apply.whitespace is the default when the cli arg is not used". But
that is the default for all configurations anyways.
^ permalink raw reply [flat|nested] 56+ messages in thread
* [PATCH v2 5/9] notes docs: de-duplicate configuration sections
2022-07-29 8:25 ` [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Ævar Arnfjörð Bjarmason
` (3 preceding siblings ...)
2022-07-29 8:25 ` [PATCH v2 4/9] apply " Ævar Arnfjörð Bjarmason
@ 2022-07-29 8:25 ` Ævar Arnfjörð Bjarmason
2022-07-30 20:02 ` Matheus Tavares
2022-07-29 8:25 ` [PATCH v2 6/9] difftool " Ævar Arnfjörð Bjarmason
` (5 subsequent siblings)
10 siblings, 1 reply; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-29 8:25 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
Let's also fix the "git-notes(1)" docs so that we link to
"git-config(1)", not "git-log(1)" as a reference for the "notes" docs.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/config/notes.txt | 43 ++++++++++++++++-----------
Documentation/git-log.txt | 16 ++--------
Documentation/git-notes.txt | 54 ++--------------------------------
3 files changed, 32 insertions(+), 81 deletions(-)
diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt
index aeef56d49ae..c7c4811734b 100644
--- a/Documentation/config/notes.txt
+++ b/Documentation/config/notes.txt
@@ -3,6 +3,9 @@ notes.mergeStrategy::
conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or
`cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES"
section of linkgit:git-notes[1] for more information on each strategy.
++
+This setting can be overridden by passing the `--strategy` option to
+linkgit:git-notes[1].
notes.<name>.mergeStrategy::
Which merge strategy to choose when doing a notes merge into
@@ -11,28 +14,35 @@ notes.<name>.mergeStrategy::
linkgit:git-notes[1] for more information on the available strategies.
notes.displayRef::
- The (fully qualified) refname from which to show notes when
- showing commit messages. The value of this variable can be set
- to a glob, in which case notes from all matching refs will be
- shown. You may also specify this configuration variable
- several times. A warning will be issued for refs that do not
- exist, but a glob that does not match any refs is silently
- ignored.
+ Which ref (or refs, if a glob or specified more than once), in
+ addition to the default set by `core.notesRef` or
+ `GIT_NOTES_REF`, to read notes from when showing commit
+ messages with the 'git log' family of commands.
+
This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`
environment variable, which must be a colon separated list of refs or
globs.
+
+A warning will be issued for refs that do not exist,
+but a glob that does not match any refs is silently ignored.
++
+This setting can be disabled by the `--no-notes` option to the 'git
+log' family of commands, or by the `--notes=<ref>` option accepted by
+those commands.
++
The effective value of "core.notesRef" (possibly overridden by
GIT_NOTES_REF) is also implicitly added to the list of refs to be
displayed.
notes.rewrite.<command>::
When rewriting commits with <command> (currently `amend` or
- `rebase`) and this variable is set to `true`, Git
- automatically copies your notes from the original to the
- rewritten commit. Defaults to `true`, but see
- "notes.rewriteRef" below.
+ `rebase`), if this variable is `false`, git will not copy
+ notes from the original to the rewritten commit. Defaults to
+ `true`. See also "`notes.rewriteRef`" below.
++
+This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
+environment variable, which must be a colon separated list of refs or
+globs.
notes.rewriteMode::
When copying notes during a rewrite (see the
@@ -46,14 +56,13 @@ environment variable.
notes.rewriteRef::
When copying notes during a rewrite, specifies the (fully
- qualified) ref whose notes should be copied. The ref may be a
- glob, in which case notes in all matching refs will be copied.
- You may also specify this configuration several times.
+ qualified) ref whose notes should be copied. May be a glob,
+ in which case notes in all matching refs will be copied. You
+ may also specify this configuration several times.
+
Does not have a default value; you must configure this variable to
enable note rewriting. Set it to `refs/notes/commits` to enable
rewriting for the default commit notes.
+
-This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
-environment variable, which must be a colon separated list of refs or
-globs.
+Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.
+See `notes.rewrite.<command>` above for a further description of its format.
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 20e87cecf49..ed802bb8e12 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -227,19 +227,9 @@ log.showSignature::
mailmap.*::
See linkgit:git-shortlog[1].
-notes.displayRef::
- Which refs, in addition to the default set by `core.notesRef`
- or `GIT_NOTES_REF`, to read notes from when showing commit
- messages with the `log` family of commands. See
- linkgit:git-notes[1].
-+
-May be an unabbreviated ref name or a glob and may be specified
-multiple times. A warning will be issued for refs that do not exist,
-but a glob that does not match any refs is silently ignored.
-+
-This setting can be disabled by the `--no-notes` option,
-overridden by the `GIT_NOTES_DISPLAY_REF` environment variable,
-and overridden by the `--notes=<ref>` option.
+include::includes/cmd-config-section-rest.txt[]
+
+include::config/notes.txt[]
GIT
---
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 0a4200674c4..68d547e2474 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -44,7 +44,7 @@ using the `--notes` option. Such notes are added as a patch commentary
after a three dash separator line.
To change which notes are shown by 'git log', see the
-"notes.displayRef" configuration in linkgit:git-log[1].
+"notes.displayRef" configuration in linkgit:git-config[1].
See the "notes.rewrite.<command>" configuration for a way to carry
notes across commands that rewrite commits.
@@ -316,57 +316,9 @@ core.notesRef::
This setting can be overridden through the environment and
command line.
-notes.mergeStrategy::
- Which merge strategy to choose by default when resolving notes
- conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or
- `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES"
- section above for more information on each strategy.
-+
-This setting can be overridden by passing the `--strategy` option.
-
-notes.<name>.mergeStrategy::
- Which merge strategy to choose when doing a notes merge into
- refs/notes/<name>. This overrides the more general
- "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section above
- for more information on each available strategy.
-
-notes.displayRef::
- Which ref (or refs, if a glob or specified more than once), in
- addition to the default set by `core.notesRef` or
- `GIT_NOTES_REF`, to read notes from when showing commit
- messages with the 'git log' family of commands.
- This setting can be overridden on the command line or by the
- `GIT_NOTES_DISPLAY_REF` environment variable.
- See linkgit:git-log[1].
-
-notes.rewrite.<command>::
- When rewriting commits with <command> (currently `amend` or
- `rebase`), if this variable is `false`, git will not copy
- notes from the original to the rewritten commit. Defaults to
- `true`. See also "`notes.rewriteRef`" below.
-+
-This setting can be overridden by the `GIT_NOTES_REWRITE_REF`
-environment variable.
+include::includes/cmd-config-section-rest.txt[]
-notes.rewriteMode::
- When copying notes during a rewrite, what to do if the target
- commit already has a note. Must be one of `overwrite`,
- `concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to
- `concatenate`.
-+
-This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
-environment variable.
-
-notes.rewriteRef::
- When copying notes during a rewrite, specifies the (fully
- qualified) ref whose notes should be copied. May be a glob,
- in which case notes in all matching refs will be copied. You
- may also specify this configuration several times.
-+
-Does not have a default value; you must configure this variable to
-enable note rewriting.
-+
-Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.
+include::config/notes.txt[]
ENVIRONMENT
--
2.37.1.1196.g8af3636bc64
^ permalink raw reply related [flat|nested] 56+ messages in thread
* Re: [PATCH v2 5/9] notes docs: de-duplicate configuration sections
2022-07-29 8:25 ` [PATCH v2 5/9] notes " Ævar Arnfjörð Bjarmason
@ 2022-07-30 20:02 ` Matheus Tavares
0 siblings, 0 replies; 56+ messages in thread
From: Matheus Tavares @ 2022-07-30 20:02 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Junio C Hamano
On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
> diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt
> index aeef56d49ae..c7c4811734b 100644
> --- a/Documentation/config/notes.txt
> +++ b/Documentation/config/notes.txt
> [...]
> notes.displayRef::
> - The (fully qualified) refname from which to show notes when
> - showing commit messages. The value of this variable can be set
> - to a glob, in which case notes from all matching refs will be
> - shown. You may also specify this configuration variable
> - several times. A warning will be issued for refs that do not
> - exist, but a glob that does not match any refs is silently
> - ignored.
> + Which ref (or refs, if a glob or specified more than once), in
> + addition to the default set by `core.notesRef` or
> + `GIT_NOTES_REF`, to read notes from when showing commit
> + messages with the 'git log' family of commands.
> +
> This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`
> environment variable, which must be a colon separated list of refs or
> globs.
> +
> +A warning will be issued for refs that do not exist,
> +but a glob that does not match any refs is silently ignored.
> ++
> +This setting can be disabled by the `--no-notes` option to the 'git
> +log' family of commands, or by the `--notes=<ref>` option accepted by
> +those commands.
> ++
> The effective value of "core.notesRef" (possibly overridden by
> GIT_NOTES_REF) is also implicitly added to the list of refs to be
> displayed.
This change is a bit complex since it agglutinates the definition of
notes.displayRef from three different places with different wordings
each. Perhaps it would be helpful to acknowledge it in the commit
message and/or justify the chosen parts?
> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
> index 0a4200674c4..68d547e2474 100644
> --- a/Documentation/git-notes.txt
> +++ b/Documentation/git-notes.txt
> @@ -44,7 +44,7 @@ using the `--notes` option. Such notes are added as a patch commentary
> after a three dash separator line.
>
> To change which notes are shown by 'git log', see the
> -"notes.displayRef" configuration in linkgit:git-log[1].
> +"notes.displayRef" configuration in linkgit:git-config[1].
Since notes.displayRef now comes from config/notes.txt which will be
included here, I think we could replace this reference to
git-config(1) with "in the CONFIGURATION section below".
^ permalink raw reply [flat|nested] 56+ messages in thread
* [PATCH v2 6/9] difftool docs: de-duplicate configuration sections
2022-07-29 8:25 ` [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Ævar Arnfjörð Bjarmason
` (4 preceding siblings ...)
2022-07-29 8:25 ` [PATCH v2 5/9] notes " Ævar Arnfjörð Bjarmason
@ 2022-07-29 8:25 ` Ævar Arnfjörð Bjarmason
2022-07-30 14:09 ` Matheus Tavares
2022-07-29 8:25 ` [PATCH v2 7/9] log " Ævar Arnfjörð Bjarmason
` (4 subsequent siblings)
10 siblings, 1 reply; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-29 8:25 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
Include the "config/difftool.txt" file in "git-difftool.txt", and move
the relevant part of git-difftool(1) configuration from
"config/diff.txt" to config/difftool.txt".
Doing this is slightly odd, as we usually discuss configuration in
alphabetical order, but by doing it we're able to include the full set
of configuration used by git-difftool(1) (and only that configuration)
in its own documentation.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/config/diff.txt | 15 ---------------
Documentation/config/difftool.txt | 28 +++++++++++++++++++++++++---
Documentation/git-difftool.txt | 27 ++++-----------------------
3 files changed, 29 insertions(+), 41 deletions(-)
diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt
index 32f84838ac1..35a7bf86d77 100644
--- a/Documentation/config/diff.txt
+++ b/Documentation/config/diff.txt
@@ -178,21 +178,6 @@ diff.<driver>.cachetextconv::
Set this option to true to make the diff driver cache the text
conversion outputs. See linkgit:gitattributes[5] for details.
-diff.tool::
- Controls which diff tool is used by linkgit:git-difftool[1].
- This variable overrides the value configured in `merge.tool`.
- The list below shows the valid built-in values.
- Any other value is treated as a custom diff tool and requires
- that a corresponding difftool.<tool>.cmd variable is defined.
-
-diff.guitool::
- Controls which diff tool is used by linkgit:git-difftool[1] when
- the -g/--gui flag is specified. This variable overrides the value
- configured in `merge.guitool`. The list below shows the valid
- built-in values. Any other value is treated as a custom diff tool
- and requires that a corresponding difftool.<guitool>.cmd variable
- is defined.
-
include::../mergetools-diff.txt[]
diff.indentHeuristic::
diff --git a/Documentation/config/difftool.txt b/Documentation/config/difftool.txt
index 67625944804..a3f82112102 100644
--- a/Documentation/config/difftool.txt
+++ b/Documentation/config/difftool.txt
@@ -1,6 +1,17 @@
-difftool.<tool>.path::
- Override the path for the given tool. This is useful in case
- your tool is not in the PATH.
+diff.tool::
+ Controls which diff tool is used by linkgit:git-difftool[1].
+ This variable overrides the value configured in `merge.tool`.
+ The list below shows the valid built-in values.
+ Any other value is treated as a custom diff tool and requires
+ that a corresponding difftool.<tool>.cmd variable is defined.
+
+diff.guitool::
+ Controls which diff tool is used by linkgit:git-difftool[1] when
+ the -g/--gui flag is specified. This variable overrides the value
+ configured in `merge.guitool`. The list below shows the valid
+ built-in values. Any other value is treated as a custom diff tool
+ and requires that a corresponding difftool.<guitool>.cmd variable
+ is defined.
difftool.<tool>.cmd::
Specify the command to invoke the specified diff tool.
@@ -9,6 +20,17 @@ difftool.<tool>.cmd::
file containing the contents of the diff pre-image and 'REMOTE'
is set to the name of the temporary file containing the contents
of the diff post-image.
++
+See the `--tool=<tool>` option in linkgit:git-difftool[1] for more details.
+
+difftool.<tool>.path::
+ Override the path for the given tool. This is useful in case
+ your tool is not in the PATH.
+
+difftool.trustExitCode::
+ Exit difftool if the invoked diff tool returns a non-zero exit status.
++
+See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details.
difftool.prompt::
Prompt before each invocation of the diff tool.
diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt
index 143b0c49d73..9d14c3c9f09 100644
--- a/Documentation/git-difftool.txt
+++ b/Documentation/git-difftool.txt
@@ -113,33 +113,14 @@ instead. `--no-symlinks` is the default on Windows.
See linkgit:git-diff[1] for the full list of supported options.
-CONFIG VARIABLES
-----------------
+CONFIGURATION
+-------------
'git difftool' falls back to 'git mergetool' config variables when the
difftool equivalents have not been defined.
-diff.tool::
- The default diff tool to use.
+include::includes/cmd-config-section-rest.txt[]
-diff.guitool::
- The default diff tool to use when `--gui` is specified.
-
-difftool.<tool>.path::
- Override the path for the given tool. This is useful in case
- your tool is not in the PATH.
-
-difftool.<tool>.cmd::
- Specify the command to invoke the specified diff tool.
-+
-See the `--tool=<tool>` option above for more details.
-
-difftool.prompt::
- Prompt before each invocation of the diff tool.
-
-difftool.trustExitCode::
- Exit difftool if the invoked diff tool returns a non-zero exit status.
-+
-See the `--trust-exit-code` option above for more details.
+include::config/difftool.txt[]
SEE ALSO
--------
--
2.37.1.1196.g8af3636bc64
^ permalink raw reply related [flat|nested] 56+ messages in thread
* Re: [PATCH v2 6/9] difftool docs: de-duplicate configuration sections
2022-07-29 8:25 ` [PATCH v2 6/9] difftool " Ævar Arnfjörð Bjarmason
@ 2022-07-30 14:09 ` Matheus Tavares
0 siblings, 0 replies; 56+ messages in thread
From: Matheus Tavares @ 2022-07-30 14:09 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Junio C Hamano
On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
> diff --git a/Documentation/config/difftool.txt b/Documentation/config/difftool.txt
> index 67625944804..a3f82112102 100644
> --- a/Documentation/config/difftool.txt
> +++ b/Documentation/config/difftool.txt
> @@ -1,6 +1,17 @@
> -difftool.<tool>.path::
> - Override the path for the given tool. This is useful in case
> - your tool is not in the PATH.
> +diff.tool::
> + Controls which diff tool is used by linkgit:git-difftool[1].
> + This variable overrides the value configured in `merge.tool`.
> + The list below shows the valid built-in values.
> + Any other value is treated as a custom diff tool and requires
> + that a corresponding difftool.<tool>.cmd variable is defined.
> +
> +diff.guitool::
> + Controls which diff tool is used by linkgit:git-difftool[1] when
> + the -g/--gui flag is specified. This variable overrides the value
> + configured in `merge.guitool`. The list below shows the valid
> + built-in values. Any other value is treated as a custom diff tool
> + and requires that a corresponding difftool.<guitool>.cmd variable
> + is defined.
At first glance I thought it was a bit weird to have this diff.*
definitions moved to difftool, but it makes sense since these are
indeed related to difftool.
> difftool.<tool>.cmd::
> Specify the command to invoke the specified diff tool.
> @@ -9,6 +20,17 @@ difftool.<tool>.cmd::
> file containing the contents of the diff pre-image and 'REMOTE'
> is set to the name of the temporary file containing the contents
> of the diff post-image.
> ++
> +See the `--tool=<tool>` option in linkgit:git-difftool[1] for more details.
> +
OK, this comes from the removed part of Documentation/git-difftool.txt.
> +difftool.<tool>.path::
> + Override the path for the given tool. This is useful in case
> + your tool is not in the PATH.
> +
> +difftool.trustExitCode::
> + Exit difftool if the invoked diff tool returns a non-zero exit status.
> ++
> +See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details.
And so does this.
^ permalink raw reply [flat|nested] 56+ messages in thread
* [PATCH v2 7/9] log docs: de-duplicate configuration sections
2022-07-29 8:25 ` [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Ævar Arnfjörð Bjarmason
` (5 preceding siblings ...)
2022-07-29 8:25 ` [PATCH v2 6/9] difftool " Ævar Arnfjörð Bjarmason
@ 2022-07-29 8:25 ` Ævar Arnfjörð Bjarmason
2022-07-30 18:52 ` Matheus Tavares
2022-07-29 8:25 ` [PATCH v2 8/9] docs: add CONFIGURATION sections that map to a built-in Ævar Arnfjörð Bjarmason
` (3 subsequent siblings)
10 siblings, 1 reply; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-29 8:25 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/config/log.txt | 18 +++++++++++++-----
Documentation/git-log.txt | 33 +++++----------------------------
2 files changed, 18 insertions(+), 33 deletions(-)
diff --git a/Documentation/config/log.txt b/Documentation/config/log.txt
index 456eb07800c..12ede8e31b8 100644
--- a/Documentation/config/log.txt
+++ b/Documentation/config/log.txt
@@ -1,12 +1,11 @@
-log.abbrevCommit::
- If true, makes linkgit:git-log[1], linkgit:git-show[1], and
- linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may
- override this option with `--no-abbrev-commit`.
-
log.date::
Set the default date-time mode for the 'log' command.
Setting a value for log.date is similar to using 'git log''s
`--date` option. See linkgit:git-log[1] for details.
++
+If the format is set to "auto:foo" and the pager is in use, format
+"foo" will be the used for the date format. Otherwise "default" will
+be used.
log.decorate::
Print out the ref names of any commits that are shown by the log
@@ -45,6 +44,11 @@ log.showRoot::
Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which
normally hide the root commit will now show it. True by default.
+log.abbrevCommit::
+ If true, makes linkgit:git-log[1], linkgit:git-show[1], and
+ linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may
+ override this option with `--no-abbrev-commit`.
+
log.showSignature::
If true, makes linkgit:git-log[1], linkgit:git-show[1], and
linkgit:git-whatchanged[1] assume `--show-signature`.
@@ -53,3 +57,7 @@ log.mailmap::
If true, makes linkgit:git-log[1], linkgit:git-show[1], and
linkgit:git-whatchanged[1] assume `--use-mailmap`, otherwise
assume `--no-use-mailmap`. True by default.
++
+The behavior of `log.mailmap` is impacted by the setting of the more
+general 'mailmap.*' configuration variables, i.e. `mailmap.file` and
+`mailmap.blob`.
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index ed802bb8e12..69c4e13833d 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -42,6 +42,9 @@ OPTIONS
shown. The option `--decorate` is short-hand for `--decorate=short`.
Default to configuration value of `log.decorate` if configured,
otherwise, `auto`.
++
+This output may be colored. See `color.ui` in linkgit:git-config[1]
+and `color.decorate` there and in the "CONFIGURATION" section below.
--decorate-refs=<pattern>::
--decorate-refs-exclude=<pattern>::
@@ -199,36 +202,10 @@ i18n.logOutputEncoding::
Defaults to the value of `i18n.commitEncoding` if set, and UTF-8
otherwise.
-log.date::
- Default format for human-readable dates. (Compare the
- `--date` option.) Defaults to "default", which means to write
- dates like `Sat May 8 19:35:34 2010 -0500`.
-+
-If the format is set to "auto:foo" and the pager is in use, format
-"foo" will be the used for the date format. Otherwise "default" will
-be used.
-
-log.follow::
- If `true`, `git log` will act as if the `--follow` option was used when
- a single <path> is given. This has the same limitations as `--follow`,
- i.e. it cannot be used to follow multiple files and does not work well
- on non-linear history.
-
-log.showRoot::
- If `false`, `git log` and related commands will not treat the
- initial commit as a big creation event. Any root commits in
- `git log -p` output would be shown without a diff attached.
- The default is `true`.
-
-log.showSignature::
- If `true`, `git log` and related commands will act as if the
- `--show-signature` option was passed to them.
-
-mailmap.*::
- See linkgit:git-shortlog[1].
-
include::includes/cmd-config-section-rest.txt[]
+include::config/log.txt[]
+
include::config/notes.txt[]
GIT
--
2.37.1.1196.g8af3636bc64
^ permalink raw reply related [flat|nested] 56+ messages in thread
* Re: [PATCH v2 7/9] log docs: de-duplicate configuration sections
2022-07-29 8:25 ` [PATCH v2 7/9] log " Ævar Arnfjörð Bjarmason
@ 2022-07-30 18:52 ` Matheus Tavares
0 siblings, 0 replies; 56+ messages in thread
From: Matheus Tavares @ 2022-07-30 18:52 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Junio C Hamano
On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> Documentation/config/log.txt | 18 +++++++++++++-----
> Documentation/git-log.txt | 33 +++++----------------------------
> 2 files changed, 18 insertions(+), 33 deletions(-)
>
> diff --git a/Documentation/config/log.txt b/Documentation/config/log.txt
> index 456eb07800c..12ede8e31b8 100644
> --- a/Documentation/config/log.txt
> +++ b/Documentation/config/log.txt
> @@ -1,12 +1,11 @@
> -log.abbrevCommit::
> - If true, makes linkgit:git-log[1], linkgit:git-show[1], and
> - linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may
> - override this option with `--no-abbrev-commit`.
> -
Why was this moved ....
> log.date::
> Set the default date-time mode for the 'log' command.
> Setting a value for log.date is similar to using 'git log''s
> `--date` option. See linkgit:git-log[1] for details.
> ++
> +If the format is set to "auto:foo" and the pager is in use, format
> +"foo" will be the used for the date format. Otherwise "default" will
> +be used.
>
> log.decorate::
> Print out the ref names of any commits that are shown by the log
> @@ -45,6 +44,11 @@ log.showRoot::
> Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which
> normally hide the root commit will now show it. True by default.
>
> +log.abbrevCommit::
> + If true, makes linkgit:git-log[1], linkgit:git-show[1], and
> + linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may
> + override this option with `--no-abbrev-commit`.
> +
... down here?
> log.showSignature::
> If true, makes linkgit:git-log[1], linkgit:git-show[1], and
> linkgit:git-whatchanged[1] assume `--show-signature`.
> @@ -53,3 +57,7 @@ log.mailmap::
> If true, makes linkgit:git-log[1], linkgit:git-show[1], and
> linkgit:git-whatchanged[1] assume `--use-mailmap`, otherwise
> assume `--no-use-mailmap`. True by default.
> ++
> +The behavior of `log.mailmap` is impacted by the setting of the more
> +general 'mailmap.*' configuration variables, i.e. `mailmap.file` and
> +`mailmap.blob`.
Good.
> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
> index ed802bb8e12..69c4e13833d 100644
> --- a/Documentation/git-log.txt
> +++ b/Documentation/git-log.txt
> @@ -42,6 +42,9 @@ OPTIONS
> shown. The option `--decorate` is short-hand for `--decorate=short`.
> Default to configuration value of `log.decorate` if configured,
> otherwise, `auto`.
> ++
> +This output may be colored. See `color.ui` in linkgit:git-config[1]
> +and `color.decorate` there and in the "CONFIGURATION" section below.
Hmm, is this related to this change?
> [...]
> -log.showRoot::
> - If `false`, `git log` and related commands will not treat the
> - initial commit as a big creation event. Any root commits in
> - `git log -p` output would be shown without a diff attached.
> - The default is `true`.
> -
> -log.showSignature::
> - If `true`, `git log` and related commands will act as if the
> - `--show-signature` option was passed to them.
These two have a different wording on config/log.txt, but they are
arguably better presented there anyway.
^ permalink raw reply [flat|nested] 56+ messages in thread
* [PATCH v2 8/9] docs: add CONFIGURATION sections that map to a built-in
2022-07-29 8:25 ` [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Ævar Arnfjörð Bjarmason
` (6 preceding siblings ...)
2022-07-29 8:25 ` [PATCH v2 7/9] log " Ævar Arnfjörð Bjarmason
@ 2022-07-29 8:25 ` Ævar Arnfjörð Bjarmason
2022-07-29 21:58 ` Junio C Hamano
2022-07-29 8:25 ` [PATCH v2 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins Ævar Arnfjörð Bjarmason
` (2 subsequent siblings)
10 siblings, 1 reply; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-29 8:25 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
Add a CONFIGURATION section to the documentation of various built-ins,
for those cases where the relevant config/NAME.txt describes
configuration that is only used by the relevant built-in documented in
git-NAME.txt. Subsequent commits will handle more complex cases.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-add.txt | 7 +++++++
Documentation/git-am.txt | 7 +++++++
Documentation/git-clean.txt | 7 +++++++
Documentation/git-clone.txt | 7 +++++++
Documentation/git-commit-graph.txt | 7 +++++++
Documentation/git-commit.txt | 4 ++++
Documentation/git-fast-import.txt | 7 +++++++
Documentation/git-mailinfo.txt | 7 +++++++
Documentation/git-maintenance.txt | 7 +++++++
Documentation/git-push.txt | 7 +++++++
Documentation/git-revert.txt | 7 +++++++
Documentation/git-show-branch.txt | 7 +++++++
Documentation/git-stash.txt | 7 +++++++
13 files changed, 88 insertions(+)
diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 11eb70f16c7..36da8bf9b51 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -431,6 +431,13 @@ they will make the patch impossible to apply:
* deleting context or removal lines
* modifying the contents of context or removal lines
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/add.txt[]
+
SEE ALSO
--------
linkgit:git-status[1]
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 09107fb1067..7ccb46b660c 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -261,6 +261,13 @@ This command can run `applypatch-msg`, `pre-applypatch`,
and `post-applypatch` hooks. See linkgit:githooks[5] for more
information.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/am.txt[]
+
SEE ALSO
--------
linkgit:git-apply[1].
diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index a7f309dff5a..91742633fa8 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -133,6 +133,13 @@ help::
Show brief usage of interactive git-clean.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/clean.txt[]
+
SEE ALSO
--------
linkgit:gitignore[5]
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 632bd1348ea..b9ee8a87238 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -363,6 +363,13 @@ $ cd my-linux
$ git clone --bare -l /home/proj/.git /pub/scm/proj.git
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/clone.txt[]
+
GIT
---
diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
index e1f48c95b3c..5225f674546 100644
--- a/Documentation/git-commit-graph.txt
+++ b/Documentation/git-commit-graph.txt
@@ -142,6 +142,13 @@ $ git show-ref -s | git commit-graph write --stdin-commits
$ git rev-parse HEAD | git commit-graph write --stdin-commits --append
------------------------------------------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/commitgraph.txt[]
+
GIT
---
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 6c60bf98f9f..225c6c9f2e5 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -557,6 +557,10 @@ The editor used to edit the commit log message will be chosen from the
`VISUAL` environment variable, or the `EDITOR` environment variable (in that
order). See linkgit:git-var[1] for details.
+include::includes/cmd-config-section-rest.txt[]
+
+include::config/commit.txt[]
+
HOOKS
-----
This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`,
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 39cfa05b28b..8b5dd6add00 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -1564,6 +1564,13 @@ operator can use this facility to peek at the objects and refs from an
import in progress, at the cost of some added running time and worse
compression.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/fastimport.txt[]
+
SEE ALSO
--------
linkgit:git-fast-export[1]
diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt
index 3fcfd965fde..28060283c70 100644
--- a/Documentation/git-mailinfo.txt
+++ b/Documentation/git-mailinfo.txt
@@ -115,6 +115,13 @@ If no such configuration option has been set, `warn` will be used.
<patch>::
The patch extracted from e-mail.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/mailinfo.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt
index e56bad28c65..9c630efe19c 100644
--- a/Documentation/git-maintenance.txt
+++ b/Documentation/git-maintenance.txt
@@ -397,6 +397,13 @@ If you want to customize the background tasks, please rename the tasks
so future calls to `git maintenance (start|stop)` do not overwrite your
custom tasks.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/maintenance.txt[]
+
GIT
---
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 2f25aa3a291..def7657ef9c 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -692,6 +692,13 @@ a `git gc` command on the origin repository.
include::transfer-data-leaks.txt[]
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/push.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index 8463fe9cf75..700f937f60a 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -145,6 +145,13 @@ EXAMPLES
changes. The revert only modifies the working tree and the
index.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/revert.txt[]
+
SEE ALSO
--------
linkgit:git-cherry-pick[1]
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index 5cc2fcefbab..e5ec6b467f9 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -199,6 +199,13 @@ shows 10 reflog entries going back from the tip as of 1 hour ago.
Without `--list`, the output also shows how these tips are
topologically related with each other.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/showbranch.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 6e15f475257..c5d70918283 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -382,6 +382,13 @@ grep commit | cut -d\ -f3 |
xargs git log --merges --no-walk --grep=WIP
----------------------------------------------------------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/stash.txt[]
+
SEE ALSO
--------
--
2.37.1.1196.g8af3636bc64
^ permalink raw reply related [flat|nested] 56+ messages in thread
* Re: [PATCH v2 8/9] docs: add CONFIGURATION sections that map to a built-in
2022-07-29 8:25 ` [PATCH v2 8/9] docs: add CONFIGURATION sections that map to a built-in Ævar Arnfjörð Bjarmason
@ 2022-07-29 21:58 ` Junio C Hamano
0 siblings, 0 replies; 56+ messages in thread
From: Junio C Hamano @ 2022-07-29 21:58 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Matheus Tavares
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> Add a CONFIGURATION section to the documentation of various built-ins,
> for those cases where the relevant config/NAME.txt describes
> configuration that is only used by the relevant built-in documented in
> git-NAME.txt. Subsequent commits will handle more complex cases.
>
> Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> ---
> Documentation/git-add.txt | 7 +++++++
> Documentation/git-am.txt | 7 +++++++
> Documentation/git-clean.txt | 7 +++++++
> Documentation/git-clone.txt | 7 +++++++
> Documentation/git-commit-graph.txt | 7 +++++++
> Documentation/git-commit.txt | 4 ++++
> Documentation/git-fast-import.txt | 7 +++++++
> Documentation/git-mailinfo.txt | 7 +++++++
> Documentation/git-maintenance.txt | 7 +++++++
> Documentation/git-push.txt | 7 +++++++
> Documentation/git-revert.txt | 7 +++++++
> Documentation/git-show-branch.txt | 7 +++++++
> Documentation/git-stash.txt | 7 +++++++
> 13 files changed, 88 insertions(+)
This is one of the larger patch in the series, but everything here
follows the same pattern and is easy to see that they are correct.
^ permalink raw reply [flat|nested] 56+ messages in thread
* [PATCH v2 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins
2022-07-29 8:25 ` [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Ævar Arnfjörð Bjarmason
` (7 preceding siblings ...)
2022-07-29 8:25 ` [PATCH v2 8/9] docs: add CONFIGURATION sections that map to a built-in Ævar Arnfjörð Bjarmason
@ 2022-07-29 8:25 ` Ævar Arnfjörð Bjarmason
2022-07-29 22:03 ` Junio C Hamano
2022-07-30 19:08 ` Matheus Tavares
2022-07-30 20:05 ` [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Matheus Tavares
2022-08-31 8:41 ` [PATCH v3 " Ævar Arnfjörð Bjarmason
10 siblings, 2 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-07-29 8:25 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
Add a CONFIGURATION section to the documentation of various built-ins,
for those cases where the relevant config/NAME.txt doesn't map only to
one git-NAME.txt. In particular:
* config/blame.txt: used by git-{blame,annotate}.txt. Since the
git-annotate(1) documentation refers to git-blame(1) don't add a
"CONFIGURATION" section to git-annotate(1), only to git-blame(1)>
* config/branch.txt: maps to both git-checkout.txt and
git-switch.txt (but nothing else).
* config/init.txt: should be included in git-init(1) and
git-clone(1).
* config/column.txt: We should ideally mention the relevant subset of
this in git-{branch,clean,status,tag}.txt, but let's punt on it for
now. We will when we eventually split these sort of files into
e.g. config/column.txt and
config/column/{branch,clean,status,tag}.txt, with the former
including the latter set.
Things that are being left out, and why:
* config/remote.txt: let's not include this in
git-{fetch,remote,push}.txt etc. for now, various options there
change their behavior.
* config/remotes.txt: As we're not including config/remote.txt for
now, let's not include this one either.
* config/credential.txt: let's not include this in
git-credential.txt, it talks more generally about how the
credential facility is used by various other commands, not that
command in particular.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-blame.txt | 6 ++++++
Documentation/git-branch.txt | 4 ++++
Documentation/git-checkout.txt | 7 +++++++
Documentation/git-clone.txt | 2 ++
Documentation/git-column.txt | 7 +++++++
Documentation/git-diff.txt | 7 +++++++
Documentation/git-fetch.txt | 7 +++++++
Documentation/git-switch.txt | 7 +++++++
8 files changed, 47 insertions(+)
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index d7a46cc6744..4400a17330b 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -241,6 +241,12 @@ MAPPING AUTHORS
See linkgit:gitmailmap[5].
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/blame.txt[]
SEE ALSO
--------
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index ae82378349d..12c5f84e3be 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -336,6 +336,10 @@ CONFIGURATION
`--list` is used or implied. The default is to use a pager.
See linkgit:git-config[1].
+include::includes/cmd-config-section-rest.txt[]
+
+include::config/branch.txt[]
+
EXAMPLES
--------
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 9f37e22e130..4cb9d555b4b 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -600,6 +600,13 @@ $ edit frotz
$ git add frotz
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/checkout.txt[]
+
SEE ALSO
--------
linkgit:git-switch[1],
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index b9ee8a87238..43955a3b504 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -368,6 +368,8 @@ CONFIGURATION
include::includes/cmd-config-section-all.txt[]
+include::config/init.txt[]
+
include::config/clone.txt[]
diff --git a/Documentation/git-column.txt b/Documentation/git-column.txt
index 6cea9ab4638..18431647a2d 100644
--- a/Documentation/git-column.txt
+++ b/Documentation/git-column.txt
@@ -74,6 +74,13 @@ v2.4.3 v2.4.4 v2.4.5 v2.4.6 v2.4.7
v2.4.8 v2.4.9
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/column.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 6236c75c9b8..85ae6d6d08a 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -213,6 +213,13 @@ $ git diff -R <2>
rewrites (very expensive).
<2> Output diff in reverse.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/diff.txt[]
+
SEE ALSO
--------
diff(1),
diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index e9d364669af..63d9569e164 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt
@@ -285,6 +285,13 @@ linkgit:git-gc[1]).
include::transfer-data-leaks.txt[]
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/fetch.txt[]
+
BUGS
----
Using --recurse-submodules can only fetch new commits in submodules that are
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index bbcbdceb459..c60fc9c138b 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -265,6 +265,13 @@ always create a new name for it (without switching away):
$ git switch -c good-surprises
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/checkout.txt[]
+
SEE ALSO
--------
linkgit:git-checkout[1],
--
2.37.1.1196.g8af3636bc64
^ permalink raw reply related [flat|nested] 56+ messages in thread
* Re: [PATCH v2 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins
2022-07-29 8:25 ` [PATCH v2 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins Ævar Arnfjörð Bjarmason
@ 2022-07-29 22:03 ` Junio C Hamano
2022-07-30 19:08 ` Matheus Tavares
1 sibling, 0 replies; 56+ messages in thread
From: Junio C Hamano @ 2022-07-29 22:03 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Matheus Tavares
Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
> Add a CONFIGURATION section to the documentation of various built-ins,
> for those cases where the relevant config/NAME.txt doesn't map only to
> one git-NAME.txt. In particular:
>
> * config/blame.txt: used by git-{blame,annotate}.txt. Since the
> git-annotate(1) documentation refers to git-blame(1) don't add a
> "CONFIGURATION" section to git-annotate(1), only to git-blame(1)>
s/>/./ I think.
> * config/branch.txt: maps to both git-checkout.txt and
> git-switch.txt (but nothing else).
s|/branch.txt|/checkout.txt|, I think.
> * config/init.txt: should be included in git-init(1) and
> git-clone(1).
>
> * config/column.txt: We should ideally mention the relevant subset of
> this in git-{branch,clean,status,tag}.txt, but let's punt on it for
> now. We will when we eventually split these sort of files into
> e.g. config/column.txt and
> config/column/{branch,clean,status,tag}.txt, with the former
> including the latter set.
>
> Things that are being left out, and why:
>
> * config/remote.txt: let's not include this in
> git-{fetch,remote,push}.txt etc. for now, various options there
> change their behavior.
Leaving some stuff out is fine, but I am not sure I understand
(note: I didn't say "I agree with") the reasoning. I take "various
options there" to mean the configuration variables described in
config/remote.txt file? If these variables affect the behaviour of
commands like fetch, remote, and push, isn't it more reason to
include the description of them?
^ permalink raw reply [flat|nested] 56+ messages in thread
* Re: [PATCH v2 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins
2022-07-29 8:25 ` [PATCH v2 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins Ævar Arnfjörð Bjarmason
2022-07-29 22:03 ` Junio C Hamano
@ 2022-07-30 19:08 ` Matheus Tavares
2022-07-30 20:44 ` Junio C Hamano
1 sibling, 1 reply; 56+ messages in thread
From: Matheus Tavares @ 2022-07-30 19:08 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Junio C Hamano
On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
> Add a CONFIGURATION section to the documentation of various built-ins,
> for those cases where the relevant config/NAME.txt doesn't map only to
> one git-NAME.txt. In particular:
>
> * config/blame.txt: used by git-{blame,annotate}.txt. Since the
> git-annotate(1) documentation refers to git-blame(1) don't add a
> "CONFIGURATION" section to git-annotate(1), only to git-blame(1)>
>
> * config/branch.txt: maps to both git-checkout.txt and
> git-switch.txt (but nothing else).
>
> * config/init.txt: should be included in git-init(1) and
> git-clone(1).
I think the inclusion at git-init(1) is missing in the diff below.
^ permalink raw reply [flat|nested] 56+ messages in thread
* Re: [PATCH v2 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins
2022-07-30 19:08 ` Matheus Tavares
@ 2022-07-30 20:44 ` Junio C Hamano
0 siblings, 0 replies; 56+ messages in thread
From: Junio C Hamano @ 2022-07-30 20:44 UTC (permalink / raw)
To: Matheus Tavares; +Cc: Ævar Arnfjörð Bjarmason, git
Matheus Tavares <matheus.bernardino@usp.br> writes:
> On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason
> <avarab@gmail.com> wrote:
>>
>> Add a CONFIGURATION section to the documentation of various built-ins,
>> for those cases where the relevant config/NAME.txt doesn't map only to
>> one git-NAME.txt. In particular:
>>
>> * config/blame.txt: used by git-{blame,annotate}.txt. Since the
>> git-annotate(1) documentation refers to git-blame(1) don't add a
>> "CONFIGURATION" section to git-annotate(1), only to git-blame(1)>
>>
>> * config/branch.txt: maps to both git-checkout.txt and
>> git-switch.txt (but nothing else).
>>
>> * config/init.txt: should be included in git-init(1) and
>> git-clone(1).
>
> I think the inclusion at git-init(1) is missing in the diff below.
Good eyes. Thanks for carefully reviewing.
^ permalink raw reply [flat|nested] 56+ messages in thread
* Re: [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections
2022-07-29 8:25 ` [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Ævar Arnfjörð Bjarmason
` (8 preceding siblings ...)
2022-07-29 8:25 ` [PATCH v2 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins Ævar Arnfjörð Bjarmason
@ 2022-07-30 20:05 ` Matheus Tavares
2022-08-31 8:41 ` [PATCH v3 " Ævar Arnfjörð Bjarmason
10 siblings, 0 replies; 56+ messages in thread
From: Matheus Tavares @ 2022-07-30 20:05 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Junio C Hamano
On Fri, Jul 29, 2022 at 5:25 AM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
> This series is a follow-up to Matheus Tavares's v1[1] patches to
> de-duplicate some of our configuration documentation, per [2] I'm
> submitting this as a replacement series.
Thanks for submitting this version, which I very much appreciate. I
left some comments in the patches, but overall it is looking good to
me.
^ permalink raw reply [flat|nested] 56+ messages in thread
* [PATCH v3 0/9] docs: de-duplicate sections, add more CONFIGURATION sections
2022-07-29 8:25 ` [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Ævar Arnfjörð Bjarmason
` (9 preceding siblings ...)
2022-07-30 20:05 ` [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Matheus Tavares
@ 2022-08-31 8:41 ` Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 1/9] docs: add and use include template for config/* includes Ævar Arnfjörð Bjarmason
` (10 more replies)
10 siblings, 11 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-31 8:41 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
This series:
* De-duplicates and combines configuration discussion that was split
or spread across Documentation/config/*.txt and
Documentation/git-*.txt, moving it to Documentation/config/*.txt.
* Includes that relevant Documentation/config/*.txt in the
Documentation/git-*.txt files.
* Introduces and uses included prose for those "CONFIGURATION"
sections in various Documentation/git-*.txt files, informing the
reader that what they see there is included from "git-config(1)".
This v3 attempts to address all the feedback on v2. I think this
should be good for merging down at this point. Sorry about the late
re-roll.
Ævar Arnfjörð Bjarmason (9):
docs: add and use include template for config/* includes
grep docs: de-duplicate configuration sections
send-email docs: de-duplicate configuration sections
apply docs: de-duplicate configuration sections
notes docs: de-duplicate and combine configuration sections
difftool docs: de-duplicate configuration sections
log docs: de-duplicate configuration sections
docs: add CONFIGURATION sections that map to a built-in
docs: add CONFIGURATION sections that fuzzy map to built-ins
Documentation/Makefile | 1 +
Documentation/config/diff.txt | 15 -----
Documentation/config/difftool.txt | 28 +++++++++-
Documentation/config/grep.txt | 7 ++-
Documentation/config/log.txt | 4 ++
Documentation/config/notes.txt | 43 +++++++++------
Documentation/config/sendemail.txt | 40 +++++++++++++-
Documentation/git-add.txt | 7 +++
Documentation/git-am.txt | 7 +++
Documentation/git-apply.txt | 10 +---
Documentation/git-blame.txt | 6 ++
Documentation/git-branch.txt | 4 ++
Documentation/git-checkout.txt | 7 +++
Documentation/git-clean.txt | 7 +++
Documentation/git-clone.txt | 9 +++
Documentation/git-column.txt | 7 +++
Documentation/git-commit-graph.txt | 7 +++
Documentation/git-commit.txt | 4 ++
Documentation/git-diff.txt | 7 +++
Documentation/git-difftool.txt | 27 ++-------
Documentation/git-fast-import.txt | 7 +++
Documentation/git-fetch.txt | 7 +++
Documentation/git-fsck.txt | 2 +
Documentation/git-gc.txt | 3 +-
Documentation/git-grep.txt | 29 +---------
Documentation/git-imap-send.txt | 2 +
Documentation/git-init.txt | 7 +++
Documentation/git-log.txt | 46 ++--------------
Documentation/git-mailinfo.txt | 7 +++
Documentation/git-maintenance.txt | 7 +++
Documentation/git-merge.txt | 5 +-
Documentation/git-mergetool.txt | 3 +
Documentation/git-notes.txt | 55 ++-----------------
Documentation/git-push.txt | 7 +++
Documentation/git-rebase.txt | 2 +
Documentation/git-revert.txt | 7 +++
Documentation/git-send-email.txt | 36 +-----------
Documentation/git-show-branch.txt | 7 +++
Documentation/git-stash.txt | 7 +++
Documentation/git-switch.txt | 7 +++
.../includes/cmd-config-section-all.txt | 3 +
.../includes/cmd-config-section-rest.txt | 3 +
42 files changed, 280 insertions(+), 226 deletions(-)
create mode 100644 Documentation/includes/cmd-config-section-all.txt
create mode 100644 Documentation/includes/cmd-config-section-rest.txt
Range-diff against v2:
1: ef6fa5450e7 ! 1: da21c19978c docs: add and use include template for config/* includes
@@ Documentation/includes/cmd-config-section-all.txt (new)
## Documentation/includes/cmd-config-section-rest.txt (new) ##
@@
-+The discussion above this line is unique to this documentation, but
-+everything below is included from section(s) in linkgit:git-config[1]
-+aplicable to this command:
++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:
2: 5f07f87710c = 2: d16e927caa2 grep docs: de-duplicate configuration sections
3: 8138dc54e3e = 3: c36feb6f35a send-email docs: de-duplicate configuration sections
4: b9750ae43e1 = 4: 5707c9dd635 apply docs: de-duplicate configuration sections
5: 1b6c8c75df7 ! 5: 5b0ea00aa33 notes docs: de-duplicate configuration sections
@@ Metadata
Author: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Commit message ##
- notes docs: de-duplicate configuration sections
+ notes docs: de-duplicate and combine configuration sections
- Let's also fix the "git-notes(1)" docs so that we link to
- "git-config(1)", not "git-log(1)" as a reference for the "notes" docs.
+ Combine the various "notes" configuration sections spread across
+ Documentation/config/notes.txt and Documentation/git-notes.txt to live
+ in the former, and to be included in the latter.
+
+ We'll now forward link from "git notes" to the "CONFIGURATION" section
+ below, rather than to "git-config(1)" when discussing configuration
+ variables that are (also) discussed in that section.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
@@ Documentation/git-notes.txt: using the `--notes` option. Such notes are added as
To change which notes are shown by 'git log', see the
-"notes.displayRef" configuration in linkgit:git-log[1].
-+"notes.displayRef" configuration in linkgit:git-config[1].
++"notes.displayRef" discussion in <<CONFIGURATION>>.
See the "notes.rewrite.<command>" configuration for a way to carry
notes across commands that rewrite commits.
+@@ Documentation/git-notes.txt: with 'git log', so if you use such notes, you'll probably need to write
+ some special-purpose tools to do something useful with them.
+
+
++[[CONFIGURATION]]
+ CONFIGURATION
+ -------------
+
@@ Documentation/git-notes.txt: core.notesRef::
This setting can be overridden through the environment and
command line.
6: b3a5ea46bb5 = 6: c4c3fa14190 difftool docs: de-duplicate configuration sections
7: 08d98767384 ! 7: e07585ba085 log docs: de-duplicate configuration sections
@@ Commit message
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
## Documentation/config/log.txt ##
-@@
--log.abbrevCommit::
-- If true, makes linkgit:git-log[1], linkgit:git-show[1], and
-- linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may
-- override this option with `--no-abbrev-commit`.
--
- log.date::
+@@ Documentation/config/log.txt: log.date::
Set the default date-time mode for the 'log' command.
Setting a value for log.date is similar to using 'git log''s
`--date` option. See linkgit:git-log[1] for details.
@@ Documentation/config/log.txt
log.decorate::
Print out the ref names of any commits that are shown by the log
-@@ Documentation/config/log.txt: log.showRoot::
- Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which
- normally hide the root commit will now show it. True by default.
-
-+log.abbrevCommit::
-+ If true, makes linkgit:git-log[1], linkgit:git-show[1], and
-+ linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may
-+ override this option with `--no-abbrev-commit`.
-+
- log.showSignature::
- If true, makes linkgit:git-log[1], linkgit:git-show[1], and
- linkgit:git-whatchanged[1] assume `--show-signature`.
-@@ Documentation/config/log.txt: log.mailmap::
- If true, makes linkgit:git-log[1], linkgit:git-show[1], and
- linkgit:git-whatchanged[1] assume `--use-mailmap`, otherwise
- assume `--no-use-mailmap`. True by default.
-++
-+The behavior of `log.mailmap` is impacted by the setting of the more
-+general 'mailmap.*' configuration variables, i.e. `mailmap.file` and
-+`mailmap.blob`.
## Documentation/git-log.txt ##
-@@ Documentation/git-log.txt: OPTIONS
- shown. The option `--decorate` is short-hand for `--decorate=short`.
- Default to configuration value of `log.decorate` if configured,
- otherwise, `auto`.
-++
-+This output may be colored. See `color.ui` in linkgit:git-config[1]
-+and `color.decorate` there and in the "CONFIGURATION" section below.
-
- --decorate-refs=<pattern>::
- --decorate-refs-exclude=<pattern>::
@@ Documentation/git-log.txt: i18n.logOutputEncoding::
Defaults to the value of `i18n.commitEncoding` if set, and UTF-8
otherwise.
8: 5c379ab1476 ! 8: af912e9ca65 docs: add CONFIGURATION sections that map to a built-in
@@ Documentation/git-commit-graph.txt: $ git show-ref -s | git commit-graph write -
+include::config/commitgraph.txt[]
+
- GIT
- ---
+ FILE FORMAT
+ -----------
## Documentation/git-commit.txt ##
@@ Documentation/git-commit.txt: The editor used to edit the commit log message will be chosen from the
@@ Documentation/git-fast-import.txt: operator can use this facility to peek at the
--------
linkgit:git-fast-export[1]
+ ## Documentation/git-init.txt ##
+@@ Documentation/git-init.txt: $ git commit <3>
+ <2> Add all existing files to the index.
+ <3> Record the pristine state as the first commit in the history.
+
++CONFIGURATION
++-------------
++
++include::includes/cmd-config-section-all.txt[]
++
++include::config/init.txt[]
++
+ GIT
+ ---
+ Part of the linkgit:git[1] suite
+
## Documentation/git-mailinfo.txt ##
@@ Documentation/git-mailinfo.txt: If no such configuration option has been set, `warn` will be used.
<patch>::
9: 91689154926 ! 9: 5ef36654bba docs: add CONFIGURATION sections that fuzzy map to built-ins
@@ Commit message
* config/blame.txt: used by git-{blame,annotate}.txt. Since the
git-annotate(1) documentation refers to git-blame(1) don't add a
- "CONFIGURATION" section to git-annotate(1), only to git-blame(1)>
+ "CONFIGURATION" section to git-annotate(1), only to git-blame(1).
- * config/branch.txt: maps to both git-checkout.txt and
+ * config/checkout.txt: maps to both git-checkout.txt and
git-switch.txt (but nothing else).
* config/init.txt: should be included in git-init(1) and
@@ Commit message
Things that are being left out, and why:
- * config/remote.txt: let's not include this in
- git-{fetch,remote,push}.txt etc. for now, various options there
- change their behavior.
-
- * config/remotes.txt: As we're not including config/remote.txt for
- now, let's not include this one either.
-
- * config/credential.txt: let's not include this in
- git-credential.txt, it talks more generally about how the
- credential facility is used by various other commands, not that
- command in particular.
+ * config/{remote,remotes,credential}.txt: Configuration that affects
+ how we talk to remote repositories is harder to untangle. We'll need
+ to include some of this in git-{fetch,remote,push,ls-remote}.txt
+ etc., but some of those only use a small subset of these
+ options. Let's leave this for now.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
--
2.37.3.1406.g184357183a6
^ permalink raw reply [flat|nested] 56+ messages in thread
* [PATCH v3 1/9] docs: add and use include template for config/* includes
2022-08-31 8:41 ` [PATCH v3 " Ævar Arnfjörð Bjarmason
@ 2022-08-31 8:41 ` Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 2/9] grep docs: de-duplicate configuration sections Ævar Arnfjörð Bjarmason
` (9 subsequent siblings)
10 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-31 8:41 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
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>
---
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 bd6b6fcb930..849af6da307 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -62,6 +62,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 5088783dccb..29318ea957e 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 0af7540a0c8..a65c9aa62d6 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 63cf498ce9f..f7b18515141 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 fee1dc2df28..2d6a1391c89 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -383,13 +383,16 @@ include::merge-strategies.txt[]
CONFIGURATION
-------------
-include::config/merge.txt[]
branch.<name>.mergeOptions::
Sets default options for merging into branch <name>. 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 f784027bc13..c44e205629b 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 1877942180e..9cb8931c7ac 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -1259,6 +1259,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 00000000000..296a239f2ab
--- /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 00000000000..b1e7682c1dc
--- /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:
--
2.37.3.1406.g184357183a6
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v3 2/9] grep docs: de-duplicate configuration sections
2022-08-31 8:41 ` [PATCH v3 " Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 1/9] docs: add and use include template for config/* includes Ævar Arnfjörð Bjarmason
@ 2022-08-31 8:41 ` Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 3/9] send-email " Ævar Arnfjörð Bjarmason
` (8 subsequent siblings)
10 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-31 8:41 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
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.
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 <avarab@gmail.com>
---
Documentation/config/grep.txt | 7 +++++--
Documentation/git-grep.txt | 29 ++---------------------------
2 files changed, 7 insertions(+), 29 deletions(-)
diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt
index 182edd813a5..e521f20390c 100644
--- a/Documentation/config/grep.txt
+++ b/Documentation/config/grep.txt
@@ -17,8 +17,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 58d944bd578..dabdbe8471d 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -343,34 +343,9 @@ 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.
+include::includes/cmd-config-section-all.txt[]
+include::config/grep.txt[]
GIT
---
--
2.37.3.1406.g184357183a6
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v3 3/9] send-email docs: de-duplicate configuration sections
2022-08-31 8:41 ` [PATCH v3 " Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 1/9] docs: add and use include template for config/* includes Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 2/9] grep docs: de-duplicate configuration sections Ævar Arnfjörð Bjarmason
@ 2022-08-31 8:41 ` Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 4/9] apply " Ævar Arnfjörð Bjarmason
` (7 subsequent siblings)
10 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-31 8:41 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
De-duplicate the discussion of "send-email" configuration, such that
the "git-config(1)" manual page becomes the source of truth, and
"git-send-email(1)" includes the relevant part.
Most commands that suffered from such duplication had diverging text
discussing the same variables, but in this case some config was also
only discussed in one or the other.
This is mostly a move-only change, the exception is a minor rewording
of changing wording like "see above" to "see linkgit:git-config[1]",
as well as a clarification about the big section of command-line
option tweaking config being discussed in git-send-email(1)'s main
docs.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/config/sendemail.txt | 40 +++++++++++++++++++++++++++---
Documentation/git-send-email.txt | 36 ++-------------------------
2 files changed, 39 insertions(+), 37 deletions(-)
diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt
index 50baa5d6bfb..51da7088a84 100644
--- a/Documentation/config/sendemail.txt
+++ b/Documentation/config/sendemail.txt
@@ -18,17 +18,49 @@ sendemail.<identity>.*::
identity is selected, through either the command-line or
`sendemail.identity`.
+sendemail.multiEdit::
+ If true (default), a single editor instance will be spawned to edit
+ files you have to edit (patches when `--annotate` is used, and the
+ summary when `--compose` is used). If false, files will be edited one
+ after the other, spawning a new editor each time.
+
+sendemail.confirm::
+ Sets the default for whether to confirm before sending. Must be
+ one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`
+ in the linkgit:git-send-email[1] documentation for the meaning of these
+ values.
+
sendemail.aliasesFile::
+ To avoid typing long email addresses, point this to one or more
+ email aliases files. You must also supply `sendemail.aliasFileType`.
+
sendemail.aliasFileType::
+ Format of the file(s) specified in sendemail.aliasesFile. Must be
+ one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.
++
+What an alias file in each format looks like can be found in
+the documentation of the email program of the same name. The
+differences and limitations from the standard formats are
+described below:
++
+--
+sendmail;;
+* Quoted aliases and quoted addresses are not supported: lines that
+ contain a `"` symbol are ignored.
+* Redirection to a file (`/path/name`) or pipe (`|command`) is not
+ supported.
+* File inclusion (`:include: /path/name`) is not supported.
+* Warnings are printed on the standard error output for any
+ explicitly unsupported constructs, and any other lines that are not
+ recognized by the parser.
+--
sendemail.annotate::
sendemail.bcc::
sendemail.cc::
sendemail.ccCmd::
sendemail.chainReplyTo::
-sendemail.confirm::
sendemail.envelopeSender::
sendemail.from::
-sendemail.multiEdit::
sendemail.signedoffbycc::
sendemail.smtpPass::
sendemail.suppresscc::
@@ -44,7 +76,9 @@ sendemail.thread::
sendemail.transferEncoding::
sendemail.validate::
sendemail.xmailer::
- See linkgit:git-send-email[1] for description.
+ These configuration variables all provide a default for
+ linkgit:git-send-email[1] command-line options. See its
+ documentation for details.
sendemail.signedoffcc (deprecated)::
Deprecated alias for `sendemail.signedoffbycc`.
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 41cd8cb4247..3290043053a 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -456,41 +456,9 @@ Information
CONFIGURATION
-------------
-sendemail.aliasesFile::
- To avoid typing long email addresses, point this to one or more
- email aliases files. You must also supply `sendemail.aliasFileType`.
+include::includes/cmd-config-section-all.txt[]
-sendemail.aliasFileType::
- Format of the file(s) specified in sendemail.aliasesFile. Must be
- one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.
-+
-What an alias file in each format looks like can be found in
-the documentation of the email program of the same name. The
-differences and limitations from the standard formats are
-described below:
-+
---
-sendmail;;
-* Quoted aliases and quoted addresses are not supported: lines that
- contain a `"` symbol are ignored.
-* Redirection to a file (`/path/name`) or pipe (`|command`) is not
- supported.
-* File inclusion (`:include: /path/name`) is not supported.
-* Warnings are printed on the standard error output for any
- explicitly unsupported constructs, and any other lines that are not
- recognized by the parser.
---
-
-sendemail.multiEdit::
- If true (default), a single editor instance will be spawned to edit
- files you have to edit (patches when `--annotate` is used, and the
- summary when `--compose` is used). If false, files will be edited one
- after the other, spawning a new editor each time.
-
-sendemail.confirm::
- Sets the default for whether to confirm before sending. Must be
- one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`
- in the previous section for the meaning of these values.
+include::config/sendemail.txt[]
EXAMPLES
--------
--
2.37.3.1406.g184357183a6
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v3 4/9] apply docs: de-duplicate configuration sections
2022-08-31 8:41 ` [PATCH v3 " Ævar Arnfjörð Bjarmason
` (2 preceding siblings ...)
2022-08-31 8:41 ` [PATCH v3 3/9] send-email " Ævar Arnfjörð Bjarmason
@ 2022-08-31 8:41 ` Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 5/9] notes docs: de-duplicate and combine " Ævar Arnfjörð Bjarmason
` (6 subsequent siblings)
10 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-31 8:41 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
The wording is not identical to Documentation/config/apply.txt, but
that version is better.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-apply.txt | 10 +++-------
1 file changed, 3 insertions(+), 7 deletions(-)
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index b6d77f42068..1d478cbe9b5 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -263,13 +263,9 @@ has no effect when `--index` or `--cached` is in use.
CONFIGURATION
-------------
-apply.ignoreWhitespace::
- Set to 'change' if you want changes in whitespace to be ignored by default.
- Set to one of: no, none, never, false if you want changes in
- whitespace to be significant.
-apply.whitespace::
- When no `--whitespace` flag is given from the command
- line, this configuration item is used as the default.
+include::includes/cmd-config-section-all.txt[]
+
+include::config/apply.txt[]
SUBMODULES
----------
--
2.37.3.1406.g184357183a6
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v3 5/9] notes docs: de-duplicate and combine configuration sections
2022-08-31 8:41 ` [PATCH v3 " Ævar Arnfjörð Bjarmason
` (3 preceding siblings ...)
2022-08-31 8:41 ` [PATCH v3 4/9] apply " Ævar Arnfjörð Bjarmason
@ 2022-08-31 8:41 ` Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 6/9] difftool docs: de-duplicate " Ævar Arnfjörð Bjarmason
` (5 subsequent siblings)
10 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-31 8:41 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
Combine the various "notes" configuration sections spread across
Documentation/config/notes.txt and Documentation/git-notes.txt to live
in the former, and to be included in the latter.
We'll now forward link from "git notes" to the "CONFIGURATION" section
below, rather than to "git-config(1)" when discussing configuration
variables that are (also) discussed in that section.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/config/notes.txt | 43 +++++++++++++++-----------
Documentation/git-log.txt | 16 ++--------
Documentation/git-notes.txt | 55 +++-------------------------------
3 files changed, 33 insertions(+), 81 deletions(-)
diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt
index aeef56d49ae..c7c4811734b 100644
--- a/Documentation/config/notes.txt
+++ b/Documentation/config/notes.txt
@@ -3,6 +3,9 @@ notes.mergeStrategy::
conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or
`cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES"
section of linkgit:git-notes[1] for more information on each strategy.
++
+This setting can be overridden by passing the `--strategy` option to
+linkgit:git-notes[1].
notes.<name>.mergeStrategy::
Which merge strategy to choose when doing a notes merge into
@@ -11,28 +14,35 @@ notes.<name>.mergeStrategy::
linkgit:git-notes[1] for more information on the available strategies.
notes.displayRef::
- The (fully qualified) refname from which to show notes when
- showing commit messages. The value of this variable can be set
- to a glob, in which case notes from all matching refs will be
- shown. You may also specify this configuration variable
- several times. A warning will be issued for refs that do not
- exist, but a glob that does not match any refs is silently
- ignored.
+ Which ref (or refs, if a glob or specified more than once), in
+ addition to the default set by `core.notesRef` or
+ `GIT_NOTES_REF`, to read notes from when showing commit
+ messages with the 'git log' family of commands.
+
This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`
environment variable, which must be a colon separated list of refs or
globs.
+
+A warning will be issued for refs that do not exist,
+but a glob that does not match any refs is silently ignored.
++
+This setting can be disabled by the `--no-notes` option to the 'git
+log' family of commands, or by the `--notes=<ref>` option accepted by
+those commands.
++
The effective value of "core.notesRef" (possibly overridden by
GIT_NOTES_REF) is also implicitly added to the list of refs to be
displayed.
notes.rewrite.<command>::
When rewriting commits with <command> (currently `amend` or
- `rebase`) and this variable is set to `true`, Git
- automatically copies your notes from the original to the
- rewritten commit. Defaults to `true`, but see
- "notes.rewriteRef" below.
+ `rebase`), if this variable is `false`, git will not copy
+ notes from the original to the rewritten commit. Defaults to
+ `true`. See also "`notes.rewriteRef`" below.
++
+This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
+environment variable, which must be a colon separated list of refs or
+globs.
notes.rewriteMode::
When copying notes during a rewrite (see the
@@ -46,14 +56,13 @@ environment variable.
notes.rewriteRef::
When copying notes during a rewrite, specifies the (fully
- qualified) ref whose notes should be copied. The ref may be a
- glob, in which case notes in all matching refs will be copied.
- You may also specify this configuration several times.
+ qualified) ref whose notes should be copied. May be a glob,
+ in which case notes in all matching refs will be copied. You
+ may also specify this configuration several times.
+
Does not have a default value; you must configure this variable to
enable note rewriting. Set it to `refs/notes/commits` to enable
rewriting for the default commit notes.
+
-This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
-environment variable, which must be a colon separated list of refs or
-globs.
+Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.
+See `notes.rewrite.<command>` above for a further description of its format.
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index b1285aee3c2..410095e9a4f 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -237,19 +237,9 @@ log.showSignature::
mailmap.*::
See linkgit:git-shortlog[1].
-notes.displayRef::
- Which refs, in addition to the default set by `core.notesRef`
- or `GIT_NOTES_REF`, to read notes from when showing commit
- messages with the `log` family of commands. See
- linkgit:git-notes[1].
-+
-May be an unabbreviated ref name or a glob and may be specified
-multiple times. A warning will be issued for refs that do not exist,
-but a glob that does not match any refs is silently ignored.
-+
-This setting can be disabled by the `--no-notes` option,
-overridden by the `GIT_NOTES_DISPLAY_REF` environment variable,
-and overridden by the `--notes=<ref>` option.
+include::includes/cmd-config-section-rest.txt[]
+
+include::config/notes.txt[]
GIT
---
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 0a4200674c4..efbc10f0f59 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -44,7 +44,7 @@ using the `--notes` option. Such notes are added as a patch commentary
after a three dash separator line.
To change which notes are shown by 'git log', see the
-"notes.displayRef" configuration in linkgit:git-log[1].
+"notes.displayRef" discussion in <<CONFIGURATION>>.
See the "notes.rewrite.<command>" configuration for a way to carry
notes across commands that rewrite commits.
@@ -307,6 +307,7 @@ with 'git log', so if you use such notes, you'll probably need to write
some special-purpose tools to do something useful with them.
+[[CONFIGURATION]]
CONFIGURATION
-------------
@@ -316,57 +317,9 @@ core.notesRef::
This setting can be overridden through the environment and
command line.
-notes.mergeStrategy::
- Which merge strategy to choose by default when resolving notes
- conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or
- `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES"
- section above for more information on each strategy.
-+
-This setting can be overridden by passing the `--strategy` option.
-
-notes.<name>.mergeStrategy::
- Which merge strategy to choose when doing a notes merge into
- refs/notes/<name>. This overrides the more general
- "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section above
- for more information on each available strategy.
-
-notes.displayRef::
- Which ref (or refs, if a glob or specified more than once), in
- addition to the default set by `core.notesRef` or
- `GIT_NOTES_REF`, to read notes from when showing commit
- messages with the 'git log' family of commands.
- This setting can be overridden on the command line or by the
- `GIT_NOTES_DISPLAY_REF` environment variable.
- See linkgit:git-log[1].
-
-notes.rewrite.<command>::
- When rewriting commits with <command> (currently `amend` or
- `rebase`), if this variable is `false`, git will not copy
- notes from the original to the rewritten commit. Defaults to
- `true`. See also "`notes.rewriteRef`" below.
-+
-This setting can be overridden by the `GIT_NOTES_REWRITE_REF`
-environment variable.
+include::includes/cmd-config-section-rest.txt[]
-notes.rewriteMode::
- When copying notes during a rewrite, what to do if the target
- commit already has a note. Must be one of `overwrite`,
- `concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to
- `concatenate`.
-+
-This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
-environment variable.
-
-notes.rewriteRef::
- When copying notes during a rewrite, specifies the (fully
- qualified) ref whose notes should be copied. May be a glob,
- in which case notes in all matching refs will be copied. You
- may also specify this configuration several times.
-+
-Does not have a default value; you must configure this variable to
-enable note rewriting.
-+
-Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.
+include::config/notes.txt[]
ENVIRONMENT
--
2.37.3.1406.g184357183a6
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v3 6/9] difftool docs: de-duplicate configuration sections
2022-08-31 8:41 ` [PATCH v3 " Ævar Arnfjörð Bjarmason
` (4 preceding siblings ...)
2022-08-31 8:41 ` [PATCH v3 5/9] notes docs: de-duplicate and combine " Ævar Arnfjörð Bjarmason
@ 2022-08-31 8:41 ` Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 7/9] log " Ævar Arnfjörð Bjarmason
` (4 subsequent siblings)
10 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-31 8:41 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
Include the "config/difftool.txt" file in "git-difftool.txt", and move
the relevant part of git-difftool(1) configuration from
"config/diff.txt" to config/difftool.txt".
Doing this is slightly odd, as we usually discuss configuration in
alphabetical order, but by doing it we're able to include the full set
of configuration used by git-difftool(1) (and only that configuration)
in its own documentation.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/config/diff.txt | 15 ---------------
Documentation/config/difftool.txt | 28 +++++++++++++++++++++++++---
Documentation/git-difftool.txt | 27 ++++-----------------------
3 files changed, 29 insertions(+), 41 deletions(-)
diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt
index 32f84838ac1..35a7bf86d77 100644
--- a/Documentation/config/diff.txt
+++ b/Documentation/config/diff.txt
@@ -178,21 +178,6 @@ diff.<driver>.cachetextconv::
Set this option to true to make the diff driver cache the text
conversion outputs. See linkgit:gitattributes[5] for details.
-diff.tool::
- Controls which diff tool is used by linkgit:git-difftool[1].
- This variable overrides the value configured in `merge.tool`.
- The list below shows the valid built-in values.
- Any other value is treated as a custom diff tool and requires
- that a corresponding difftool.<tool>.cmd variable is defined.
-
-diff.guitool::
- Controls which diff tool is used by linkgit:git-difftool[1] when
- the -g/--gui flag is specified. This variable overrides the value
- configured in `merge.guitool`. The list below shows the valid
- built-in values. Any other value is treated as a custom diff tool
- and requires that a corresponding difftool.<guitool>.cmd variable
- is defined.
-
include::../mergetools-diff.txt[]
diff.indentHeuristic::
diff --git a/Documentation/config/difftool.txt b/Documentation/config/difftool.txt
index 67625944804..a3f82112102 100644
--- a/Documentation/config/difftool.txt
+++ b/Documentation/config/difftool.txt
@@ -1,6 +1,17 @@
-difftool.<tool>.path::
- Override the path for the given tool. This is useful in case
- your tool is not in the PATH.
+diff.tool::
+ Controls which diff tool is used by linkgit:git-difftool[1].
+ This variable overrides the value configured in `merge.tool`.
+ The list below shows the valid built-in values.
+ Any other value is treated as a custom diff tool and requires
+ that a corresponding difftool.<tool>.cmd variable is defined.
+
+diff.guitool::
+ Controls which diff tool is used by linkgit:git-difftool[1] when
+ the -g/--gui flag is specified. This variable overrides the value
+ configured in `merge.guitool`. The list below shows the valid
+ built-in values. Any other value is treated as a custom diff tool
+ and requires that a corresponding difftool.<guitool>.cmd variable
+ is defined.
difftool.<tool>.cmd::
Specify the command to invoke the specified diff tool.
@@ -9,6 +20,17 @@ difftool.<tool>.cmd::
file containing the contents of the diff pre-image and 'REMOTE'
is set to the name of the temporary file containing the contents
of the diff post-image.
++
+See the `--tool=<tool>` option in linkgit:git-difftool[1] for more details.
+
+difftool.<tool>.path::
+ Override the path for the given tool. This is useful in case
+ your tool is not in the PATH.
+
+difftool.trustExitCode::
+ Exit difftool if the invoked diff tool returns a non-zero exit status.
++
+See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details.
difftool.prompt::
Prompt before each invocation of the diff tool.
diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt
index 143b0c49d73..9d14c3c9f09 100644
--- a/Documentation/git-difftool.txt
+++ b/Documentation/git-difftool.txt
@@ -113,33 +113,14 @@ instead. `--no-symlinks` is the default on Windows.
See linkgit:git-diff[1] for the full list of supported options.
-CONFIG VARIABLES
-----------------
+CONFIGURATION
+-------------
'git difftool' falls back to 'git mergetool' config variables when the
difftool equivalents have not been defined.
-diff.tool::
- The default diff tool to use.
+include::includes/cmd-config-section-rest.txt[]
-diff.guitool::
- The default diff tool to use when `--gui` is specified.
-
-difftool.<tool>.path::
- Override the path for the given tool. This is useful in case
- your tool is not in the PATH.
-
-difftool.<tool>.cmd::
- Specify the command to invoke the specified diff tool.
-+
-See the `--tool=<tool>` option above for more details.
-
-difftool.prompt::
- Prompt before each invocation of the diff tool.
-
-difftool.trustExitCode::
- Exit difftool if the invoked diff tool returns a non-zero exit status.
-+
-See the `--trust-exit-code` option above for more details.
+include::config/difftool.txt[]
SEE ALSO
--------
--
2.37.3.1406.g184357183a6
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v3 7/9] log docs: de-duplicate configuration sections
2022-08-31 8:41 ` [PATCH v3 " Ævar Arnfjörð Bjarmason
` (5 preceding siblings ...)
2022-08-31 8:41 ` [PATCH v3 6/9] difftool docs: de-duplicate " Ævar Arnfjörð Bjarmason
@ 2022-08-31 8:41 ` Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 8/9] docs: add CONFIGURATION sections that map to a built-in Ævar Arnfjörð Bjarmason
` (3 subsequent siblings)
10 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-31 8:41 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/config/log.txt | 4 ++++
Documentation/git-log.txt | 30 ++----------------------------
2 files changed, 6 insertions(+), 28 deletions(-)
diff --git a/Documentation/config/log.txt b/Documentation/config/log.txt
index 5250ba45fb4..bc63bc3939c 100644
--- a/Documentation/config/log.txt
+++ b/Documentation/config/log.txt
@@ -7,6 +7,10 @@ log.date::
Set the default date-time mode for the 'log' command.
Setting a value for log.date is similar to using 'git log''s
`--date` option. See linkgit:git-log[1] for details.
++
+If the format is set to "auto:foo" and the pager is in use, format
+"foo" will be the used for the date format. Otherwise "default" will
+be used.
log.decorate::
Print out the ref names of any commits that are shown by the log
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 410095e9a4f..2a66cf88807 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -209,36 +209,10 @@ i18n.logOutputEncoding::
Defaults to the value of `i18n.commitEncoding` if set, and UTF-8
otherwise.
-log.date::
- Default format for human-readable dates. (Compare the
- `--date` option.) Defaults to "default", which means to write
- dates like `Sat May 8 19:35:34 2010 -0500`.
-+
-If the format is set to "auto:foo" and the pager is in use, format
-"foo" will be the used for the date format. Otherwise "default" will
-be used.
-
-log.follow::
- If `true`, `git log` will act as if the `--follow` option was used when
- a single <path> is given. This has the same limitations as `--follow`,
- i.e. it cannot be used to follow multiple files and does not work well
- on non-linear history.
-
-log.showRoot::
- If `false`, `git log` and related commands will not treat the
- initial commit as a big creation event. Any root commits in
- `git log -p` output would be shown without a diff attached.
- The default is `true`.
-
-log.showSignature::
- If `true`, `git log` and related commands will act as if the
- `--show-signature` option was passed to them.
-
-mailmap.*::
- See linkgit:git-shortlog[1].
-
include::includes/cmd-config-section-rest.txt[]
+include::config/log.txt[]
+
include::config/notes.txt[]
GIT
--
2.37.3.1406.g184357183a6
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v3 8/9] docs: add CONFIGURATION sections that map to a built-in
2022-08-31 8:41 ` [PATCH v3 " Ævar Arnfjörð Bjarmason
` (6 preceding siblings ...)
2022-08-31 8:41 ` [PATCH v3 7/9] log " Ævar Arnfjörð Bjarmason
@ 2022-08-31 8:41 ` Ævar Arnfjörð Bjarmason
2022-08-31 8:41 ` [PATCH v3 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins Ævar Arnfjörð Bjarmason
` (2 subsequent siblings)
10 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-31 8:41 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
Add a CONFIGURATION section to the documentation of various built-ins,
for those cases where the relevant config/NAME.txt describes
configuration that is only used by the relevant built-in documented in
git-NAME.txt. Subsequent commits will handle more complex cases.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-add.txt | 7 +++++++
Documentation/git-am.txt | 7 +++++++
Documentation/git-clean.txt | 7 +++++++
Documentation/git-clone.txt | 7 +++++++
Documentation/git-commit-graph.txt | 7 +++++++
Documentation/git-commit.txt | 4 ++++
Documentation/git-fast-import.txt | 7 +++++++
Documentation/git-init.txt | 7 +++++++
Documentation/git-mailinfo.txt | 7 +++++++
Documentation/git-maintenance.txt | 7 +++++++
Documentation/git-push.txt | 7 +++++++
Documentation/git-revert.txt | 7 +++++++
Documentation/git-show-branch.txt | 7 +++++++
Documentation/git-stash.txt | 7 +++++++
14 files changed, 95 insertions(+)
diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 9b37f356542..a030d33c6e7 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -433,6 +433,13 @@ they will make the patch impossible to apply:
* deleting context or removal lines
* modifying the contents of context or removal lines
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/add.txt[]
+
SEE ALSO
--------
linkgit:git-status[1]
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 320da6c4f76..326276e51ce 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -258,6 +258,13 @@ This command can run `applypatch-msg`, `pre-applypatch`,
and `post-applypatch` hooks. See linkgit:githooks[5] for more
information.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/am.txt[]
+
SEE ALSO
--------
linkgit:git-apply[1].
diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index a7f309dff5a..91742633fa8 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -133,6 +133,13 @@ help::
Show brief usage of interactive git-clean.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/clean.txt[]
+
SEE ALSO
--------
linkgit:gitignore[5]
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 632bd1348ea..b9ee8a87238 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -363,6 +363,13 @@ $ cd my-linux
$ git clone --bare -l /home/proj/.git /pub/scm/proj.git
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/clone.txt[]
+
GIT
---
diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
index 047decdb65b..36fe56c2c71 100644
--- a/Documentation/git-commit-graph.txt
+++ b/Documentation/git-commit-graph.txt
@@ -142,6 +142,13 @@ $ git show-ref -s | git commit-graph write --stdin-commits
$ git rev-parse HEAD | git commit-graph write --stdin-commits --append
------------------------------------------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/commitgraph.txt[]
+
FILE FORMAT
-----------
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 6c60bf98f9f..225c6c9f2e5 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -557,6 +557,10 @@ The editor used to edit the commit log message will be chosen from the
`VISUAL` environment variable, or the `EDITOR` environment variable (in that
order). See linkgit:git-var[1] for details.
+include::includes/cmd-config-section-rest.txt[]
+
+include::config/commit.txt[]
+
HOOKS
-----
This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`,
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 39cfa05b28b..8b5dd6add00 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -1564,6 +1564,13 @@ operator can use this facility to peek at the objects and refs from an
import in progress, at the cost of some added running time and worse
compression.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/fastimport.txt[]
+
SEE ALSO
--------
linkgit:git-fast-export[1]
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index ad921fe782e..160dea1372c 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -169,6 +169,13 @@ $ git commit <3>
<2> Add all existing files to the index.
<3> Record the pristine state as the first commit in the history.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/init.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt
index 3fcfd965fde..28060283c70 100644
--- a/Documentation/git-mailinfo.txt
+++ b/Documentation/git-mailinfo.txt
@@ -115,6 +115,13 @@ If no such configuration option has been set, `warn` will be used.
<patch>::
The patch extracted from e-mail.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/mailinfo.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt
index e56bad28c65..9c630efe19c 100644
--- a/Documentation/git-maintenance.txt
+++ b/Documentation/git-maintenance.txt
@@ -397,6 +397,13 @@ If you want to customize the background tasks, please rename the tasks
so future calls to `git maintenance (start|stop)` do not overwrite your
custom tasks.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/maintenance.txt[]
+
GIT
---
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 2f25aa3a291..def7657ef9c 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -692,6 +692,13 @@ a `git gc` command on the origin repository.
include::transfer-data-leaks.txt[]
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/push.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index 0105a54c1a5..5016755efb6 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -142,6 +142,13 @@ EXAMPLES
changes. The revert only modifies the working tree and the
index.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/revert.txt[]
+
SEE ALSO
--------
linkgit:git-cherry-pick[1]
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index 5cc2fcefbab..e5ec6b467f9 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -199,6 +199,13 @@ shows 10 reflog entries going back from the tip as of 1 hour ago.
Without `--list`, the output also shows how these tips are
topologically related with each other.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/showbranch.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 6e15f475257..c5d70918283 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -382,6 +382,13 @@ grep commit | cut -d\ -f3 |
xargs git log --merges --no-walk --grep=WIP
----------------------------------------------------------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/stash.txt[]
+
SEE ALSO
--------
--
2.37.3.1406.g184357183a6
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v3 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins
2022-08-31 8:41 ` [PATCH v3 " Ævar Arnfjörð Bjarmason
` (7 preceding siblings ...)
2022-08-31 8:41 ` [PATCH v3 8/9] docs: add CONFIGURATION sections that map to a built-in Ævar Arnfjörð Bjarmason
@ 2022-08-31 8:41 ` Ævar Arnfjörð Bjarmason
2022-09-03 13:29 ` [PATCH v3 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Matheus Tavares
2022-09-07 8:26 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
10 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-08-31 8:41 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
Add a CONFIGURATION section to the documentation of various built-ins,
for those cases where the relevant config/NAME.txt doesn't map only to
one git-NAME.txt. In particular:
* config/blame.txt: used by git-{blame,annotate}.txt. Since the
git-annotate(1) documentation refers to git-blame(1) don't add a
"CONFIGURATION" section to git-annotate(1), only to git-blame(1).
* config/checkout.txt: maps to both git-checkout.txt and
git-switch.txt (but nothing else).
* config/init.txt: should be included in git-init(1) and
git-clone(1).
* config/column.txt: We should ideally mention the relevant subset of
this in git-{branch,clean,status,tag}.txt, but let's punt on it for
now. We will when we eventually split these sort of files into
e.g. config/column.txt and
config/column/{branch,clean,status,tag}.txt, with the former
including the latter set.
Things that are being left out, and why:
* config/{remote,remotes,credential}.txt: Configuration that affects
how we talk to remote repositories is harder to untangle. We'll need
to include some of this in git-{fetch,remote,push,ls-remote}.txt
etc., but some of those only use a small subset of these
options. Let's leave this for now.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-blame.txt | 6 ++++++
Documentation/git-branch.txt | 4 ++++
Documentation/git-checkout.txt | 7 +++++++
Documentation/git-clone.txt | 2 ++
Documentation/git-column.txt | 7 +++++++
Documentation/git-diff.txt | 7 +++++++
Documentation/git-fetch.txt | 7 +++++++
Documentation/git-switch.txt | 7 +++++++
8 files changed, 47 insertions(+)
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index d7a46cc6744..4400a17330b 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -241,6 +241,12 @@ MAPPING AUTHORS
See linkgit:gitmailmap[5].
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/blame.txt[]
SEE ALSO
--------
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index ae82378349d..12c5f84e3be 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -336,6 +336,10 @@ CONFIGURATION
`--list` is used or implied. The default is to use a pager.
See linkgit:git-config[1].
+include::includes/cmd-config-section-rest.txt[]
+
+include::config/branch.txt[]
+
EXAMPLES
--------
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 9f37e22e130..4cb9d555b4b 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -600,6 +600,13 @@ $ edit frotz
$ git add frotz
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/checkout.txt[]
+
SEE ALSO
--------
linkgit:git-switch[1],
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index b9ee8a87238..43955a3b504 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -368,6 +368,8 @@ CONFIGURATION
include::includes/cmd-config-section-all.txt[]
+include::config/init.txt[]
+
include::config/clone.txt[]
diff --git a/Documentation/git-column.txt b/Documentation/git-column.txt
index 6cea9ab4638..18431647a2d 100644
--- a/Documentation/git-column.txt
+++ b/Documentation/git-column.txt
@@ -74,6 +74,13 @@ v2.4.3 v2.4.4 v2.4.5 v2.4.6 v2.4.7
v2.4.8 v2.4.9
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/column.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 6236c75c9b8..85ae6d6d08a 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -213,6 +213,13 @@ $ git diff -R <2>
rewrites (very expensive).
<2> Output diff in reverse.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/diff.txt[]
+
SEE ALSO
--------
diff(1),
diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index e9d364669af..63d9569e164 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt
@@ -285,6 +285,13 @@ linkgit:git-gc[1]).
include::transfer-data-leaks.txt[]
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/fetch.txt[]
+
BUGS
----
Using --recurse-submodules can only fetch new commits in submodules that are
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index bbcbdceb459..c60fc9c138b 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -265,6 +265,13 @@ always create a new name for it (without switching away):
$ git switch -c good-surprises
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/checkout.txt[]
+
SEE ALSO
--------
linkgit:git-checkout[1],
--
2.37.3.1406.g184357183a6
^ permalink raw reply related [flat|nested] 56+ messages in thread
* Re: [PATCH v3 0/9] docs: de-duplicate sections, add more CONFIGURATION sections
2022-08-31 8:41 ` [PATCH v3 " Ævar Arnfjörð Bjarmason
` (8 preceding siblings ...)
2022-08-31 8:41 ` [PATCH v3 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins Ævar Arnfjörð Bjarmason
@ 2022-09-03 13:29 ` Matheus Tavares
2022-09-07 8:26 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
10 siblings, 0 replies; 56+ messages in thread
From: Matheus Tavares @ 2022-09-03 13:29 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Junio C Hamano
Hi, Ævar
Thanks for the reroll. I looked at the range-diff, and you've
addressed almost all of my comments from the previous version. I only
spot one issue:
On Wed, Aug 31, 2022 at 5:41 AM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
> Range-diff against v2:
> [...]
> 8: 5c379ab1476 ! 8: af912e9ca65 docs: add CONFIGURATION sections that map to a built-in
> @@ Documentation/git-fast-import.txt: operator can use this facility to peek at the
> --------
> linkgit:git-fast-export[1]
>
> + ## Documentation/git-init.txt ##
> +@@ Documentation/git-init.txt: $ git commit <3>
> + <2> Add all existing files to the index.
> + <3> Record the pristine state as the first commit in the history.
> +
> ++CONFIGURATION
> ++-------------
> ++
> ++include::includes/cmd-config-section-all.txt[]
> ++
> ++include::config/init.txt[]
> ++
> + GIT
> + ---
> + Part of the linkgit:git[1] suite
> +
Shouldn't this change be part of commit 9 instead of 8?
^ permalink raw reply [flat|nested] 56+ messages in thread
* [PATCH v4 0/9] docs: de-duplicate sections, add more CONFIGURATION sections
2022-08-31 8:41 ` [PATCH v3 " Ævar Arnfjörð Bjarmason
` (9 preceding siblings ...)
2022-09-03 13:29 ` [PATCH v3 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Matheus Tavares
@ 2022-09-07 8:26 ` Ævar Arnfjörð Bjarmason
2022-09-07 8:26 ` [PATCH v4 1/9] docs: add and use include template for config/* includes Ævar Arnfjörð Bjarmason
` (9 more replies)
10 siblings, 10 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-07 8:26 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
This series:
* De-duplicates and combines configuration discussion that was split
or spread across Documentation/config/*.txt and
Documentation/git-*.txt, moving it to Documentation/config/*.txt.
* Includes that relevant Documentation/config/*.txt in the
Documentation/git-*.txt files.
* Introduces and uses included prose for those "CONFIGURATION"
sections in various Documentation/git-*.txt files, informing the
reader that what they see there is included from "git-config(1)".
This v4 addresses the feedback from Matheus Tavares on v3 (thanks for
the review!): A hunk belonged in 9/9, not 8/9 (init's config is used
by e.g. "clone" too). The end-state at the end of this series is
exactly the same.
1. https://lore.kernel.org/git/CAHd-oW4QpPBUqo5ToWXtBg7-LHbEam7aqSALSrwaA3OABma8ng@mail.gmail.com/
Ævar Arnfjörð Bjarmason (9):
docs: add and use include template for config/* includes
grep docs: de-duplicate configuration sections
send-email docs: de-duplicate configuration sections
apply docs: de-duplicate configuration sections
notes docs: de-duplicate and combine configuration sections
difftool docs: de-duplicate configuration sections
log docs: de-duplicate configuration sections
docs: add CONFIGURATION sections that map to a built-in
docs: add CONFIGURATION sections that fuzzy map to built-ins
Documentation/Makefile | 1 +
Documentation/config/diff.txt | 15 -----
Documentation/config/difftool.txt | 28 +++++++++-
Documentation/config/grep.txt | 7 ++-
Documentation/config/log.txt | 4 ++
Documentation/config/notes.txt | 43 +++++++++------
Documentation/config/sendemail.txt | 40 +++++++++++++-
Documentation/git-add.txt | 7 +++
Documentation/git-am.txt | 7 +++
Documentation/git-apply.txt | 10 +---
Documentation/git-blame.txt | 6 ++
Documentation/git-branch.txt | 4 ++
Documentation/git-checkout.txt | 7 +++
Documentation/git-clean.txt | 7 +++
Documentation/git-clone.txt | 9 +++
Documentation/git-column.txt | 7 +++
Documentation/git-commit-graph.txt | 7 +++
Documentation/git-commit.txt | 4 ++
Documentation/git-diff.txt | 7 +++
Documentation/git-difftool.txt | 27 ++-------
Documentation/git-fast-import.txt | 7 +++
Documentation/git-fetch.txt | 7 +++
Documentation/git-fsck.txt | 2 +
Documentation/git-gc.txt | 3 +-
Documentation/git-grep.txt | 29 +---------
Documentation/git-imap-send.txt | 2 +
Documentation/git-init.txt | 7 +++
Documentation/git-log.txt | 46 ++--------------
Documentation/git-mailinfo.txt | 7 +++
Documentation/git-maintenance.txt | 7 +++
Documentation/git-merge.txt | 5 +-
Documentation/git-mergetool.txt | 3 +
Documentation/git-notes.txt | 55 ++-----------------
Documentation/git-push.txt | 7 +++
Documentation/git-rebase.txt | 2 +
Documentation/git-revert.txt | 7 +++
Documentation/git-send-email.txt | 36 +-----------
Documentation/git-show-branch.txt | 7 +++
Documentation/git-stash.txt | 7 +++
Documentation/git-switch.txt | 7 +++
.../includes/cmd-config-section-all.txt | 3 +
.../includes/cmd-config-section-rest.txt | 3 +
42 files changed, 280 insertions(+), 226 deletions(-)
create mode 100644 Documentation/includes/cmd-config-section-all.txt
create mode 100644 Documentation/includes/cmd-config-section-rest.txt
Range-diff against v3:
1: da21c19978c = 1: ddcae390002 docs: add and use include template for config/* includes
2: d16e927caa2 = 2: e5ad838e1d7 grep docs: de-duplicate configuration sections
3: c36feb6f35a = 3: f73c148a06e send-email docs: de-duplicate configuration sections
4: 5707c9dd635 = 4: 5523095fe7e apply docs: de-duplicate configuration sections
5: 5b0ea00aa33 = 5: 9f1b90298d8 notes docs: de-duplicate and combine configuration sections
6: c4c3fa14190 = 6: 73e6804db13 difftool docs: de-duplicate configuration sections
7: e07585ba085 = 7: 6465a98ec0a log docs: de-duplicate configuration sections
8: af912e9ca65 ! 8: 929fd693bdf docs: add CONFIGURATION sections that map to a built-in
@@ Documentation/git-fast-import.txt: operator can use this facility to peek at the
--------
linkgit:git-fast-export[1]
- ## Documentation/git-init.txt ##
-@@ Documentation/git-init.txt: $ git commit <3>
- <2> Add all existing files to the index.
- <3> Record the pristine state as the first commit in the history.
-
-+CONFIGURATION
-+-------------
-+
-+include::includes/cmd-config-section-all.txt[]
-+
-+include::config/init.txt[]
-+
- GIT
- ---
- Part of the linkgit:git[1] suite
-
## Documentation/git-mailinfo.txt ##
@@ Documentation/git-mailinfo.txt: If no such configuration option has been set, `warn` will be used.
<patch>::
9: 5ef36654bba ! 9: 738ee46512d docs: add CONFIGURATION sections that fuzzy map to built-ins
@@ Documentation/git-fetch.txt: linkgit:git-gc[1]).
----
Using --recurse-submodules can only fetch new commits in submodules that are
+ ## Documentation/git-init.txt ##
+@@ Documentation/git-init.txt: $ git commit <3>
+ <2> Add all existing files to the index.
+ <3> Record the pristine state as the first commit in the history.
+
++CONFIGURATION
++-------------
++
++include::includes/cmd-config-section-all.txt[]
++
++include::config/init.txt[]
++
+ GIT
+ ---
+ Part of the linkgit:git[1] suite
+
## Documentation/git-switch.txt ##
@@ Documentation/git-switch.txt: always create a new name for it (without switching away):
$ git switch -c good-surprises
--
2.37.3.1490.g9adf4224da0
^ permalink raw reply [flat|nested] 56+ messages in thread
* [PATCH v4 1/9] docs: add and use include template for config/* includes
2022-09-07 8:26 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
@ 2022-09-07 8:26 ` Ævar Arnfjörð Bjarmason
2022-09-07 8:26 ` [PATCH v4 2/9] grep docs: de-duplicate configuration sections Ævar Arnfjörð Bjarmason
` (8 subsequent siblings)
9 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-07 8:26 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
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>
---
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 bd6b6fcb930..849af6da307 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -62,6 +62,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 5088783dccb..29318ea957e 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 0af7540a0c8..a65c9aa62d6 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 63cf498ce9f..f7b18515141 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 fee1dc2df28..2d6a1391c89 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -383,13 +383,16 @@ include::merge-strategies.txt[]
CONFIGURATION
-------------
-include::config/merge.txt[]
branch.<name>.mergeOptions::
Sets default options for merging into branch <name>. 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 f784027bc13..c44e205629b 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 1877942180e..9cb8931c7ac 100644
--- a/Documentation/git-rebase.txt
+++ b/Documentation/git-rebase.txt
@@ -1259,6 +1259,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 00000000000..296a239f2ab
--- /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 00000000000..b1e7682c1dc
--- /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:
--
2.37.3.1490.g9adf4224da0
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v4 2/9] grep docs: de-duplicate configuration sections
2022-09-07 8:26 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
2022-09-07 8:26 ` [PATCH v4 1/9] docs: add and use include template for config/* includes Ævar Arnfjörð Bjarmason
@ 2022-09-07 8:26 ` Ævar Arnfjörð Bjarmason
2022-09-07 8:26 ` [PATCH v4 3/9] send-email " Ævar Arnfjörð Bjarmason
` (7 subsequent siblings)
9 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-07 8:26 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
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.
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 <avarab@gmail.com>
---
Documentation/config/grep.txt | 7 +++++--
Documentation/git-grep.txt | 29 ++---------------------------
2 files changed, 7 insertions(+), 29 deletions(-)
diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt
index 182edd813a5..e521f20390c 100644
--- a/Documentation/config/grep.txt
+++ b/Documentation/config/grep.txt
@@ -17,8 +17,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 58d944bd578..dabdbe8471d 100644
--- a/Documentation/git-grep.txt
+++ b/Documentation/git-grep.txt
@@ -343,34 +343,9 @@ 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.
+include::includes/cmd-config-section-all.txt[]
+include::config/grep.txt[]
GIT
---
--
2.37.3.1490.g9adf4224da0
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v4 3/9] send-email docs: de-duplicate configuration sections
2022-09-07 8:26 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
2022-09-07 8:26 ` [PATCH v4 1/9] docs: add and use include template for config/* includes Ævar Arnfjörð Bjarmason
2022-09-07 8:26 ` [PATCH v4 2/9] grep docs: de-duplicate configuration sections Ævar Arnfjörð Bjarmason
@ 2022-09-07 8:26 ` Ævar Arnfjörð Bjarmason
2022-09-07 8:27 ` [PATCH v4 4/9] apply " Ævar Arnfjörð Bjarmason
` (6 subsequent siblings)
9 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-07 8:26 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
De-duplicate the discussion of "send-email" configuration, such that
the "git-config(1)" manual page becomes the source of truth, and
"git-send-email(1)" includes the relevant part.
Most commands that suffered from such duplication had diverging text
discussing the same variables, but in this case some config was also
only discussed in one or the other.
This is mostly a move-only change, the exception is a minor rewording
of changing wording like "see above" to "see linkgit:git-config[1]",
as well as a clarification about the big section of command-line
option tweaking config being discussed in git-send-email(1)'s main
docs.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/config/sendemail.txt | 40 +++++++++++++++++++++++++++---
Documentation/git-send-email.txt | 36 ++-------------------------
2 files changed, 39 insertions(+), 37 deletions(-)
diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt
index 50baa5d6bfb..51da7088a84 100644
--- a/Documentation/config/sendemail.txt
+++ b/Documentation/config/sendemail.txt
@@ -18,17 +18,49 @@ sendemail.<identity>.*::
identity is selected, through either the command-line or
`sendemail.identity`.
+sendemail.multiEdit::
+ If true (default), a single editor instance will be spawned to edit
+ files you have to edit (patches when `--annotate` is used, and the
+ summary when `--compose` is used). If false, files will be edited one
+ after the other, spawning a new editor each time.
+
+sendemail.confirm::
+ Sets the default for whether to confirm before sending. Must be
+ one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`
+ in the linkgit:git-send-email[1] documentation for the meaning of these
+ values.
+
sendemail.aliasesFile::
+ To avoid typing long email addresses, point this to one or more
+ email aliases files. You must also supply `sendemail.aliasFileType`.
+
sendemail.aliasFileType::
+ Format of the file(s) specified in sendemail.aliasesFile. Must be
+ one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.
++
+What an alias file in each format looks like can be found in
+the documentation of the email program of the same name. The
+differences and limitations from the standard formats are
+described below:
++
+--
+sendmail;;
+* Quoted aliases and quoted addresses are not supported: lines that
+ contain a `"` symbol are ignored.
+* Redirection to a file (`/path/name`) or pipe (`|command`) is not
+ supported.
+* File inclusion (`:include: /path/name`) is not supported.
+* Warnings are printed on the standard error output for any
+ explicitly unsupported constructs, and any other lines that are not
+ recognized by the parser.
+--
sendemail.annotate::
sendemail.bcc::
sendemail.cc::
sendemail.ccCmd::
sendemail.chainReplyTo::
-sendemail.confirm::
sendemail.envelopeSender::
sendemail.from::
-sendemail.multiEdit::
sendemail.signedoffbycc::
sendemail.smtpPass::
sendemail.suppresscc::
@@ -44,7 +76,9 @@ sendemail.thread::
sendemail.transferEncoding::
sendemail.validate::
sendemail.xmailer::
- See linkgit:git-send-email[1] for description.
+ These configuration variables all provide a default for
+ linkgit:git-send-email[1] command-line options. See its
+ documentation for details.
sendemail.signedoffcc (deprecated)::
Deprecated alias for `sendemail.signedoffbycc`.
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 41cd8cb4247..3290043053a 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -456,41 +456,9 @@ Information
CONFIGURATION
-------------
-sendemail.aliasesFile::
- To avoid typing long email addresses, point this to one or more
- email aliases files. You must also supply `sendemail.aliasFileType`.
+include::includes/cmd-config-section-all.txt[]
-sendemail.aliasFileType::
- Format of the file(s) specified in sendemail.aliasesFile. Must be
- one of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.
-+
-What an alias file in each format looks like can be found in
-the documentation of the email program of the same name. The
-differences and limitations from the standard formats are
-described below:
-+
---
-sendmail;;
-* Quoted aliases and quoted addresses are not supported: lines that
- contain a `"` symbol are ignored.
-* Redirection to a file (`/path/name`) or pipe (`|command`) is not
- supported.
-* File inclusion (`:include: /path/name`) is not supported.
-* Warnings are printed on the standard error output for any
- explicitly unsupported constructs, and any other lines that are not
- recognized by the parser.
---
-
-sendemail.multiEdit::
- If true (default), a single editor instance will be spawned to edit
- files you have to edit (patches when `--annotate` is used, and the
- summary when `--compose` is used). If false, files will be edited one
- after the other, spawning a new editor each time.
-
-sendemail.confirm::
- Sets the default for whether to confirm before sending. Must be
- one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`
- in the previous section for the meaning of these values.
+include::config/sendemail.txt[]
EXAMPLES
--------
--
2.37.3.1490.g9adf4224da0
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v4 4/9] apply docs: de-duplicate configuration sections
2022-09-07 8:26 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (2 preceding siblings ...)
2022-09-07 8:26 ` [PATCH v4 3/9] send-email " Ævar Arnfjörð Bjarmason
@ 2022-09-07 8:27 ` Ævar Arnfjörð Bjarmason
2022-09-07 8:27 ` [PATCH v4 5/9] notes docs: de-duplicate and combine " Ævar Arnfjörð Bjarmason
` (5 subsequent siblings)
9 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-07 8:27 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
The wording is not identical to Documentation/config/apply.txt, but
that version is better.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-apply.txt | 10 +++-------
1 file changed, 3 insertions(+), 7 deletions(-)
diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt
index b6d77f42068..1d478cbe9b5 100644
--- a/Documentation/git-apply.txt
+++ b/Documentation/git-apply.txt
@@ -263,13 +263,9 @@ has no effect when `--index` or `--cached` is in use.
CONFIGURATION
-------------
-apply.ignoreWhitespace::
- Set to 'change' if you want changes in whitespace to be ignored by default.
- Set to one of: no, none, never, false if you want changes in
- whitespace to be significant.
-apply.whitespace::
- When no `--whitespace` flag is given from the command
- line, this configuration item is used as the default.
+include::includes/cmd-config-section-all.txt[]
+
+include::config/apply.txt[]
SUBMODULES
----------
--
2.37.3.1490.g9adf4224da0
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v4 5/9] notes docs: de-duplicate and combine configuration sections
2022-09-07 8:26 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (3 preceding siblings ...)
2022-09-07 8:27 ` [PATCH v4 4/9] apply " Ævar Arnfjörð Bjarmason
@ 2022-09-07 8:27 ` Ævar Arnfjörð Bjarmason
2022-09-07 8:27 ` [PATCH v4 6/9] difftool docs: de-duplicate " Ævar Arnfjörð Bjarmason
` (4 subsequent siblings)
9 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-07 8:27 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
Combine the various "notes" configuration sections spread across
Documentation/config/notes.txt and Documentation/git-notes.txt to live
in the former, and to be included in the latter.
We'll now forward link from "git notes" to the "CONFIGURATION" section
below, rather than to "git-config(1)" when discussing configuration
variables that are (also) discussed in that section.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/config/notes.txt | 43 +++++++++++++++-----------
Documentation/git-log.txt | 16 ++--------
Documentation/git-notes.txt | 55 +++-------------------------------
3 files changed, 33 insertions(+), 81 deletions(-)
diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt
index aeef56d49ae..c7c4811734b 100644
--- a/Documentation/config/notes.txt
+++ b/Documentation/config/notes.txt
@@ -3,6 +3,9 @@ notes.mergeStrategy::
conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or
`cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES"
section of linkgit:git-notes[1] for more information on each strategy.
++
+This setting can be overridden by passing the `--strategy` option to
+linkgit:git-notes[1].
notes.<name>.mergeStrategy::
Which merge strategy to choose when doing a notes merge into
@@ -11,28 +14,35 @@ notes.<name>.mergeStrategy::
linkgit:git-notes[1] for more information on the available strategies.
notes.displayRef::
- The (fully qualified) refname from which to show notes when
- showing commit messages. The value of this variable can be set
- to a glob, in which case notes from all matching refs will be
- shown. You may also specify this configuration variable
- several times. A warning will be issued for refs that do not
- exist, but a glob that does not match any refs is silently
- ignored.
+ Which ref (or refs, if a glob or specified more than once), in
+ addition to the default set by `core.notesRef` or
+ `GIT_NOTES_REF`, to read notes from when showing commit
+ messages with the 'git log' family of commands.
+
This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`
environment variable, which must be a colon separated list of refs or
globs.
+
+A warning will be issued for refs that do not exist,
+but a glob that does not match any refs is silently ignored.
++
+This setting can be disabled by the `--no-notes` option to the 'git
+log' family of commands, or by the `--notes=<ref>` option accepted by
+those commands.
++
The effective value of "core.notesRef" (possibly overridden by
GIT_NOTES_REF) is also implicitly added to the list of refs to be
displayed.
notes.rewrite.<command>::
When rewriting commits with <command> (currently `amend` or
- `rebase`) and this variable is set to `true`, Git
- automatically copies your notes from the original to the
- rewritten commit. Defaults to `true`, but see
- "notes.rewriteRef" below.
+ `rebase`), if this variable is `false`, git will not copy
+ notes from the original to the rewritten commit. Defaults to
+ `true`. See also "`notes.rewriteRef`" below.
++
+This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
+environment variable, which must be a colon separated list of refs or
+globs.
notes.rewriteMode::
When copying notes during a rewrite (see the
@@ -46,14 +56,13 @@ environment variable.
notes.rewriteRef::
When copying notes during a rewrite, specifies the (fully
- qualified) ref whose notes should be copied. The ref may be a
- glob, in which case notes in all matching refs will be copied.
- You may also specify this configuration several times.
+ qualified) ref whose notes should be copied. May be a glob,
+ in which case notes in all matching refs will be copied. You
+ may also specify this configuration several times.
+
Does not have a default value; you must configure this variable to
enable note rewriting. Set it to `refs/notes/commits` to enable
rewriting for the default commit notes.
+
-This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
-environment variable, which must be a colon separated list of refs or
-globs.
+Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.
+See `notes.rewrite.<command>` above for a further description of its format.
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index b1285aee3c2..410095e9a4f 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -237,19 +237,9 @@ log.showSignature::
mailmap.*::
See linkgit:git-shortlog[1].
-notes.displayRef::
- Which refs, in addition to the default set by `core.notesRef`
- or `GIT_NOTES_REF`, to read notes from when showing commit
- messages with the `log` family of commands. See
- linkgit:git-notes[1].
-+
-May be an unabbreviated ref name or a glob and may be specified
-multiple times. A warning will be issued for refs that do not exist,
-but a glob that does not match any refs is silently ignored.
-+
-This setting can be disabled by the `--no-notes` option,
-overridden by the `GIT_NOTES_DISPLAY_REF` environment variable,
-and overridden by the `--notes=<ref>` option.
+include::includes/cmd-config-section-rest.txt[]
+
+include::config/notes.txt[]
GIT
---
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 0a4200674c4..efbc10f0f59 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -44,7 +44,7 @@ using the `--notes` option. Such notes are added as a patch commentary
after a three dash separator line.
To change which notes are shown by 'git log', see the
-"notes.displayRef" configuration in linkgit:git-log[1].
+"notes.displayRef" discussion in <<CONFIGURATION>>.
See the "notes.rewrite.<command>" configuration for a way to carry
notes across commands that rewrite commits.
@@ -307,6 +307,7 @@ with 'git log', so if you use such notes, you'll probably need to write
some special-purpose tools to do something useful with them.
+[[CONFIGURATION]]
CONFIGURATION
-------------
@@ -316,57 +317,9 @@ core.notesRef::
This setting can be overridden through the environment and
command line.
-notes.mergeStrategy::
- Which merge strategy to choose by default when resolving notes
- conflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or
- `cat_sort_uniq`. Defaults to `manual`. See "NOTES MERGE STRATEGIES"
- section above for more information on each strategy.
-+
-This setting can be overridden by passing the `--strategy` option.
-
-notes.<name>.mergeStrategy::
- Which merge strategy to choose when doing a notes merge into
- refs/notes/<name>. This overrides the more general
- "notes.mergeStrategy". See the "NOTES MERGE STRATEGIES" section above
- for more information on each available strategy.
-
-notes.displayRef::
- Which ref (or refs, if a glob or specified more than once), in
- addition to the default set by `core.notesRef` or
- `GIT_NOTES_REF`, to read notes from when showing commit
- messages with the 'git log' family of commands.
- This setting can be overridden on the command line or by the
- `GIT_NOTES_DISPLAY_REF` environment variable.
- See linkgit:git-log[1].
-
-notes.rewrite.<command>::
- When rewriting commits with <command> (currently `amend` or
- `rebase`), if this variable is `false`, git will not copy
- notes from the original to the rewritten commit. Defaults to
- `true`. See also "`notes.rewriteRef`" below.
-+
-This setting can be overridden by the `GIT_NOTES_REWRITE_REF`
-environment variable.
+include::includes/cmd-config-section-rest.txt[]
-notes.rewriteMode::
- When copying notes during a rewrite, what to do if the target
- commit already has a note. Must be one of `overwrite`,
- `concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to
- `concatenate`.
-+
-This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
-environment variable.
-
-notes.rewriteRef::
- When copying notes during a rewrite, specifies the (fully
- qualified) ref whose notes should be copied. May be a glob,
- in which case notes in all matching refs will be copied. You
- may also specify this configuration several times.
-+
-Does not have a default value; you must configure this variable to
-enable note rewriting.
-+
-Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.
+include::config/notes.txt[]
ENVIRONMENT
--
2.37.3.1490.g9adf4224da0
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v4 6/9] difftool docs: de-duplicate configuration sections
2022-09-07 8:26 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (4 preceding siblings ...)
2022-09-07 8:27 ` [PATCH v4 5/9] notes docs: de-duplicate and combine " Ævar Arnfjörð Bjarmason
@ 2022-09-07 8:27 ` Ævar Arnfjörð Bjarmason
2022-09-07 8:27 ` [PATCH v4 7/9] log " Ævar Arnfjörð Bjarmason
` (3 subsequent siblings)
9 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-07 8:27 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
Include the "config/difftool.txt" file in "git-difftool.txt", and move
the relevant part of git-difftool(1) configuration from
"config/diff.txt" to config/difftool.txt".
Doing this is slightly odd, as we usually discuss configuration in
alphabetical order, but by doing it we're able to include the full set
of configuration used by git-difftool(1) (and only that configuration)
in its own documentation.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/config/diff.txt | 15 ---------------
Documentation/config/difftool.txt | 28 +++++++++++++++++++++++++---
Documentation/git-difftool.txt | 27 ++++-----------------------
3 files changed, 29 insertions(+), 41 deletions(-)
diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt
index 32f84838ac1..35a7bf86d77 100644
--- a/Documentation/config/diff.txt
+++ b/Documentation/config/diff.txt
@@ -178,21 +178,6 @@ diff.<driver>.cachetextconv::
Set this option to true to make the diff driver cache the text
conversion outputs. See linkgit:gitattributes[5] for details.
-diff.tool::
- Controls which diff tool is used by linkgit:git-difftool[1].
- This variable overrides the value configured in `merge.tool`.
- The list below shows the valid built-in values.
- Any other value is treated as a custom diff tool and requires
- that a corresponding difftool.<tool>.cmd variable is defined.
-
-diff.guitool::
- Controls which diff tool is used by linkgit:git-difftool[1] when
- the -g/--gui flag is specified. This variable overrides the value
- configured in `merge.guitool`. The list below shows the valid
- built-in values. Any other value is treated as a custom diff tool
- and requires that a corresponding difftool.<guitool>.cmd variable
- is defined.
-
include::../mergetools-diff.txt[]
diff.indentHeuristic::
diff --git a/Documentation/config/difftool.txt b/Documentation/config/difftool.txt
index 67625944804..a3f82112102 100644
--- a/Documentation/config/difftool.txt
+++ b/Documentation/config/difftool.txt
@@ -1,6 +1,17 @@
-difftool.<tool>.path::
- Override the path for the given tool. This is useful in case
- your tool is not in the PATH.
+diff.tool::
+ Controls which diff tool is used by linkgit:git-difftool[1].
+ This variable overrides the value configured in `merge.tool`.
+ The list below shows the valid built-in values.
+ Any other value is treated as a custom diff tool and requires
+ that a corresponding difftool.<tool>.cmd variable is defined.
+
+diff.guitool::
+ Controls which diff tool is used by linkgit:git-difftool[1] when
+ the -g/--gui flag is specified. This variable overrides the value
+ configured in `merge.guitool`. The list below shows the valid
+ built-in values. Any other value is treated as a custom diff tool
+ and requires that a corresponding difftool.<guitool>.cmd variable
+ is defined.
difftool.<tool>.cmd::
Specify the command to invoke the specified diff tool.
@@ -9,6 +20,17 @@ difftool.<tool>.cmd::
file containing the contents of the diff pre-image and 'REMOTE'
is set to the name of the temporary file containing the contents
of the diff post-image.
++
+See the `--tool=<tool>` option in linkgit:git-difftool[1] for more details.
+
+difftool.<tool>.path::
+ Override the path for the given tool. This is useful in case
+ your tool is not in the PATH.
+
+difftool.trustExitCode::
+ Exit difftool if the invoked diff tool returns a non-zero exit status.
++
+See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details.
difftool.prompt::
Prompt before each invocation of the diff tool.
diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt
index 143b0c49d73..9d14c3c9f09 100644
--- a/Documentation/git-difftool.txt
+++ b/Documentation/git-difftool.txt
@@ -113,33 +113,14 @@ instead. `--no-symlinks` is the default on Windows.
See linkgit:git-diff[1] for the full list of supported options.
-CONFIG VARIABLES
-----------------
+CONFIGURATION
+-------------
'git difftool' falls back to 'git mergetool' config variables when the
difftool equivalents have not been defined.
-diff.tool::
- The default diff tool to use.
+include::includes/cmd-config-section-rest.txt[]
-diff.guitool::
- The default diff tool to use when `--gui` is specified.
-
-difftool.<tool>.path::
- Override the path for the given tool. This is useful in case
- your tool is not in the PATH.
-
-difftool.<tool>.cmd::
- Specify the command to invoke the specified diff tool.
-+
-See the `--tool=<tool>` option above for more details.
-
-difftool.prompt::
- Prompt before each invocation of the diff tool.
-
-difftool.trustExitCode::
- Exit difftool if the invoked diff tool returns a non-zero exit status.
-+
-See the `--trust-exit-code` option above for more details.
+include::config/difftool.txt[]
SEE ALSO
--------
--
2.37.3.1490.g9adf4224da0
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v4 7/9] log docs: de-duplicate configuration sections
2022-09-07 8:26 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (5 preceding siblings ...)
2022-09-07 8:27 ` [PATCH v4 6/9] difftool docs: de-duplicate " Ævar Arnfjörð Bjarmason
@ 2022-09-07 8:27 ` Ævar Arnfjörð Bjarmason
2022-09-07 8:27 ` [PATCH v4 8/9] docs: add CONFIGURATION sections that map to a built-in Ævar Arnfjörð Bjarmason
` (2 subsequent siblings)
9 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-07 8:27 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/config/log.txt | 4 ++++
Documentation/git-log.txt | 30 ++----------------------------
2 files changed, 6 insertions(+), 28 deletions(-)
diff --git a/Documentation/config/log.txt b/Documentation/config/log.txt
index 5250ba45fb4..bc63bc3939c 100644
--- a/Documentation/config/log.txt
+++ b/Documentation/config/log.txt
@@ -7,6 +7,10 @@ log.date::
Set the default date-time mode for the 'log' command.
Setting a value for log.date is similar to using 'git log''s
`--date` option. See linkgit:git-log[1] for details.
++
+If the format is set to "auto:foo" and the pager is in use, format
+"foo" will be the used for the date format. Otherwise "default" will
+be used.
log.decorate::
Print out the ref names of any commits that are shown by the log
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 410095e9a4f..2a66cf88807 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -209,36 +209,10 @@ i18n.logOutputEncoding::
Defaults to the value of `i18n.commitEncoding` if set, and UTF-8
otherwise.
-log.date::
- Default format for human-readable dates. (Compare the
- `--date` option.) Defaults to "default", which means to write
- dates like `Sat May 8 19:35:34 2010 -0500`.
-+
-If the format is set to "auto:foo" and the pager is in use, format
-"foo" will be the used for the date format. Otherwise "default" will
-be used.
-
-log.follow::
- If `true`, `git log` will act as if the `--follow` option was used when
- a single <path> is given. This has the same limitations as `--follow`,
- i.e. it cannot be used to follow multiple files and does not work well
- on non-linear history.
-
-log.showRoot::
- If `false`, `git log` and related commands will not treat the
- initial commit as a big creation event. Any root commits in
- `git log -p` output would be shown without a diff attached.
- The default is `true`.
-
-log.showSignature::
- If `true`, `git log` and related commands will act as if the
- `--show-signature` option was passed to them.
-
-mailmap.*::
- See linkgit:git-shortlog[1].
-
include::includes/cmd-config-section-rest.txt[]
+include::config/log.txt[]
+
include::config/notes.txt[]
GIT
--
2.37.3.1490.g9adf4224da0
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v4 8/9] docs: add CONFIGURATION sections that map to a built-in
2022-09-07 8:26 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (6 preceding siblings ...)
2022-09-07 8:27 ` [PATCH v4 7/9] log " Ævar Arnfjörð Bjarmason
@ 2022-09-07 8:27 ` Ævar Arnfjörð Bjarmason
2022-09-07 8:27 ` [PATCH v4 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins Ævar Arnfjörð Bjarmason
2022-09-07 11:51 ` [PATCH v4 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Matheus Tavares
9 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-07 8:27 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
Add a CONFIGURATION section to the documentation of various built-ins,
for those cases where the relevant config/NAME.txt describes
configuration that is only used by the relevant built-in documented in
git-NAME.txt. Subsequent commits will handle more complex cases.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-add.txt | 7 +++++++
Documentation/git-am.txt | 7 +++++++
Documentation/git-clean.txt | 7 +++++++
Documentation/git-clone.txt | 7 +++++++
Documentation/git-commit-graph.txt | 7 +++++++
Documentation/git-commit.txt | 4 ++++
Documentation/git-fast-import.txt | 7 +++++++
Documentation/git-mailinfo.txt | 7 +++++++
Documentation/git-maintenance.txt | 7 +++++++
Documentation/git-push.txt | 7 +++++++
Documentation/git-revert.txt | 7 +++++++
Documentation/git-show-branch.txt | 7 +++++++
Documentation/git-stash.txt | 7 +++++++
13 files changed, 88 insertions(+)
diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
index 9b37f356542..a030d33c6e7 100644
--- a/Documentation/git-add.txt
+++ b/Documentation/git-add.txt
@@ -433,6 +433,13 @@ they will make the patch impossible to apply:
* deleting context or removal lines
* modifying the contents of context or removal lines
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/add.txt[]
+
SEE ALSO
--------
linkgit:git-status[1]
diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt
index 320da6c4f76..326276e51ce 100644
--- a/Documentation/git-am.txt
+++ b/Documentation/git-am.txt
@@ -258,6 +258,13 @@ This command can run `applypatch-msg`, `pre-applypatch`,
and `post-applypatch` hooks. See linkgit:githooks[5] for more
information.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/am.txt[]
+
SEE ALSO
--------
linkgit:git-apply[1].
diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt
index a7f309dff5a..91742633fa8 100644
--- a/Documentation/git-clean.txt
+++ b/Documentation/git-clean.txt
@@ -133,6 +133,13 @@ help::
Show brief usage of interactive git-clean.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/clean.txt[]
+
SEE ALSO
--------
linkgit:gitignore[5]
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index d032d971dd7..1c3d7017646 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -370,6 +370,13 @@ $ cd my-linux
$ git clone --bare -l /home/proj/.git /pub/scm/proj.git
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/clone.txt[]
+
GIT
---
diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt
index 047decdb65b..36fe56c2c71 100644
--- a/Documentation/git-commit-graph.txt
+++ b/Documentation/git-commit-graph.txt
@@ -142,6 +142,13 @@ $ git show-ref -s | git commit-graph write --stdin-commits
$ git rev-parse HEAD | git commit-graph write --stdin-commits --append
------------------------------------------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/commitgraph.txt[]
+
FILE FORMAT
-----------
diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt
index 6c60bf98f9f..225c6c9f2e5 100644
--- a/Documentation/git-commit.txt
+++ b/Documentation/git-commit.txt
@@ -557,6 +557,10 @@ The editor used to edit the commit log message will be chosen from the
`VISUAL` environment variable, or the `EDITOR` environment variable (in that
order). See linkgit:git-var[1] for details.
+include::includes/cmd-config-section-rest.txt[]
+
+include::config/commit.txt[]
+
HOOKS
-----
This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`,
diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt
index 39cfa05b28b..8b5dd6add00 100644
--- a/Documentation/git-fast-import.txt
+++ b/Documentation/git-fast-import.txt
@@ -1564,6 +1564,13 @@ operator can use this facility to peek at the objects and refs from an
import in progress, at the cost of some added running time and worse
compression.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/fastimport.txt[]
+
SEE ALSO
--------
linkgit:git-fast-export[1]
diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt
index 3fcfd965fde..28060283c70 100644
--- a/Documentation/git-mailinfo.txt
+++ b/Documentation/git-mailinfo.txt
@@ -115,6 +115,13 @@ If no such configuration option has been set, `warn` will be used.
<patch>::
The patch extracted from e-mail.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/mailinfo.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt
index e56bad28c65..9c630efe19c 100644
--- a/Documentation/git-maintenance.txt
+++ b/Documentation/git-maintenance.txt
@@ -397,6 +397,13 @@ If you want to customize the background tasks, please rename the tasks
so future calls to `git maintenance (start|stop)` do not overwrite your
custom tasks.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/maintenance.txt[]
+
GIT
---
diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt
index 2f25aa3a291..def7657ef9c 100644
--- a/Documentation/git-push.txt
+++ b/Documentation/git-push.txt
@@ -692,6 +692,13 @@ a `git gc` command on the origin repository.
include::transfer-data-leaks.txt[]
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/push.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt
index 0105a54c1a5..5016755efb6 100644
--- a/Documentation/git-revert.txt
+++ b/Documentation/git-revert.txt
@@ -142,6 +142,13 @@ EXAMPLES
changes. The revert only modifies the working tree and the
index.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/revert.txt[]
+
SEE ALSO
--------
linkgit:git-cherry-pick[1]
diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt
index 5cc2fcefbab..e5ec6b467f9 100644
--- a/Documentation/git-show-branch.txt
+++ b/Documentation/git-show-branch.txt
@@ -199,6 +199,13 @@ shows 10 reflog entries going back from the tip as of 1 hour ago.
Without `--list`, the output also shows how these tips are
topologically related with each other.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/showbranch.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt
index 6e15f475257..c5d70918283 100644
--- a/Documentation/git-stash.txt
+++ b/Documentation/git-stash.txt
@@ -382,6 +382,13 @@ grep commit | cut -d\ -f3 |
xargs git log --merges --no-walk --grep=WIP
----------------------------------------------------------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/stash.txt[]
+
SEE ALSO
--------
--
2.37.3.1490.g9adf4224da0
^ permalink raw reply related [flat|nested] 56+ messages in thread
* [PATCH v4 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins
2022-09-07 8:26 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (7 preceding siblings ...)
2022-09-07 8:27 ` [PATCH v4 8/9] docs: add CONFIGURATION sections that map to a built-in Ævar Arnfjörð Bjarmason
@ 2022-09-07 8:27 ` Ævar Arnfjörð Bjarmason
2022-09-07 11:51 ` [PATCH v4 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Matheus Tavares
9 siblings, 0 replies; 56+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2022-09-07 8:27 UTC (permalink / raw)
To: git
Cc: Junio C Hamano, Matheus Tavares, Ævar Arnfjörð Bjarmason
Add a CONFIGURATION section to the documentation of various built-ins,
for those cases where the relevant config/NAME.txt doesn't map only to
one git-NAME.txt. In particular:
* config/blame.txt: used by git-{blame,annotate}.txt. Since the
git-annotate(1) documentation refers to git-blame(1) don't add a
"CONFIGURATION" section to git-annotate(1), only to git-blame(1).
* config/checkout.txt: maps to both git-checkout.txt and
git-switch.txt (but nothing else).
* config/init.txt: should be included in git-init(1) and
git-clone(1).
* config/column.txt: We should ideally mention the relevant subset of
this in git-{branch,clean,status,tag}.txt, but let's punt on it for
now. We will when we eventually split these sort of files into
e.g. config/column.txt and
config/column/{branch,clean,status,tag}.txt, with the former
including the latter set.
Things that are being left out, and why:
* config/{remote,remotes,credential}.txt: Configuration that affects
how we talk to remote repositories is harder to untangle. We'll need
to include some of this in git-{fetch,remote,push,ls-remote}.txt
etc., but some of those only use a small subset of these
options. Let's leave this for now.
Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
---
Documentation/git-blame.txt | 6 ++++++
Documentation/git-branch.txt | 4 ++++
Documentation/git-checkout.txt | 7 +++++++
Documentation/git-clone.txt | 2 ++
Documentation/git-column.txt | 7 +++++++
Documentation/git-diff.txt | 7 +++++++
Documentation/git-fetch.txt | 7 +++++++
Documentation/git-init.txt | 7 +++++++
Documentation/git-switch.txt | 7 +++++++
9 files changed, 54 insertions(+)
diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt
index d7a46cc6744..4400a17330b 100644
--- a/Documentation/git-blame.txt
+++ b/Documentation/git-blame.txt
@@ -241,6 +241,12 @@ MAPPING AUTHORS
See linkgit:gitmailmap[5].
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/blame.txt[]
SEE ALSO
--------
diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt
index ae82378349d..12c5f84e3be 100644
--- a/Documentation/git-branch.txt
+++ b/Documentation/git-branch.txt
@@ -336,6 +336,10 @@ CONFIGURATION
`--list` is used or implied. The default is to use a pager.
See linkgit:git-config[1].
+include::includes/cmd-config-section-rest.txt[]
+
+include::config/branch.txt[]
+
EXAMPLES
--------
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index 9f37e22e130..4cb9d555b4b 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -600,6 +600,13 @@ $ edit frotz
$ git add frotz
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/checkout.txt[]
+
SEE ALSO
--------
linkgit:git-switch[1],
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 1c3d7017646..d6434d262d6 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -375,6 +375,8 @@ CONFIGURATION
include::includes/cmd-config-section-all.txt[]
+include::config/init.txt[]
+
include::config/clone.txt[]
diff --git a/Documentation/git-column.txt b/Documentation/git-column.txt
index 6cea9ab4638..18431647a2d 100644
--- a/Documentation/git-column.txt
+++ b/Documentation/git-column.txt
@@ -74,6 +74,13 @@ v2.4.3 v2.4.4 v2.4.5 v2.4.6 v2.4.7
v2.4.8 v2.4.9
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/column.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 6236c75c9b8..85ae6d6d08a 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -213,6 +213,13 @@ $ git diff -R <2>
rewrites (very expensive).
<2> Output diff in reverse.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/diff.txt[]
+
SEE ALSO
--------
diff(1),
diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index e9d364669af..63d9569e164 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt
@@ -285,6 +285,13 @@ linkgit:git-gc[1]).
include::transfer-data-leaks.txt[]
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/fetch.txt[]
+
BUGS
----
Using --recurse-submodules can only fetch new commits in submodules that are
diff --git a/Documentation/git-init.txt b/Documentation/git-init.txt
index ad921fe782e..160dea1372c 100644
--- a/Documentation/git-init.txt
+++ b/Documentation/git-init.txt
@@ -169,6 +169,13 @@ $ git commit <3>
<2> Add all existing files to the index.
<3> Record the pristine state as the first commit in the history.
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/init.txt[]
+
GIT
---
Part of the linkgit:git[1] suite
diff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt
index bbcbdceb459..c60fc9c138b 100644
--- a/Documentation/git-switch.txt
+++ b/Documentation/git-switch.txt
@@ -265,6 +265,13 @@ always create a new name for it (without switching away):
$ git switch -c good-surprises
------------
+CONFIGURATION
+-------------
+
+include::includes/cmd-config-section-all.txt[]
+
+include::config/checkout.txt[]
+
SEE ALSO
--------
linkgit:git-checkout[1],
--
2.37.3.1490.g9adf4224da0
^ permalink raw reply related [flat|nested] 56+ messages in thread
* Re: [PATCH v4 0/9] docs: de-duplicate sections, add more CONFIGURATION sections
2022-09-07 8:26 ` [PATCH v4 " Ævar Arnfjörð Bjarmason
` (8 preceding siblings ...)
2022-09-07 8:27 ` [PATCH v4 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins Ævar Arnfjörð Bjarmason
@ 2022-09-07 11:51 ` Matheus Tavares
2022-09-07 16:45 ` Junio C Hamano
9 siblings, 1 reply; 56+ messages in thread
From: Matheus Tavares @ 2022-09-07 11:51 UTC (permalink / raw)
To: Ævar Arnfjörð Bjarmason; +Cc: git, Junio C Hamano
On Wed, Sep 7, 2022 at 5:27 AM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:
>
> This series:
>
> * De-duplicates and combines configuration discussion that was split
> or spread across Documentation/config/*.txt and
> Documentation/git-*.txt, moving it to Documentation/config/*.txt.
>
> * Includes that relevant Documentation/config/*.txt in the
> Documentation/git-*.txt files.
>
> * Introduces and uses included prose for those "CONFIGURATION"
> sections in various Documentation/git-*.txt files, informing the
> reader that what they see there is included from "git-config(1)".
>
> This v4 addresses the feedback from Matheus Tavares on v3 (thanks for
> the review!): A hunk belonged in 9/9, not 8/9 (init's config is used
> by e.g. "clone" too). The end-state at the end of this series is
> exactly the same.
This version LGTM. Thanks!
^ permalink raw reply [flat|nested] 56+ messages in thread
* Re: [PATCH v4 0/9] docs: de-duplicate sections, add more CONFIGURATION sections
2022-09-07 11:51 ` [PATCH v4 0/9] docs: de-duplicate sections, add more CONFIGURATION sections Matheus Tavares
@ 2022-09-07 16:45 ` Junio C Hamano
0 siblings, 0 replies; 56+ messages in thread
From: Junio C Hamano @ 2022-09-07 16:45 UTC (permalink / raw)
To: Matheus Tavares; +Cc: Ævar Arnfjörð Bjarmason, git
Matheus Tavares <matheus.bernardino@usp.br> writes:
> On Wed, Sep 7, 2022 at 5:27 AM Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:
>>
>> This series:
>>
>> * De-duplicates and combines configuration discussion that was split
>> or spread across Documentation/config/*.txt and
>> Documentation/git-*.txt, moving it to Documentation/config/*.txt.
>>
>> * Includes that relevant Documentation/config/*.txt in the
>> Documentation/git-*.txt files.
>>
>> * Introduces and uses included prose for those "CONFIGURATION"
>> sections in various Documentation/git-*.txt files, informing the
>> reader that what they see there is included from "git-config(1)".
>>
>> This v4 addresses the feedback from Matheus Tavares on v3 (thanks for
>> the review!): A hunk belonged in 9/9, not 8/9 (init's config is used
>> by e.g. "clone" too). The end-state at the end of this series is
>> exactly the same.
>
> This version LGTM. Thanks!
Thanks, both.
^ permalink raw reply [flat|nested] 56+ messages in thread