{"thread":{"id":"58160","subject":"[PATCH 0/3] doc: unify config info on some cmds","startedAt":"2022-07-14T17:44:21Z","lastAt":"2022-09-07T16:46:02Z","messageCount":56,"participants":["Matheus Tavares","Junio C Hamano","Ævar Arnfjörð Bjarmason"],"isPatch":true,"patchVersion":1,"patchTotal":3},"messages":[{"id":"459054","messageId":"cover.1657819649.git.matheus.bernardino@usp.br","threadId":"58160","inReplyTo":null,"subject":"[PATCH 0/3] doc: unify config info on some cmds","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-07-14T17:44:01Z","receivedAt":"2022-07-14T17:44:21Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"These three patches attempt to remove duplication between some\nconfig/*.txt and git-*.txt files, to facilitate maintenance and fix any\ndivergences.\n\nThis series targets the most straightforward conversions, but there are\nalso other commands whose config documentation could possibly be unified\n(maybe #leftoverbits):\n\n- git-log.txt and config/log.txt have some duplications, but with\n different wordings, which could probably be standardized.\n\n- git-send-email.txt has some config definitions \"inlined\" with the\n descriptions about the CLI options (e.g. sendemail.xmailer). Not sure\n if it is worth unifying the configs in this case.\n\n- Some cmds like format-patch, status, and branch have some config variables\n defined at config/*, but not at git-*.txt. Maybe the latter could\n mention something like \"See the full list of available .*\n configuration variables at git-config(1).\"\n\nMatheus Tavares (3):\n doc: grep: unify configuration variables definitions\n doc: apply: unify configuration variables definitions\n doc: notes: unify configuration variables definitions\n\n Documentation/config/apply.txt | 7 +++-\n Documentation/config/grep.txt | 10 ++++--\n Documentation/config/notes.txt | 62 ++++++++++++++++------------------\n Documentation/git-apply.txt | 9 ++---\n Documentation/git-grep.txt | 37 ++++----------------\n Documentation/git-notes.txt | 54 ++---------------------------\n 6 files changed, 53 insertions(+), 126 deletions(-)\n\n-- \n2.37.0\n\n"},{"id":"459055","messageId":"439cfdf858f5b1917ae7ca3ca327bb33b42f71c7.1657819649.git.matheus.bernardino@usp.br","threadId":"58160","inReplyTo":"cover.1657819649.git.matheus.bernardino@usp.br","subject":"[PATCH 1/3] doc: grep: unify configuration variables definitions","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-07-14T17:44:02Z","receivedAt":"2022-07-14T17:44:22Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"The configuration variables for git-grep are duplicated in\n\"Documentation/git-grep.txt\" and \"Documentation/config/grep.txt\", which\ngqcan make maintenance difficult. The first also contains a definition\nthat is not present in the latter (grep.fullName), and the latter\nreceived a wording improvement that was not replicated in the former:\nsee 91028f765 (\"grep: clarify what `grep.patternType=default` means\",\n2021-12-05).\n\nTo avoid such problems, unify the information in one file and include it\nin the other.\n\nSigned-off-by: Matheus Tavares \n---\n Documentation/config/grep.txt | 10 ++++++++--\n Documentation/git-grep.txt | 37 ++++++-----------------------------\n 2 files changed, 14 insertions(+), 33 deletions(-)\n\ndiff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt\nindex 182edd813a..6996e64574 100644\n--- a/Documentation/config/grep.txt\n+++ b/Documentation/config/grep.txt\n@@ -17,8 +17,14 @@ grep.extendedRegexp::\n \tother than 'default'.\n \n grep.threads::\n-\tNumber of grep worker threads to use.\n-\tSee `grep.threads` in linkgit:git-grep[1] for more information.\n+\tNumber of grep worker threads to use. See `--threads`\n+ifndef::git-grep[]\n+\tin linkgit:git-grep[1]\n+endif::git-grep[]\n+\tfor more information.\n+\n+grep.fullName::\n+\tIf set to true, enable `--full-name` option by default.\n \n grep.fallbackToNoIndex::\n \tIf set to true, fall back to git grep --no-index if git grep\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 3d393fbac1..65a3ca1101 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -37,7 +37,6 @@ registered in the index file, or blobs in given tree objects. Patterns\n are lists of one or more search expressions separated by newline\n characters. An empty string as search expression matches all lines.\n \n-\n OPTIONS\n -------\n --cached::\n@@ -239,8 +238,10 @@ providing this option will cause it to die.\n \tcustom hunk-header' in linkgit:gitattributes[5]).\n \n --threads ::\n-\tNumber of grep worker threads to use.\n-\tSee `grep.threads` in 'CONFIGURATION' for more information.\n+\tNumber of grep worker threads to use. If not provided (or set to\n+\t0), Git will use as many worker threads as the number of logical\n+\tcores available. The default value can also be set with the\n+\t`grep.threads` configuration.\n \n -f ::\n \tRead patterns from , one per line.\n@@ -334,34 +335,8 @@ performance in this case, it might be desirable to use `--threads=1`.\n CONFIGURATION\n -------------\n \n-grep.lineNumber::\n-\tIf set to true, enable `-n` option by default.\n-\n-grep.column::\n-\tIf set to true, enable the `--column` option by default.\n-\n-grep.patternType::\n-\tSet the default matching behavior. Using a value of 'basic', 'extended',\n-\t'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,\n-\t`--fixed-strings`, or `--perl-regexp` option accordingly, while the\n-\tvalue 'default' will return to the default matching behavior.\n-\n-grep.extendedRegexp::\n-\tIf set to true, enable `--extended-regexp` option by default. This\n-\toption is ignored when the `grep.patternType` option is set to a value\n-\tother than 'default'.\n-\n-grep.threads::\n-\tNumber of grep worker threads to use. If unset (or set to 0), Git will\n-\tuse as many threads as the number of logical cores available.\n-\n-grep.fullName::\n-\tIf set to true, enable `--full-name` option by default.\n-\n-grep.fallbackToNoIndex::\n-\tIf set to true, fall back to git grep --no-index if git grep\n-\tis executed outside of a git repository. Defaults to false.\n-\n+:git-grep: 1\n+include::config/grep.txt[]\n \n GIT\n ---\n-- \n2.37.0\n\n"},{"id":"459056","messageId":"a25a6d89647638ffd682fb24ef0b5b6c9bed0941.1657819649.git.matheus.bernardino@usp.br","threadId":"58160","inReplyTo":"cover.1657819649.git.matheus.bernardino@usp.br","subject":"[PATCH 2/3] doc: apply: unify configuration variables definitions","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-07-14T17:44:03Z","receivedAt":"2022-07-14T17:44:23Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"Note that apply.ignoreWhitespace and apply.whitespace are defined with\nslightly different wordings at git-apply.txt and config/apply.txt.\nNevertheless, there is no loss of information from using one or the\nother, so I kept the latter for the single unified definition.\n\nSigned-off-by: Matheus Tavares \n---\n Documentation/config/apply.txt | 7 ++++++-\n Documentation/git-apply.txt | 9 ++-------\n 2 files changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/config/apply.txt b/Documentation/config/apply.txt\nindex 8fb8ef763d..7fb1ae7f8a 100644\n--- a/Documentation/config/apply.txt\n+++ b/Documentation/config/apply.txt\n@@ -4,8 +4,13 @@ apply.ignoreWhitespace::\n \toption.\n \tWhen set to one of: no, none, never, false tells 'git apply' to\n \trespect all whitespace differences.\n+ifndef::git-apply[]\n \tSee linkgit:git-apply[1].\n+endif::git-apply[]\n \n apply.whitespace::\n \tTells 'git apply' how to handle whitespaces, in the same way\n-\tas the `--whitespace` option. See linkgit:git-apply[1].\n+\tas the `--whitespace` option.\n+ifndef::git-apply[]\n+\tSee linkgit:git-apply[1].\n+endif::git-apply[]\ndiff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt\nindex b6d77f4206..7ababdaaa7 100644\n--- a/Documentation/git-apply.txt\n+++ b/Documentation/git-apply.txt\n@@ -263,13 +263,8 @@ has no effect when `--index` or `--cached` is in use.\n CONFIGURATION\n -------------\n \n-apply.ignoreWhitespace::\n-\tSet to 'change' if you want changes in whitespace to be ignored by default.\n-\tSet to one of: no, none, never, false if you want changes in\n-\twhitespace to be significant.\n-apply.whitespace::\n-\tWhen no `--whitespace` flag is given from the command\n-\tline, this configuration item is used as the default.\n+:git-apply: 1\n+include::config/apply.txt[]\n \n SUBMODULES\n ----------\n-- \n2.37.0\n\n"},{"id":"459057","messageId":"d39e826756e79ce7fe270175ad0d5ae523528af9.1657819649.git.matheus.bernardino@usp.br","threadId":"58160","inReplyTo":"cover.1657819649.git.matheus.bernardino@usp.br","subject":"[PATCH 3/3] doc: notes: unify configuration variables definitions","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-07-14T17:44:04Z","receivedAt":"2022-07-14T17:44:32Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"Unify duplicated configuration descriptions from git-notes.txt and\nconfig.txt in order to facilitate maintenance and update. There are some\ndiscrepancies between these two files: git-notes.txt received two\nupdates that were not made in config.txt: see 66c4c32\n(\"Documentation/notes: simplify treatment of default display refs\",\n2010-05-08) and c5ce183 (\"Documentation/notes: clean up description of\nrewriting configuration\", 2010-05-08 ). And there was also an update to\nconfig.txt not propagated to git-notes.txt: see 2b4aa89 (\"Documentation:\nbasic configuration of notes.rewriteRef\", 2011-09-13). Let's make sure\nto include all these three updates in the unified version.\n\nSigned-off-by: Matheus Tavares \n---\n Documentation/config/notes.txt | 62 ++++++++++++++++------------------\n Documentation/git-notes.txt | 54 ++---------------------------\n 2 files changed, 31 insertions(+), 85 deletions(-)\n\ndiff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt\nindex aeef56d49a..552b340987 100644\n--- a/Documentation/config/notes.txt\n+++ b/Documentation/config/notes.txt\n@@ -2,58 +2,54 @@ notes.mergeStrategy::\n \tWhich merge strategy to choose by default when resolving notes\n \tconflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or\n \t`cat_sort_uniq`. Defaults to `manual`. See \"NOTES MERGE STRATEGIES\"\n-\tsection of linkgit:git-notes[1] for more information on each strategy.\n+\tsection\n+ifdef::git-notes[above]\n+ifndef::git-notes[of linkgit:git-notes[1]]\n+\tfor more information on each strategy.\n \n notes..mergeStrategy::\n \tWhich merge strategy to choose when doing a notes merge into\n \trefs/notes/. This overrides the more general\n-\t\"notes.mergeStrategy\". See the \"NOTES MERGE STRATEGIES\" section in\n-\tlinkgit:git-notes[1] for more information on the available strategies.\n+\t\"notes.mergeStrategy\". See the \"NOTES MERGE STRATEGIES\" section\n+ifdef::git-notes[above]\n+ifndef::git-notes[in linkgit:git-notes[1]]\n+\tfor more information on the available strategies.\n \n notes.displayRef::\n-\tThe (fully qualified) refname from which to show notes when\n-\tshowing commit messages. The value of this variable can be set\n-\tto a glob, in which case notes from all matching refs will be\n-\tshown. You may also specify this configuration variable\n-\tseveral times. A warning will be issued for refs that do not\n-\texist, but a glob that does not match any refs is silently\n-\tignored.\n-+\n-This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`\n-environment variable, which must be a colon separated list of refs or\n-globs.\n-+\n-The effective value of \"core.notesRef\" (possibly overridden by\n-GIT_NOTES_REF) is also implicitly added to the list of refs to be\n-displayed.\n+\tWhich ref (or refs, if a glob or specified more than once), in\n+\taddition to the default set by `core.notesRef` or\n+\t`GIT_NOTES_REF`, to read notes from when showing commit\n+\tmessages with the 'git log' family of commands.\n+\tThis setting can be overridden on the command line or by the\n+\t`GIT_NOTES_DISPLAY_REF` environment variable.\n+\tSee linkgit:git-log[1].\n \n notes.rewrite.::\n \tWhen rewriting commits with (currently `amend` or\n-\t`rebase`) and this variable is set to `true`, Git\n-\tautomatically copies your notes from the original to the\n-\trewritten commit. Defaults to `true`, but see\n-\t\"notes.rewriteRef\" below.\n+\t`rebase`), if this variable is `false`, git will not copy\n+\tnotes from the original to the rewritten commit. Defaults to\n+\t`true`. See also \"`notes.rewriteRef`\" below.\n++\n+This setting can be overridden by the `GIT_NOTES_REWRITE_REF`\n+environment variable.\n \n notes.rewriteMode::\n-\tWhen copying notes during a rewrite (see the\n-\t\"notes.rewrite.\" option), determines what to do if\n-\tthe target commit already has a note. Must be one of\n-\t`overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`.\n-\tDefaults to `concatenate`.\n+\tWhen copying notes during a rewrite, what to do if the target\n+\tcommit already has a note. Must be one of `overwrite`,\n+\t`concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to\n+\t`concatenate`.\n +\n This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`\n environment variable.\n \n notes.rewriteRef::\n \tWhen copying notes during a rewrite, specifies the (fully\n-\tqualified) ref whose notes should be copied. The ref may be a\n-\tglob, in which case notes in all matching refs will be copied.\n-\tYou may also specify this configuration several times.\n+\tqualified) ref whose notes should be copied. May be a glob,\n+\tin which case notes in all matching refs will be copied. You\n+\tmay also specify this configuration several times.\n +\n Does not have a default value; you must configure this variable to\n enable note rewriting. Set it to `refs/notes/commits` to enable\n rewriting for the default commit notes.\n +\n-This setting can be overridden with the `GIT_NOTES_REWRITE_REF`\n-environment variable, which must be a colon separated list of refs or\n-globs.\n+Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 0a4200674c..79b2c60646 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -316,58 +316,8 @@ core.notesRef::\n \tThis setting can be overridden through the environment and\n \tcommand line.\n \n-notes.mergeStrategy::\n-\tWhich merge strategy to choose by default when resolving notes\n-\tconflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or\n-\t`cat_sort_uniq`. Defaults to `manual`. See \"NOTES MERGE STRATEGIES\"\n-\tsection above for more information on each strategy.\n-+\n-This setting can be overridden by passing the `--strategy` option.\n-\n-notes..mergeStrategy::\n-\tWhich merge strategy to choose when doing a notes merge into\n-\trefs/notes/. This overrides the more general\n-\t\"notes.mergeStrategy\". See the \"NOTES MERGE STRATEGIES\" section above\n-\tfor more information on each available strategy.\n-\n-notes.displayRef::\n-\tWhich ref (or refs, if a glob or specified more than once), in\n-\taddition to the default set by `core.notesRef` or\n-\t`GIT_NOTES_REF`, to read notes from when showing commit\n-\tmessages with the 'git log' family of commands.\n-\tThis setting can be overridden on the command line or by the\n-\t`GIT_NOTES_DISPLAY_REF` environment variable.\n-\tSee linkgit:git-log[1].\n-\n-notes.rewrite.::\n-\tWhen rewriting commits with (currently `amend` or\n-\t`rebase`), if this variable is `false`, git will not copy\n-\tnotes from the original to the rewritten commit. Defaults to\n-\t`true`. See also \"`notes.rewriteRef`\" below.\n-+\n-This setting can be overridden by the `GIT_NOTES_REWRITE_REF`\n-environment variable.\n-\n-notes.rewriteMode::\n-\tWhen copying notes during a rewrite, what to do if the target\n-\tcommit already has a note. Must be one of `overwrite`,\n-\t`concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to\n-\t`concatenate`.\n-+\n-This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`\n-environment variable.\n-\n-notes.rewriteRef::\n-\tWhen copying notes during a rewrite, specifies the (fully\n-\tqualified) ref whose notes should be copied. May be a glob,\n-\tin which case notes in all matching refs will be copied. You\n-\tmay also specify this configuration several times.\n-+\n-Does not have a default value; you must configure this variable to\n-enable note rewriting.\n-+\n-Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.\n-\n+:git-notes: 1\n+include::config/notes.txt[]\n \n ENVIRONMENT\n -----------\n-- \n2.37.0\n\n"},{"id":"459065","messageId":"xmqqfsj35y7t.fsf@gitster.g","threadId":"58160","inReplyTo":"439cfdf858f5b1917ae7ca3ca327bb33b42f71c7.1657819649.git.matheus.bernardino@usp.br","subject":"Re: [PATCH 1/3] doc: grep: unify configuration variables definitions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-14T18:46:30Z","receivedAt":"2022-07-14T18:46:40Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matheus Tavares writes:\n\n> The configuration variables for git-grep are duplicated in\n> \"Documentation/git-grep.txt\" and \"Documentation/config/grep.txt\", which\n> gqcan make maintenance difficult. The first also contains a definition\n\ngqcan?\n\n> that is not present in the latter (grep.fullName), and the latter\n> received a wording improvement that was not replicated in the former:\n> see 91028f765 (\"grep: clarify what `grep.patternType=default` means\",\n> 2021-12-05).\n>\n> To avoid such problems, unify the information in one file and include it\n> in the other.\n\nOK.\n\n> Signed-off-by: Matheus Tavares \n> ---\n> Documentation/config/grep.txt | 10 ++++++++--\n> Documentation/git-grep.txt | 37 ++++++-----------------------------\n> 2 files changed, 14 insertions(+), 33 deletions(-)\n>\n> diff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt\n> index 182edd813a..6996e64574 100644\n> --- a/Documentation/config/grep.txt\n> +++ b/Documentation/config/grep.txt\n> @@ -17,8 +17,14 @@ grep.extendedRegexp::\n> \tother than 'default'.\n> \n> grep.threads::\n> -\tNumber of grep worker threads to use.\n> -\tSee `grep.threads` in linkgit:git-grep[1] for more information.\n> +\tNumber of grep worker threads to use. See `--threads`\n> +ifndef::git-grep[]\n> +\tin linkgit:git-grep[1]\n> +endif::git-grep[]\n> +\tfor more information.\n> +\n> +grep.fullName::\n> +\tIf set to true, enable `--full-name` option by default.\n\nAll of the above makes sense.\n\n> --threads ::\n> -\tNumber of grep worker threads to use.\n> -\tSee `grep.threads` in 'CONFIGURATION' for more information.\n> +\tNumber of grep worker threads to use. If not provided (or set to\n> +\t0), Git will use as many worker threads as the number of logical\n> +\tcores available. The default value can also be set with the\n> +\t`grep.threads` configuration.\n\nThis change is clearly outside of the \"unify 'git config --help' and\n'git grep --help'\" theme, isn't it?\n\nI wonder if you want to leave this untouched, and instead put more\nwork and words in the description of grep.threads in the other file?\n"},{"id":"459066","messageId":"xmqqbktr5y4q.fsf@gitster.g","threadId":"58160","inReplyTo":"a25a6d89647638ffd682fb24ef0b5b6c9bed0941.1657819649.git.matheus.bernardino@usp.br","subject":"Re: [PATCH 2/3] doc: apply: unify configuration variables definitions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-14T18:48:21Z","receivedAt":"2022-07-14T18:49:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matheus Tavares writes:\n\n> +ifndef::git-apply[]\n> \tSee linkgit:git-apply[1].\n> +endif::git-apply[]\n> \n> apply.whitespace::\n> \tTells 'git apply' how to handle whitespaces, in the same way\n> -\tas the `--whitespace` option. See linkgit:git-apply[1].\n> +\tas the `--whitespace` option.\n> +ifndef::git-apply[]\n> +\tSee linkgit:git-apply[1].\n> +endif::git-apply[]\n\nMakes sense.\n"},{"id":"459080","messageId":"xmqqzghb4gwg.fsf@gitster.g","threadId":"58160","inReplyTo":"d39e826756e79ce7fe270175ad0d5ae523528af9.1657819649.git.matheus.bernardino@usp.br","subject":"Re: [PATCH 3/3] doc: notes: unify configuration variables definitions","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-14T19:45:51Z","receivedAt":"2022-07-14T19:46:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matheus Tavares writes:\n\n> \t`cat_sort_uniq`. Defaults to `manual`. See \"NOTES MERGE STRATEGIES\"\n> -\tsection of linkgit:git-notes[1] for more information on each strategy.\n> +\tsection\n> +ifdef::git-notes[above]\n> +ifndef::git-notes[of linkgit:git-notes[1]]\n> +\tfor more information on each strategy.\n\nThis is the first use of the single line ifdef/ifndef in our\nDocumentation. I assume you have verified the rendered output on\nboth AsciiDoc and AsciiDoctor?\n\n> -\t\"notes.mergeStrategy\". See the \"NOTES MERGE STRATEGIES\" section in\n> -\tlinkgit:git-notes[1] for more information on the available strategies.\n> +\t\"notes.mergeStrategy\". See the \"NOTES MERGE STRATEGIES\" section\n> +ifdef::git-notes[above]\n> +ifndef::git-notes[in linkgit:git-notes[1]]\n> +\tfor more information on the available strategies.\n\nDitto.\n\n> notes.displayRef::\n> -\tThe (fully qualified) refname from which to show notes when\n> -\tshowing commit messages. The value of this variable can be set\n> -\tto a glob, in which case notes from all matching refs will be\n> -\tshown. You may also specify this configuration variable\n> -\tseveral times. A warning will be issued for refs that do not\n> -\texist, but a glob that does not match any refs is silently\n> -\tignored.\n> -+\n> -This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`\n> -environment variable, which must be a colon separated list of refs or\n> -globs.\n> -+\n> -The effective value of \"core.notesRef\" (possibly overridden by\n> -GIT_NOTES_REF) is also implicitly added to the list of refs to be\n> -displayed.\n> +\tWhich ref (or refs, if a glob or specified more than once), in\n> +\taddition to the default set by `core.notesRef` or\n> +\t`GIT_NOTES_REF`, to read notes from when showing commit\n> +\tmessages with the 'git log' family of commands.\n> +\tThis setting can be overridden on the command line or by the\n> +\t`GIT_NOTES_DISPLAY_REF` environment variable.\n> +\tSee linkgit:git-log[1].\n\nThis is unrelated to the \"unify description in git-foo.txt and\nconfig/foo.txt in the documentation\" topic, isn't it?\n\nI haven't formed an opinion on the updated text, and it makes it\nharder to review when the content change is mixed in the \"unify\ndescription in two places\" topic, so I won't comment on the change\nof the contents. Please split them into two steps (a step with only\ncontent change, and then another step to remove the duplicated one\nby making one include the other). Same comment applies to [2/3].\n\n> notes.rewrite.::\n> \tWhen rewriting commits with (currently `amend` or\n> -\t`rebase`) and this variable is set to `true`, Git\n> -\tautomatically copies your notes from the original to the\n> -\trewritten commit. Defaults to `true`, but see\n> -\t\"notes.rewriteRef\" below.\n> +\t`rebase`), if this variable is `false`, git will not copy\n> +\tnotes from the original to the rewritten commit. Defaults to\n> +\t`true`. See also \"`notes.rewriteRef`\" below.\n> ++\n> +This setting can be overridden by the `GIT_NOTES_REWRITE_REF`\n> +environment variable.\n\nDitto.\n\n> notes.rewriteMode::\n> -\tWhen copying notes during a rewrite (see the\n> -\t\"notes.rewrite.\" option), determines what to do if\n> -\tthe target commit already has a note. Must be one of\n> -\t`overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`.\n> -\tDefaults to `concatenate`.\n> +\tWhen copying notes during a rewrite, what to do if the target\n> +\tcommit already has a note. Must be one of `overwrite`,\n> +\t`concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to\n> +\t`concatenate`.\n> +\n> This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`\n> environment variable.\n\nWe are losing the mention of \"notes.rewrite.\", which is\noutside the \"unify\" topic, isn't it?\n\n> notes.rewriteRef::\n> \tWhen copying notes during a rewrite, specifies the (fully\n> -\tqualified) ref whose notes should be copied. The ref may be a\n> -\tglob, in which case notes in all matching refs will be copied.\n> -\tYou may also specify this configuration several times.\n> +\tqualified) ref whose notes should be copied. May be a glob,\n> +\tin which case notes in all matching refs will be copied. You\n> +\tmay also specify this configuration several times.\n> +\n> Does not have a default value; you must configure this variable to\n> enable note rewriting. Set it to `refs/notes/commits` to enable\n> rewriting for the default commit notes.\n> +\n> -This setting can be overridden with the `GIT_NOTES_REWRITE_REF`\n> -environment variable, which must be a colon separated list of refs or\n> -globs.\n> +Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.\n\nDitto.\n\nThanks.\n"},{"id":"459086","messageId":"220714.86ilnz1j1i.gmgdl@evledraar.gmail.com","threadId":"58160","inReplyTo":"cover.1657819649.git.matheus.bernardino@usp.br","subject":"Re: [PATCH 0/3] doc: unify config info on some cmds","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-14T21:17:25Z","receivedAt":"2022-07-14T21:28:09Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Thu, Jul 14 2022, Matheus Tavares wrote:\n\n> These three patches attempt to remove duplication between some\n> config/*.txt and git-*.txt files, to facilitate maintenance and fix any\n> divergences.\n>\n> This series targets the most straightforward conversions, but there are\n> also other commands whose config documentation could possibly be unified\n> (maybe #leftoverbits):\n\nGreat think alike & all that, these patches are pretty much what I've\nhad locally & been meaning to submit for (check notes) around a year and\na half. So having this move forward is great.\n\nHere's a cleaned up version of what I have, which I figure is probably\nbetter linked-to than contributing to my E-Mail quota :):\n\n\thttps://github.com/git/git/compare/master...avar:git:avar/doc-config-includes\n\nI cleaned that up just now for this discussion, but I've had these\nrelatively more messy changes on top too, but I think those could/should\nfollow:\n\n\thttps://github.com/avar/git/compare/avar/doc-config-includes...avar:git:avar/doc-config-includes-split\n\nI in that second part I end up e.g. splitting config/gc.txt into that\nand config/gc/rerere.txt, so that we can include the latter in both\nconfig/gc.txt (which is included in git-gc.txt) and in git-rerere.txt\n(along with config/rerere.txt itself).\n\nI.e. to have all CONFIGURATION sections discuss all the config relevant\nto that command, if possible. Not just in the straightforward cases, but\nalso e.g. the \"rerere\" case where it needs to \"borrow\" a part of the\n\"gc\" section.\n\nAnother notable one is the config/color.txt, i.e. we want \"git branch\"\nand the like to discuss its part of the \"color\" configuration.\n\nAnyway, I'm happy to have your versions of this, although maybe the\nrange-diff below is useful to you to see if there's anything you'd like\nto change or steal (it's to the part one above).\n\nThe one thing I'd like you to reconsider is to drop the idea of adding\nthese \"ifndef::git-grep[]\" defines and the like. In your version it\nyields an arguably better result.\n\nBut I think what we should be going for is the more general direction\noutlined above, at which point that becomes quite a mess of\nifdefs. I.e. config/gc/rerere.txt would need to know what it's going to\nget include in, which would be N number of manpages in the genreal case,\nnot just \"main or config\" as this series leaves it.\n\nI think the solution I have to that in 1/9 in that first series is a\nbetter trade-off, i.e. we just (eventually, your series doesn't need to\ndo that) include some standard wording saying that what you're looking\nat in git-CMD(1) is transcluded as-is from the relevant part of\ngit-config(1). I.e.:\n\n\tEverything below this line in this section is selectively included\n\tfrom the linkgit:git-config[1] documentation. The content is the same\n\tas what's found there:\n\nWhat do you think about doing that instead?\n\n -: ----------- > 1: 5d0a4562ea8 docs: add and use include template for config/* includes\n -: ----------- > 2: 450a9d82bf2 docs: include a CONFIGURATION section\n -: ----------- > 3: 03cdf2d4e4e docs: add includes to the CONFIGURATION section\n -: ----------- > 4: 959b6ccd6e2 docs: move config discussion to CONFIGURATION section\n 1: 439cfdf858f ! 5: f20f207ece7 doc: grep: unify configuration variables definitions\n @@\n ## Metadata ##\n -Author: Matheus Tavares \n +Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - doc: grep: unify configuration variables definitions\n + grep docs: de-duplicate configuration sections\n \n - The configuration variables for git-grep are duplicated in\n - \"Documentation/git-grep.txt\" and \"Documentation/config/grep.txt\", which\n - gqcan make maintenance difficult. The first also contains a definition\n - that is not present in the latter (grep.fullName), and the latter\n - received a wording improvement that was not replicated in the former:\n - see 91028f765 (\"grep: clarify what `grep.patternType=default` means\",\n - 2021-12-05).\n + Include the \"config/grep.txt\" file in \"git-grep.txt\", instead of\n + repeating an almost identical description of the \"grep\" configuration\n + variables in two places.\n \n - To avoid such problems, unify the information in one file and include it\n - in the other.\n + There is no loss of information here that isn't shown in the addition\n + to \"grep.txt\". This change was made by copying the contents of\n + \"git-grep.txt\"'s version over the \"grep.txt\" version. Aside from the\n + change \"grep.txt\" being made here the two were identical.\n \n - Signed-off-by: Matheus Tavares \n + This documentation started being copy/pasted around in\n + b22520a37c8 (grep: allow -E and -n to be turned on by default via\n + configuration, 2011-03-30). After that in e.g. 6453f7b3486 (grep: add\n + grep.fullName config variable, 2014-03-17) they started drifting\n + apart, with only grep.fullName being described in the command\n + documentation.\n +\n + In 434e6e753fe (config.txt: move grep.* to a separate file,\n + 2018-10-27) we gained the include, but didn't do this next step, let's\n + do it now.\n +\n + Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/config/grep.txt ##\n @@ Documentation/config/grep.txt: grep.extendedRegexp::\n @@ Documentation/config/grep.txt: grep.extendedRegexp::\n grep.threads::\n -\tNumber of grep worker threads to use.\n -\tSee `grep.threads` in linkgit:git-grep[1] for more information.\n -+\tNumber of grep worker threads to use. See `--threads`\n -+ifndef::git-grep[]\n -+\tin linkgit:git-grep[1]\n -+endif::git-grep[]\n -+\tfor more information.\n ++\tNumber of grep worker threads to use. If unset (or set to 0), Git will\n ++\tuse as many threads as the number of logical cores available.\n +\n +grep.fullName::\n +\tIf set to true, enable `--full-name` option by default.\n @@ Documentation/config/grep.txt: grep.extendedRegexp::\n \tIf set to true, fall back to git grep --no-index if git grep\n \n ## Documentation/git-grep.txt ##\n -@@ Documentation/git-grep.txt: registered in the index file, or blobs in given tree objects. Patterns\n - are lists of one or more search expressions separated by newline\n - characters. An empty string as search expression matches all lines.\n - \n --\n - OPTIONS\n - -------\n - --cached::\n -@@ Documentation/git-grep.txt: providing this option will cause it to die.\n - \tcustom hunk-header' in linkgit:gitattributes[5]).\n - \n - --threads ::\n --\tNumber of grep worker threads to use.\n --\tSee `grep.threads` in 'CONFIGURATION' for more information.\n -+\tNumber of grep worker threads to use. If not provided (or set to\n -+\t0), Git will use as many worker threads as the number of logical\n -+\tcores available. The default value can also be set with the\n -+\t`grep.threads` configuration.\n - \n - -f ::\n - \tRead patterns from , one per line.\n @@ Documentation/git-grep.txt: performance in this case, it might be desirable to use `--threads=1`.\n CONFIGURATION\n -------------\n @@ Documentation/git-grep.txt: performance in this case, it might be desirable to u\n -grep.fallbackToNoIndex::\n -\tIf set to true, fall back to git grep --no-index if git grep\n -\tis executed outside of a git repository. Defaults to false.\n --\n -+:git-grep: 1\n ++include::includes/cmd-config-section-all.txt[]\n + \n +include::config/grep.txt[]\n \n GIT\n 2: a25a6d89647 < -: ----------- doc: apply: unify configuration variables definitions\n -: ----------- > 6: 58f8fccef11 send-email docs: de-duplicate configuration sections\n -: ----------- > 7: acb6fc2aef5 apply docs: de-duplicate configuration sections\n 3: 699dda58fc6 ! 8: c8725b99483 doc: notes: unify config variable definitions\n @@\n ## Metadata ##\n -Author: Matheus Tavares \n +Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - doc: notes: unify config variable definitions\n + notes docs: de-duplicate configuration sections\n \n - Unify duplicated configuration descriptions from git-notes.txt and\n - config.txt in order to facilitate maintenance and update. There are some\n - discrepancies between these two files: git-notes.txt received two\n - updates that were not made in config.txt: see 66c4c32\n - (\"Documentation/notes: simplify treatment of default display refs\",\n - 2010-05-08) and c5ce183 (\"Documentation/notes: clean up description of\n - rewriting configuration\", 2010-05-08 ). And there was also an update to\n - config.txt not propagated to git-notes.txt: see 2b4aa89 (\"Documentation:\n - basic configuration of notes.rewriteRef\", 2011-09-13). Let's make sure\n - to include all these three updates in the unified version.\n + Let's also fix the \"git-notes(1)\" docs so that we link to\n + \"git-config(1)\", not \"git-log(1)\" as a reference for the \"notes\" docs.\n \n - Signed-off-by: Matheus Tavares \n + Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/config/notes.txt ##\n @@ Documentation/config/notes.txt: notes.mergeStrategy::\n - \tWhich merge strategy to choose by default when resolving notes\n \tconflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or\n \t`cat_sort_uniq`. Defaults to `manual`. See \"NOTES MERGE STRATEGIES\"\n --\tsection of linkgit:git-notes[1] for more information on each strategy.\n -+\tsection\n -+ifdef::git-notes[above]\n -+ifndef::git-notes[of linkgit:git-notes[1]]\n -+\tfor more information on each strategy.\n + \tsection of linkgit:git-notes[1] for more information on each strategy.\n +++\n ++This setting can be overridden by passing the `--strategy` option to\n ++linkgit:git-notes[1].\n \n notes..mergeStrategy::\n \tWhich merge strategy to choose when doing a notes merge into\n - \trefs/notes/. This overrides the more general\n --\t\"notes.mergeStrategy\". See the \"NOTES MERGE STRATEGIES\" section in\n --\tlinkgit:git-notes[1] for more information on the available strategies.\n -+\t\"notes.mergeStrategy\". See the \"NOTES MERGE STRATEGIES\" section\n -+ifdef::git-notes[above]\n -+ifndef::git-notes[in linkgit:git-notes[1]]\n -+\tfor more information on the available strategies.\n +@@ Documentation/config/notes.txt: notes..mergeStrategy::\n + \tlinkgit:git-notes[1] for more information on the available strategies.\n \n notes.displayRef::\n -\tThe (fully qualified) refname from which to show notes when\n @@ Documentation/config/notes.txt: notes.mergeStrategy::\n -\tseveral times. A warning will be issued for refs that do not\n -\texist, but a glob that does not match any refs is silently\n -\tignored.\n --+\n --This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`\n --environment variable, which must be a colon separated list of refs or\n --globs.\n --+\n --The effective value of \"core.notesRef\" (possibly overridden by\n --GIT_NOTES_REF) is also implicitly added to the list of refs to be\n --displayed.\n +\tWhich ref (or refs, if a glob or specified more than once), in\n +\taddition to the default set by `core.notesRef` or\n +\t`GIT_NOTES_REF`, to read notes from when showing commit\n +\tmessages with the 'git log' family of commands.\n -+\tThis setting can be overridden on the command line or by the\n -+\t`GIT_NOTES_DISPLAY_REF` environment variable.\n -+\tSee linkgit:git-log[1].\n + +\n + This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`\n + environment variable, which must be a colon separated list of refs or\n + globs.\n + +\n ++A warning will be issued for refs that do not exist,\n ++but a glob that does not match any refs is silently ignored.\n +++\n ++This setting can be disabled by the `--no-notes` option to the 'git\n ++log' family of commands, or by the `--notes=` option accepted by\n ++those commands.\n +++\n + The effective value of \"core.notesRef\" (possibly overridden by\n + GIT_NOTES_REF) is also implicitly added to the list of refs to be\n + displayed.\n \n notes.rewrite.::\n \tWhen rewriting commits with (currently `amend` or\n @@ Documentation/config/notes.txt: notes.mergeStrategy::\n +\tnotes from the original to the rewritten commit. Defaults to\n +\t`true`. See also \"`notes.rewriteRef`\" below.\n ++\n -+This setting can be overridden by the `GIT_NOTES_REWRITE_REF`\n -+environment variable.\n ++This setting can be overridden with the `GIT_NOTES_REWRITE_REF`\n ++environment variable, which must be a colon separated list of refs or\n ++globs.\n \n notes.rewriteMode::\n --\tWhen copying notes during a rewrite (see the\n --\t\"notes.rewrite.\" option), determines what to do if\n --\tthe target commit already has a note. Must be one of\n --\t`overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`.\n --\tDefaults to `concatenate`.\n -+\tWhen copying notes during a rewrite, what to do if the target\n -+\tcommit already has a note. Must be one of `overwrite`,\n -+\t`concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to\n -+\t`concatenate`.\n - +\n - This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`\n - environment variable.\n + \tWhen copying notes during a rewrite (see the\n +@@ Documentation/config/notes.txt: environment variable.\n \n notes.rewriteRef::\n \tWhen copying notes during a rewrite, specifies the (fully\n @@ Documentation/config/notes.txt: notes.mergeStrategy::\n -environment variable, which must be a colon separated list of refs or\n -globs.\n +Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.\n ++See `notes.rewrite.` above for a further description of its format.\n +\n + ## Documentation/git-log.txt ##\n +@@ Documentation/git-log.txt: log.showSignature::\n + mailmap.*::\n + \tSee linkgit:git-shortlog[1].\n + \n +-notes.displayRef::\n +-\tWhich refs, in addition to the default set by `core.notesRef`\n +-\tor `GIT_NOTES_REF`, to read notes from when showing commit\n +-\tmessages with the `log` family of commands. See\n +-\tlinkgit:git-notes[1].\n +-+\n +-May be an unabbreviated ref name or a glob and may be specified\n +-multiple times. A warning will be issued for refs that do not exist,\n +-but a glob that does not match any refs is silently ignored.\n +-+\n +-This setting can be disabled by the `--no-notes` option,\n +-overridden by the `GIT_NOTES_DISPLAY_REF` environment variable,\n +-and overridden by the `--notes=` option.\n ++include::includes/cmd-config-section-rest.txt[]\n ++\n ++include::config/notes.txt[]\n + \n + GIT\n + ---\n \n ## Documentation/git-notes.txt ##\n +@@ Documentation/git-notes.txt: using the `--notes` option. Such notes are added as a patch commentary\n + after a three dash separator line.\n + \n + To change which notes are shown by 'git log', see the\n +-\"notes.displayRef\" configuration in linkgit:git-log[1].\n ++\"notes.displayRef\" configuration in linkgit:git-config[1].\n + \n + See the \"notes.rewrite.\" configuration for a way to carry\n + notes across commands that rewrite commits.\n @@ Documentation/git-notes.txt: core.notesRef::\n \tThis setting can be overridden through the environment and\n \tcommand line.\n @@ Documentation/git-notes.txt: core.notesRef::\n -+\n -This setting can be overridden by the `GIT_NOTES_REWRITE_REF`\n -environment variable.\n --\n ++include::includes/cmd-config-section-rest.txt[]\n + \n -notes.rewriteMode::\n -\tWhen copying notes during a rewrite, what to do if the target\n -\tcommit already has a note. Must be one of `overwrite`,\n @@ Documentation/git-notes.txt: core.notesRef::\n -enable note rewriting.\n -+\n -Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.\n --\n -+:git-notes: 1\n +include::config/notes.txt[]\n \n + \n ENVIRONMENT\n - -----------\n -: ----------- > 9: cffa925ccf9 log docs: de-duplicate configuration sections\n"},{"id":"459168","messageId":"CAHd-oW4zHA1YLX-5B1vYTA1f8PocziUCi0WxvSEkFUuf2GqKxg@mail.gmail.com","threadId":"58160","inReplyTo":"220714.86ilnz1j1i.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH 0/3] doc: unify config info on some cmds","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-07-15T19:58:31Z","receivedAt":"2022-07-15T19:58:53Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"Em qui, 14 de jul de 2022 18:27, Ævar Arnfjörð Bjarmason\n escreveu:\n>\n>\n> Here's a cleaned up version of what I have, which I figure is probably\n> better linked-to than contributing to my E-Mail quota :):\n>\n> https://github.com/git/git/compare/master...avar:git:avar/doc-config-includes\n\nThanks for sharing your version!\n\n> The one thing I'd like you to reconsider is to drop the idea of adding\n> these \"ifndef::git-grep[]\" defines and the like. In your version it\n> yields an arguably better result.\n>\n> But I think what we should be going for is the more general direction\n> outlined above, at which point that becomes quite a mess of\n> ifdefs. I.e. config/gc/rerere.txt would need to know what it's going to\n> get include in, which would be N number of manpages in the genreal case,\n> not just \"main or config\" as this series leaves it.\n>\n> I think the solution I have to that in 1/9 in that first series is a\n> better trade-off, i.e. we just (eventually, your series doesn't need to\n> do that) include some standard wording saying that what you're looking\n> at in git-CMD(1) is transcluded as-is from the relevant part of\n> git-config(1). I.e.:\n>\n> Everything below this line in this section is selectively included\n> from the linkgit:git-config[1] documentation. The content is the same\n> as what's found there:\n>\n> What do you think about doing that instead?\n\nI like the includes/* idea, and I agree that it is a more sensible way\nforward than the many 'ifndef[]::git-cmd.txt's :) Your linked changes\nalso cover a wider range of cmds than my series does. So I'd be happy\nto have them as a replacement to this series.\n"},{"id":"459188","messageId":"220716.867d4dze37.gmgdl@evledraar.gmail.com","threadId":"58160","inReplyTo":"CAHd-oW4zHA1YLX-5B1vYTA1f8PocziUCi0WxvSEkFUuf2GqKxg@mail.gmail.com","subject":"Re: [PATCH 0/3] doc: unify config info on some cmds","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-16T07:53:23Z","receivedAt":"2022-07-16T07:55:29Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Fri, Jul 15 2022, Matheus Tavares wrote:\n\n> Em qui, 14 de jul de 2022 18:27, Ævar Arnfjörð Bjarmason\n> escreveu:\n>>\n>>\n>> Here's a cleaned up version of what I have, which I figure is probably\n>> better linked-to than contributing to my E-Mail quota :):\n>>\n>> https://github.com/git/git/compare/master...avar:git:avar/doc-config-includes\n>\n> Thanks for sharing your version!\n>\n>> The one thing I'd like you to reconsider is to drop the idea of adding\n>> these \"ifndef::git-grep[]\" defines and the like. In your version it\n>> yields an arguably better result.\n>>\n>> But I think what we should be going for is the more general direction\n>> outlined above, at which point that becomes quite a mess of\n>> ifdefs. I.e. config/gc/rerere.txt would need to know what it's going to\n>> get include in, which would be N number of manpages in the genreal case,\n>> not just \"main or config\" as this series leaves it.\n>>\n>> I think the solution I have to that in 1/9 in that first series is a\n>> better trade-off, i.e. we just (eventually, your series doesn't need to\n>> do that) include some standard wording saying that what you're looking\n>> at in git-CMD(1) is transcluded as-is from the relevant part of\n>> git-config(1). I.e.:\n>>\n>> Everything below this line in this section is selectively included\n>> from the linkgit:git-config[1] documentation. The content is the same\n>> as what's found there:\n>>\n>> What do you think about doing that instead?\n>\n> I like the includes/* idea, and I agree that it is a more sensible way\n> forward than the many 'ifndef[]::git-cmd.txt's :) Your linked changes\n> also cover a wider range of cmds than my series does. So I'd be happy\n> to have them as a replacement to this series.\n\nI can submit what I've got as a v2 if you'd like, but I'd be just as\nhappy with you picking this up & running with it, whether that's seeing\nwhat you'd like to integrate into your series here, or perhaps rebasing\nyour patches on the 1st patch I have (the one that introduces those\n\"Everything below this...\" template)>\n\nBut OTOH if you're going to drop the \"ifndef\" idea I think what you'd\ncome up with will be identical to the patch bodies I've got for the bits\nyou modified, so perhaps it's easier if I just submit mine...\n\nJust let me know, I'd just like these docs fixed & unified.\n"},{"id":"459230","messageId":"CAHd-oW6ompHPJ_8X6XqwBJs8mda52a=NJge7=AwVwuEg-9VHZw@mail.gmail.com","threadId":"58160","inReplyTo":"220716.867d4dze37.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH 0/3] doc: unify config info on some cmds","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-07-17T17:13:14Z","receivedAt":"2022-07-17T17:13:32Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"On Sat, Jul 16, 2022 at 4:55 AM Ævar Arnfjörð Bjarmason\n wrote:\n>\n> I can submit what I've got as a v2 if you'd like, but I'd be just as\n> happy with you picking this up & running with it, whether that's seeing\n> what you'd like to integrate into your series here, or perhaps rebasing\n> your patches on the 1st patch I have (the one that introduces those\n> \"Everything below this...\" template)\n>\n> But OTOH if you're going to drop the \"ifndef\" idea I think what you'd\n> come up with will be identical to the patch bodies I've got for the bits\n> you modified, so perhaps it's easier if I just submit mine...\n\nYup, that's what I thought too. Feel free to do so, if you like :)\n"},{"id":"460172","messageId":"patch-v2-1.9-ef6fa5450e7-20220729T081959Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v2-0.9-00000000000-20220729T081959Z-avarab@gmail.com","subject":"[PATCH v2 1/9] docs: add and use include template for config/* includes","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-29T08:25:47Z","receivedAt":"2022-07-29T08:26:37Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"In b6a8d09f6d8 (gc docs: include the \"gc.*\" section from \"config\" in\n\"gc\", 2019-04-07) the \"git gc\" documentation was made to include the\nconfig/gc.txt in its \"CONFIGURATION\" section. We do that in several\nother places, but \"git gc\" was the only one with a blurb above the\ninclude to orient the reader.\n\nWe don't want readers to carefully scrutinize \"git-config(1)\" and\n\"git-gc(1)\" looking for discrepancies, instead we should tell them\nthat the latter includes a part of the former.\n\nThis change formalizes that wording in two new templates to be\nincluded, one for the \"git gc\" case where the entire section is\nincluded from \"git-config(1)\", and another for when the inclusion of\n\"git-config(1)\" follows discussion unique to that documentation. In\norder to use that re-arrange the order of those being discussed in the\n\"git-merge(1)\" documentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-fsck.txt | 2 ++\n Documentation/git-gc.txt | 3 +--\n Documentation/git-imap-send.txt | 2 ++\n Documentation/git-merge.txt | 5 ++++-\n Documentation/git-mergetool.txt | 3 +++\n Documentation/git-rebase.txt | 2 ++\n Documentation/includes/cmd-config-section-all.txt | 3 +++\n Documentation/includes/cmd-config-section-rest.txt | 3 +++\n 9 files changed, 21 insertions(+), 3 deletions(-)\n create mode 100644 Documentation/includes/cmd-config-section-all.txt\n create mode 100644 Documentation/includes/cmd-config-section-rest.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex 4f801f4e4c9..85b2088b888 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -51,6 +51,7 @@ HOWTO_TXT += $(wildcard howto/*.txt)\n \n DOC_DEP_TXT += $(wildcard *.txt)\n DOC_DEP_TXT += $(wildcard config/*.txt)\n+DOC_DEP_TXT += $(wildcard includes/*.txt)\n \n ifdef MAN_FILTER\n MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))\ndiff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt\nindex 5088783dccb..29318ea957e 100644\n--- a/Documentation/git-fsck.txt\n+++ b/Documentation/git-fsck.txt\n@@ -107,6 +107,8 @@ care about this output and want to speed it up further.\n CONFIGURATION\n -------------\n \n+include::includes/cmd-config-section-all.txt[]\n+\n include::config/fsck.txt[]\n \n DISCUSSION\ndiff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt\nindex 0af7540a0c8..a65c9aa62d6 100644\n--- a/Documentation/git-gc.txt\n+++ b/Documentation/git-gc.txt\n@@ -110,8 +110,7 @@ users and their repositories.\n CONFIGURATION\n -------------\n \n-The below documentation is the same as what's found in\n-linkgit:git-config[1]:\n+include::includes/cmd-config-section-all.txt[]\n \n include::config/gc.txt[]\n \ndiff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt\nindex 63cf498ce9f..f7b18515141 100644\n--- a/Documentation/git-imap-send.txt\n+++ b/Documentation/git-imap-send.txt\n@@ -54,6 +54,8 @@ CONFIGURATION\n To use the tool, `imap.folder` and either `imap.tunnel` or `imap.host` must be set\n to appropriate values.\n \n+include::includes/cmd-config-section-rest.txt[]\n+\n include::config/imap.txt[]\n \n EXAMPLES\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex 3125473cc1d..6e5db8ef4c5 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -386,13 +386,16 @@ include::merge-strategies.txt[]\n \n CONFIGURATION\n -------------\n-include::config/merge.txt[]\n \n branch..mergeOptions::\n \tSets default options for merging into branch . The syntax and\n \tsupported options are the same as those of 'git merge', but option\n \tvalues containing whitespace characters are currently not supported.\n \n+include::includes/cmd-config-section-rest.txt[]\n+\n+include::config/merge.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],\ndiff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt\nindex f784027bc13..c44e205629b 100644\n--- a/Documentation/git-mergetool.txt\n+++ b/Documentation/git-mergetool.txt\n@@ -102,6 +102,9 @@ success of the resolution after the custom tool has exited.\n CONFIGURATION\n -------------\n :git-mergetool: 1\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n include::config/mergetool.txt[]\n \n TEMPORARY FILES\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex a872ab0fbd1..d9b6af8a571 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -1252,6 +1252,8 @@ merge cmake\n CONFIGURATION\n -------------\n \n+include::includes/cmd-config-section-all.txt[]\n+\n include::config/rebase.txt[]\n include::config/sequencer.txt[]\n \ndiff --git a/Documentation/includes/cmd-config-section-all.txt b/Documentation/includes/cmd-config-section-all.txt\nnew file mode 100644\nindex 00000000000..296a239f2ab\n--- /dev/null\n+++ b/Documentation/includes/cmd-config-section-all.txt\n@@ -0,0 +1,3 @@\n+Everything below this line in this section is selectively included\n+from the linkgit:git-config[1] documentation. The content is the same\n+as what's found there:\ndiff --git a/Documentation/includes/cmd-config-section-rest.txt b/Documentation/includes/cmd-config-section-rest.txt\nnew file mode 100644\nindex 00000000000..fe4721dac76\n--- /dev/null\n+++ b/Documentation/includes/cmd-config-section-rest.txt\n@@ -0,0 +1,3 @@\n+The discussion above this line is unique to this documentation, but\n+everything below is included from section(s) in linkgit:git-config[1]\n+aplicable to this command:\n-- \n2.37.1.1196.g8af3636bc64\n\n"},{"id":"460173","messageId":"cover-v2-0.9-00000000000-20220729T081959Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover.1657819649.git.matheus.bernardino@usp.br","subject":"[PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-29T08:25:46Z","receivedAt":"2022-07-29T08:26:39Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"This series is a follow-up to Matheus Tavares's v1[1] patches to\nde-duplicate some of our configuration documentation, per [2] I'm\nsubmitting this as a replacement series.\n\nI've had this laying around for a while (around 1 1/2 yrs). Per the\ndiffstat we add a CONFIGURATION section to various built-ins, with the\nconfiguration that's relevant to them.\n\nDoing that isn't new, e.g. we do so for git-gc(1) and a few others\n(see 1/9) and https://git-scm.com/docs/git-gc#_configuration; but\nthis takes the concept much further.\n\nI have follow-up patches that come after this, which involve adding\neven more exhaustive configuration to these sections, e.g. each\ncommand getting its own color.* configuration when appropriate. Doing\nthat requires splitting up the Documentation/config/*.txt files into\nsub-includes.\n\nThis series stops just short of that.\n\n1. https://lore.kernel.org/git/cover.1657819649.git.matheus.bernardino@usp.br/\n2. https://lore.kernel.org/git/CAHd-oW6ompHPJ_8X6XqwBJs8mda52a=NJge7=AwVwuEg-9VHZw@mail.gmail.com/\n\nÆvar Arnfjörð Bjarmason (9):\n docs: add and use include template for config/* includes\n grep docs: de-duplicate configuration sections\n send-email docs: de-duplicate configuration sections\n apply docs: de-duplicate configuration sections\n notes docs: de-duplicate configuration sections\n difftool docs: de-duplicate configuration sections\n log docs: de-duplicate configuration sections\n docs: add CONFIGURATION sections that map to a built-in\n docs: add CONFIGURATION sections that fuzzy map to built-ins\n\n Documentation/Makefile | 1 +\n Documentation/config/diff.txt | 15 ------\n Documentation/config/difftool.txt | 28 ++++++++--\n Documentation/config/grep.txt | 7 ++-\n Documentation/config/log.txt | 18 +++++--\n Documentation/config/notes.txt | 43 +++++++++------\n Documentation/config/sendemail.txt | 40 ++++++++++++--\n Documentation/git-add.txt | 7 +++\n Documentation/git-am.txt | 7 +++\n Documentation/git-apply.txt | 10 ++--\n Documentation/git-blame.txt | 6 +++\n Documentation/git-branch.txt | 4 ++\n Documentation/git-checkout.txt | 7 +++\n Documentation/git-clean.txt | 7 +++\n Documentation/git-clone.txt | 9 ++++\n Documentation/git-column.txt | 7 +++\n Documentation/git-commit-graph.txt | 7 +++\n Documentation/git-commit.txt | 4 ++\n Documentation/git-diff.txt | 7 +++\n Documentation/git-difftool.txt | 27 ++--------\n Documentation/git-fast-import.txt | 7 +++\n Documentation/git-fetch.txt | 7 +++\n Documentation/git-fsck.txt | 2 +\n Documentation/git-gc.txt | 3 +-\n Documentation/git-grep.txt | 29 +---------\n Documentation/git-imap-send.txt | 2 +\n Documentation/git-log.txt | 49 +++--------------\n Documentation/git-mailinfo.txt | 7 +++\n Documentation/git-maintenance.txt | 7 +++\n Documentation/git-merge.txt | 5 +-\n Documentation/git-mergetool.txt | 3 ++\n Documentation/git-notes.txt | 54 ++-----------------\n Documentation/git-push.txt | 7 +++\n Documentation/git-rebase.txt | 2 +\n Documentation/git-revert.txt | 7 +++\n Documentation/git-send-email.txt | 36 +------------\n Documentation/git-show-branch.txt | 7 +++\n Documentation/git-stash.txt | 7 +++\n Documentation/git-switch.txt | 7 +++\n .../includes/cmd-config-section-all.txt | 3 ++\n .../includes/cmd-config-section-rest.txt | 3 ++\n 41 files changed, 284 insertions(+), 231 deletions(-)\n create mode 100644 Documentation/includes/cmd-config-section-all.txt\n create mode 100644 Documentation/includes/cmd-config-section-rest.txt\n\nRange-diff against v1:\n -: ----------- > 1: ef6fa5450e7 docs: add and use include template for config/* includes\n 1: f3b275fd5b5 ! 2: 5f07f87710c doc: grep: unify configuration variables definitions\n @@\n ## Metadata ##\n -Author: Matheus Tavares \n +Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - doc: grep: unify configuration variables definitions\n + grep docs: de-duplicate configuration sections\n \n - The configuration variables for git-grep are duplicated in\n - \"Documentation/git-grep.txt\" and \"Documentation/config/grep.txt\", which\n - gqcan make maintenance difficult. The first also contains a definition\n - that is not present in the latter (grep.fullName), and the latter\n - received a wording improvement that was not replicated in the former:\n - see 91028f765 (\"grep: clarify what `grep.patternType=default` means\",\n - 2021-12-05).\n + Include the \"config/grep.txt\" file in \"git-grep.txt\", instead of\n + repeating an almost identical description of the \"grep\" configuration\n + variables in two places.\n \n - To avoid such problems, unify the information in one file and include it\n - in the other.\n + There is no loss of information here that isn't shown in the addition\n + to \"grep.txt\". This change was made by copying the contents of\n + \"git-grep.txt\"'s version over the \"grep.txt\" version. Aside from the\n + change \"grep.txt\" being made here the two were identical.\n \n - Signed-off-by: Matheus Tavares \n + This documentation started being copy/pasted around in\n + b22520a37c8 (grep: allow -E and -n to be turned on by default via\n + configuration, 2011-03-30). After that in e.g. 6453f7b3486 (grep: add\n + grep.fullName config variable, 2014-03-17) they started drifting\n + apart, with only grep.fullName being described in the command\n + documentation.\n +\n + In 434e6e753fe (config.txt: move grep.* to a separate file,\n + 2018-10-27) we gained the include, but didn't do this next step, let's\n + do it now.\n +\n + Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/config/grep.txt ##\n @@ Documentation/config/grep.txt: grep.extendedRegexp::\n @@ Documentation/config/grep.txt: grep.extendedRegexp::\n grep.threads::\n -\tNumber of grep worker threads to use.\n -\tSee `grep.threads` in linkgit:git-grep[1] for more information.\n -+\tNumber of grep worker threads to use. See `--threads`\n -+ifndef::git-grep[]\n -+\tin linkgit:git-grep[1]\n -+endif::git-grep[]\n -+\tfor more information.\n ++\tNumber of grep worker threads to use. If unset (or set to 0), Git will\n ++\tuse as many threads as the number of logical cores available.\n +\n +grep.fullName::\n +\tIf set to true, enable `--full-name` option by default.\n @@ Documentation/config/grep.txt: grep.extendedRegexp::\n \tIf set to true, fall back to git grep --no-index if git grep\n \n ## Documentation/git-grep.txt ##\n -@@ Documentation/git-grep.txt: registered in the index file, or blobs in given tree objects. Patterns\n - are lists of one or more search expressions separated by newline\n - characters. An empty string as search expression matches all lines.\n - \n --\n - OPTIONS\n - -------\n - --cached::\n -@@ Documentation/git-grep.txt: providing this option will cause it to die.\n - \ta non-zero status.\n - \n - --threads ::\n --\tNumber of grep worker threads to use.\n --\tSee `grep.threads` in 'CONFIGURATION' for more information.\n -+\tNumber of grep worker threads to use. If not provided (or set to\n -+\t0), Git will use as many worker threads as the number of logical\n -+\tcores available. The default value can also be set with the\n -+\t`grep.threads` configuration.\n - \n - -f ::\n - \tRead patterns from , one per line.\n @@ Documentation/git-grep.txt: performance in this case, it might be desirable to use `--threads=1`.\n CONFIGURATION\n -------------\n @@ Documentation/git-grep.txt: performance in this case, it might be desirable to u\n -grep.fallbackToNoIndex::\n -\tIf set to true, fall back to git grep --no-index if git grep\n -\tis executed outside of a git repository. Defaults to false.\n --\n -+:git-grep: 1\n ++include::includes/cmd-config-section-all.txt[]\n + \n +include::config/grep.txt[]\n \n GIT\n -: ----------- > 3: 8138dc54e3e send-email docs: de-duplicate configuration sections\n 2: d40ed2c351f ! 4: b9750ae43e1 doc: apply: unify configuration variables definitions\n @@\n ## Metadata ##\n -Author: Matheus Tavares \n +Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - doc: apply: unify configuration variables definitions\n + apply docs: de-duplicate configuration sections\n \n - Note that apply.ignoreWhitespace and apply.whitespace are defined with\n - slightly different wordings at git-apply.txt and config/apply.txt.\n - Nevertheless, there is no loss of information from using one or the\n - other, so I kept the latter for the single unified definition.\n + The wording is not identical to Documentation/config/apply.txt, but\n + that version is better.\n \n - Signed-off-by: Matheus Tavares \n -\n - ## Documentation/config/apply.txt ##\n -@@ Documentation/config/apply.txt: apply.ignoreWhitespace::\n - \toption.\n - \tWhen set to one of: no, none, never, false tells 'git apply' to\n - \trespect all whitespace differences.\n -+ifndef::git-apply[]\n - \tSee linkgit:git-apply[1].\n -+endif::git-apply[]\n - \n - apply.whitespace::\n - \tTells 'git apply' how to handle whitespaces, in the same way\n --\tas the `--whitespace` option. See linkgit:git-apply[1].\n -+\tas the `--whitespace` option.\n -+ifndef::git-apply[]\n -+\tSee linkgit:git-apply[1].\n -+endif::git-apply[]\n + Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/git-apply.txt ##\n @@ Documentation/git-apply.txt: has no effect when `--index` or `--cached` is in use.\n @@ Documentation/git-apply.txt: has no effect when `--index` or `--cached` is in us\n -apply.whitespace::\n -\tWhen no `--whitespace` flag is given from the command\n -\tline, this configuration item is used as the default.\n -+:git-apply: 1\n ++include::includes/cmd-config-section-all.txt[]\n ++\n +include::config/apply.txt[]\n \n SUBMODULES\n 3: 5338d50c99c ! 5: 1b6c8c75df7 doc: notes: unify configuration variables definitions\n @@\n ## Metadata ##\n -Author: Matheus Tavares \n +Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - doc: notes: unify configuration variables definitions\n + notes docs: de-duplicate configuration sections\n \n - Unify duplicated configuration descriptions from git-notes.txt and\n - config.txt in order to facilitate maintenance and update. There are some\n - discrepancies between these two files: git-notes.txt received two\n - updates that were not made in config.txt: see 66c4c32\n - (\"Documentation/notes: simplify treatment of default display refs\",\n - 2010-05-08) and c5ce183 (\"Documentation/notes: clean up description of\n - rewriting configuration\", 2010-05-08 ). And there was also an update to\n - config.txt not propagated to git-notes.txt: see 2b4aa89 (\"Documentation:\n - basic configuration of notes.rewriteRef\", 2011-09-13). Let's make sure\n - to include all these three updates in the unified version.\n + Let's also fix the \"git-notes(1)\" docs so that we link to\n + \"git-config(1)\", not \"git-log(1)\" as a reference for the \"notes\" docs.\n \n - Signed-off-by: Matheus Tavares \n + Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/config/notes.txt ##\n @@ Documentation/config/notes.txt: notes.mergeStrategy::\n - \tWhich merge strategy to choose by default when resolving notes\n \tconflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or\n \t`cat_sort_uniq`. Defaults to `manual`. See \"NOTES MERGE STRATEGIES\"\n --\tsection of linkgit:git-notes[1] for more information on each strategy.\n -+\tsection\n -+ifdef::git-notes[above]\n -+ifndef::git-notes[of linkgit:git-notes[1]]\n -+\tfor more information on each strategy.\n + \tsection of linkgit:git-notes[1] for more information on each strategy.\n +++\n ++This setting can be overridden by passing the `--strategy` option to\n ++linkgit:git-notes[1].\n \n notes..mergeStrategy::\n \tWhich merge strategy to choose when doing a notes merge into\n - \trefs/notes/. This overrides the more general\n --\t\"notes.mergeStrategy\". See the \"NOTES MERGE STRATEGIES\" section in\n --\tlinkgit:git-notes[1] for more information on the available strategies.\n -+\t\"notes.mergeStrategy\". See the \"NOTES MERGE STRATEGIES\" section\n -+ifdef::git-notes[above]\n -+ifndef::git-notes[in linkgit:git-notes[1]]\n -+\tfor more information on the available strategies.\n +@@ Documentation/config/notes.txt: notes..mergeStrategy::\n + \tlinkgit:git-notes[1] for more information on the available strategies.\n \n notes.displayRef::\n -\tThe (fully qualified) refname from which to show notes when\n @@ Documentation/config/notes.txt: notes.mergeStrategy::\n -\tseveral times. A warning will be issued for refs that do not\n -\texist, but a glob that does not match any refs is silently\n -\tignored.\n --+\n --This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`\n --environment variable, which must be a colon separated list of refs or\n --globs.\n --+\n --The effective value of \"core.notesRef\" (possibly overridden by\n --GIT_NOTES_REF) is also implicitly added to the list of refs to be\n --displayed.\n +\tWhich ref (or refs, if a glob or specified more than once), in\n +\taddition to the default set by `core.notesRef` or\n +\t`GIT_NOTES_REF`, to read notes from when showing commit\n +\tmessages with the 'git log' family of commands.\n -+\tThis setting can be overridden on the command line or by the\n -+\t`GIT_NOTES_DISPLAY_REF` environment variable.\n -+\tSee linkgit:git-log[1].\n + +\n + This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`\n + environment variable, which must be a colon separated list of refs or\n + globs.\n + +\n ++A warning will be issued for refs that do not exist,\n ++but a glob that does not match any refs is silently ignored.\n +++\n ++This setting can be disabled by the `--no-notes` option to the 'git\n ++log' family of commands, or by the `--notes=` option accepted by\n ++those commands.\n +++\n + The effective value of \"core.notesRef\" (possibly overridden by\n + GIT_NOTES_REF) is also implicitly added to the list of refs to be\n + displayed.\n \n notes.rewrite.::\n \tWhen rewriting commits with (currently `amend` or\n @@ Documentation/config/notes.txt: notes.mergeStrategy::\n +\tnotes from the original to the rewritten commit. Defaults to\n +\t`true`. See also \"`notes.rewriteRef`\" below.\n ++\n -+This setting can be overridden by the `GIT_NOTES_REWRITE_REF`\n -+environment variable.\n ++This setting can be overridden with the `GIT_NOTES_REWRITE_REF`\n ++environment variable, which must be a colon separated list of refs or\n ++globs.\n \n notes.rewriteMode::\n --\tWhen copying notes during a rewrite (see the\n --\t\"notes.rewrite.\" option), determines what to do if\n --\tthe target commit already has a note. Must be one of\n --\t`overwrite`, `concatenate`, `cat_sort_uniq`, or `ignore`.\n --\tDefaults to `concatenate`.\n -+\tWhen copying notes during a rewrite, what to do if the target\n -+\tcommit already has a note. Must be one of `overwrite`,\n -+\t`concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to\n -+\t`concatenate`.\n - +\n - This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`\n - environment variable.\n + \tWhen copying notes during a rewrite (see the\n +@@ Documentation/config/notes.txt: environment variable.\n \n notes.rewriteRef::\n \tWhen copying notes during a rewrite, specifies the (fully\n @@ Documentation/config/notes.txt: notes.mergeStrategy::\n -environment variable, which must be a colon separated list of refs or\n -globs.\n +Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.\n ++See `notes.rewrite.` above for a further description of its format.\n +\n + ## Documentation/git-log.txt ##\n +@@ Documentation/git-log.txt: log.showSignature::\n + mailmap.*::\n + \tSee linkgit:git-shortlog[1].\n + \n +-notes.displayRef::\n +-\tWhich refs, in addition to the default set by `core.notesRef`\n +-\tor `GIT_NOTES_REF`, to read notes from when showing commit\n +-\tmessages with the `log` family of commands. See\n +-\tlinkgit:git-notes[1].\n +-+\n +-May be an unabbreviated ref name or a glob and may be specified\n +-multiple times. A warning will be issued for refs that do not exist,\n +-but a glob that does not match any refs is silently ignored.\n +-+\n +-This setting can be disabled by the `--no-notes` option,\n +-overridden by the `GIT_NOTES_DISPLAY_REF` environment variable,\n +-and overridden by the `--notes=` option.\n ++include::includes/cmd-config-section-rest.txt[]\n ++\n ++include::config/notes.txt[]\n + \n + GIT\n + ---\n \n ## Documentation/git-notes.txt ##\n +@@ Documentation/git-notes.txt: using the `--notes` option. Such notes are added as a patch commentary\n + after a three dash separator line.\n + \n + To change which notes are shown by 'git log', see the\n +-\"notes.displayRef\" configuration in linkgit:git-log[1].\n ++\"notes.displayRef\" configuration in linkgit:git-config[1].\n + \n + See the \"notes.rewrite.\" configuration for a way to carry\n + notes across commands that rewrite commits.\n @@ Documentation/git-notes.txt: core.notesRef::\n \tThis setting can be overridden through the environment and\n \tcommand line.\n @@ Documentation/git-notes.txt: core.notesRef::\n -+\n -This setting can be overridden by the `GIT_NOTES_REWRITE_REF`\n -environment variable.\n --\n ++include::includes/cmd-config-section-rest.txt[]\n + \n -notes.rewriteMode::\n -\tWhen copying notes during a rewrite, what to do if the target\n -\tcommit already has a note. Must be one of `overwrite`,\n @@ Documentation/git-notes.txt: core.notesRef::\n -enable note rewriting.\n -+\n -Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.\n --\n -+:git-notes: 1\n +include::config/notes.txt[]\n \n + \n ENVIRONMENT\n - -----------\n -: ----------- > 6: b3a5ea46bb5 difftool docs: de-duplicate configuration sections\n -: ----------- > 7: 08d98767384 log docs: de-duplicate configuration sections\n -: ----------- > 8: 5c379ab1476 docs: add CONFIGURATION sections that map to a built-in\n -: ----------- > 9: 91689154926 docs: add CONFIGURATION sections that fuzzy map to built-ins\n-- \n2.37.1.1196.g8af3636bc64\n\n"},{"id":"460174","messageId":"patch-v2-2.9-5f07f87710c-20220729T081959Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v2-0.9-00000000000-20220729T081959Z-avarab@gmail.com","subject":"[PATCH v2 2/9] grep docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-29T08:25:48Z","receivedAt":"2022-07-29T08:26:41Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Include the \"config/grep.txt\" file in \"git-grep.txt\", instead of\nrepeating an almost identical description of the \"grep\" configuration\nvariables in two places.\n\nThere is no loss of information here that isn't shown in the addition\nto \"grep.txt\". This change was made by copying the contents of\n\"git-grep.txt\"'s version over the \"grep.txt\" version. Aside from the\nchange \"grep.txt\" being made here the two were identical.\n\nThis documentation started being copy/pasted around in\nb22520a37c8 (grep: allow -E and -n to be turned on by default via\nconfiguration, 2011-03-30). After that in e.g. 6453f7b3486 (grep: add\ngrep.fullName config variable, 2014-03-17) they started drifting\napart, with only grep.fullName being described in the command\ndocumentation.\n\nIn 434e6e753fe (config.txt: move grep.* to a separate file,\n2018-10-27) we gained the include, but didn't do this next step, let's\ndo it now.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/grep.txt | 7 +++++--\n Documentation/git-grep.txt | 29 ++---------------------------\n 2 files changed, 7 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt\nindex 182edd813a5..e521f20390c 100644\n--- a/Documentation/config/grep.txt\n+++ b/Documentation/config/grep.txt\n@@ -17,8 +17,11 @@ grep.extendedRegexp::\n \tother than 'default'.\n \n grep.threads::\n-\tNumber of grep worker threads to use.\n-\tSee `grep.threads` in linkgit:git-grep[1] for more information.\n+\tNumber of grep worker threads to use. If unset (or set to 0), Git will\n+\tuse as many threads as the number of logical cores available.\n+\n+grep.fullName::\n+\tIf set to true, enable `--full-name` option by default.\n \n grep.fallbackToNoIndex::\n \tIf set to true, fall back to git grep --no-index if git grep\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 58d944bd578..dabdbe8471d 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -343,34 +343,9 @@ performance in this case, it might be desirable to use `--threads=1`.\n CONFIGURATION\n -------------\n \n-grep.lineNumber::\n-\tIf set to true, enable `-n` option by default.\n-\n-grep.column::\n-\tIf set to true, enable the `--column` option by default.\n-\n-grep.patternType::\n-\tSet the default matching behavior. Using a value of 'basic', 'extended',\n-\t'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,\n-\t`--fixed-strings`, or `--perl-regexp` option accordingly, while the\n-\tvalue 'default' will return to the default matching behavior.\n-\n-grep.extendedRegexp::\n-\tIf set to true, enable `--extended-regexp` option by default. This\n-\toption is ignored when the `grep.patternType` option is set to a value\n-\tother than 'default'.\n-\n-grep.threads::\n-\tNumber of grep worker threads to use. If unset (or set to 0), Git will\n-\tuse as many threads as the number of logical cores available.\n-\n-grep.fullName::\n-\tIf set to true, enable `--full-name` option by default.\n-\n-grep.fallbackToNoIndex::\n-\tIf set to true, fall back to git grep --no-index if git grep\n-\tis executed outside of a git repository. Defaults to false.\n+include::includes/cmd-config-section-all.txt[]\n \n+include::config/grep.txt[]\n \n GIT\n ---\n-- \n2.37.1.1196.g8af3636bc64\n\n"},{"id":"460175","messageId":"patch-v2-3.9-8138dc54e3e-20220729T081959Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v2-0.9-00000000000-20220729T081959Z-avarab@gmail.com","subject":"[PATCH v2 3/9] send-email docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-29T08:25:49Z","receivedAt":"2022-07-29T08:26:42Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"De-duplicate the discussion of \"send-email\" configuration, such that\nthe \"git-config(1)\" manual page becomes the source of truth, and\n\"git-send-email(1)\" includes the relevant part.\n\nMost commands that suffered from such duplication had diverging text\ndiscussing the same variables, but in this case some config was also\nonly discussed in one or the other.\n\nThis is mostly a move-only change, the exception is a minor rewording\nof changing wording like \"see above\" to \"see linkgit:git-config[1]\",\nas well as a clarification about the big section of command-line\noption tweaking config being discussed in git-send-email(1)'s main\ndocs.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/sendemail.txt | 40 +++++++++++++++++++++++++++---\n Documentation/git-send-email.txt | 36 ++-------------------------\n 2 files changed, 39 insertions(+), 37 deletions(-)\n\ndiff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt\nindex 50baa5d6bfb..51da7088a84 100644\n--- a/Documentation/config/sendemail.txt\n+++ b/Documentation/config/sendemail.txt\n@@ -18,17 +18,49 @@ sendemail..*::\n \tidentity is selected, through either the command-line or\n \t`sendemail.identity`.\n \n+sendemail.multiEdit::\n+\tIf true (default), a single editor instance will be spawned to edit\n+\tfiles you have to edit (patches when `--annotate` is used, and the\n+\tsummary when `--compose` is used). If false, files will be edited one\n+\tafter the other, spawning a new editor each time.\n+\n+sendemail.confirm::\n+\tSets the default for whether to confirm before sending. Must be\n+\tone of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`\n+\tin the linkgit:git-send-email[1] documentation for the meaning of these\n+\tvalues.\n+\n sendemail.aliasesFile::\n+\tTo avoid typing long email addresses, point this to one or more\n+\temail aliases files. You must also supply `sendemail.aliasFileType`.\n+\n sendemail.aliasFileType::\n+\tFormat of the file(s) specified in sendemail.aliasesFile. Must be\n+\tone of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.\n++\n+What an alias file in each format looks like can be found in\n+the documentation of the email program of the same name. The\n+differences and limitations from the standard formats are\n+described below:\n++\n+--\n+sendmail;;\n+*\tQuoted aliases and quoted addresses are not supported: lines that\n+\tcontain a `\"` symbol are ignored.\n+*\tRedirection to a file (`/path/name`) or pipe (`|command`) is not\n+\tsupported.\n+*\tFile inclusion (`:include: /path/name`) is not supported.\n+*\tWarnings are printed on the standard error output for any\n+\texplicitly unsupported constructs, and any other lines that are not\n+\trecognized by the parser.\n+--\n sendemail.annotate::\n sendemail.bcc::\n sendemail.cc::\n sendemail.ccCmd::\n sendemail.chainReplyTo::\n-sendemail.confirm::\n sendemail.envelopeSender::\n sendemail.from::\n-sendemail.multiEdit::\n sendemail.signedoffbycc::\n sendemail.smtpPass::\n sendemail.suppresscc::\n@@ -44,7 +76,9 @@ sendemail.thread::\n sendemail.transferEncoding::\n sendemail.validate::\n sendemail.xmailer::\n-\tSee linkgit:git-send-email[1] for description.\n+\tThese configuration variables all provide a default for\n+\tlinkgit:git-send-email[1] command-line options. See its\n+\tdocumentation for details.\n \n sendemail.signedoffcc (deprecated)::\n \tDeprecated alias for `sendemail.signedoffbycc`.\ndiff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\nindex 41cd8cb4247..3290043053a 100644\n--- a/Documentation/git-send-email.txt\n+++ b/Documentation/git-send-email.txt\n@@ -456,41 +456,9 @@ Information\n CONFIGURATION\n -------------\n \n-sendemail.aliasesFile::\n-\tTo avoid typing long email addresses, point this to one or more\n-\temail aliases files. You must also supply `sendemail.aliasFileType`.\n+include::includes/cmd-config-section-all.txt[]\n \n-sendemail.aliasFileType::\n-\tFormat of the file(s) specified in sendemail.aliasesFile. Must be\n-\tone of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.\n-+\n-What an alias file in each format looks like can be found in\n-the documentation of the email program of the same name. The\n-differences and limitations from the standard formats are\n-described below:\n-+\n---\n-sendmail;;\n-*\tQuoted aliases and quoted addresses are not supported: lines that\n-\tcontain a `\"` symbol are ignored.\n-*\tRedirection to a file (`/path/name`) or pipe (`|command`) is not\n-\tsupported.\n-*\tFile inclusion (`:include: /path/name`) is not supported.\n-*\tWarnings are printed on the standard error output for any\n-\texplicitly unsupported constructs, and any other lines that are not\n-\trecognized by the parser.\n---\n-\n-sendemail.multiEdit::\n-\tIf true (default), a single editor instance will be spawned to edit\n-\tfiles you have to edit (patches when `--annotate` is used, and the\n-\tsummary when `--compose` is used). If false, files will be edited one\n-\tafter the other, spawning a new editor each time.\n-\n-sendemail.confirm::\n-\tSets the default for whether to confirm before sending. Must be\n-\tone of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`\n-\tin the previous section for the meaning of these values.\n+include::config/sendemail.txt[]\n \n EXAMPLES\n --------\n-- \n2.37.1.1196.g8af3636bc64\n\n"},{"id":"460176","messageId":"patch-v2-5.9-1b6c8c75df7-20220729T081959Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v2-0.9-00000000000-20220729T081959Z-avarab@gmail.com","subject":"[PATCH v2 5/9] notes docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-29T08:25:51Z","receivedAt":"2022-07-29T08:26:45Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Let's also fix the \"git-notes(1)\" docs so that we link to\n\"git-config(1)\", not \"git-log(1)\" as a reference for the \"notes\" docs.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/notes.txt | 43 ++++++++++++++++-----------\n Documentation/git-log.txt | 16 ++--------\n Documentation/git-notes.txt | 54 ++--------------------------------\n 3 files changed, 32 insertions(+), 81 deletions(-)\n\ndiff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt\nindex aeef56d49ae..c7c4811734b 100644\n--- a/Documentation/config/notes.txt\n+++ b/Documentation/config/notes.txt\n@@ -3,6 +3,9 @@ notes.mergeStrategy::\n \tconflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or\n \t`cat_sort_uniq`. Defaults to `manual`. See \"NOTES MERGE STRATEGIES\"\n \tsection of linkgit:git-notes[1] for more information on each strategy.\n++\n+This setting can be overridden by passing the `--strategy` option to\n+linkgit:git-notes[1].\n \n notes..mergeStrategy::\n \tWhich merge strategy to choose when doing a notes merge into\n@@ -11,28 +14,35 @@ notes..mergeStrategy::\n \tlinkgit:git-notes[1] for more information on the available strategies.\n \n notes.displayRef::\n-\tThe (fully qualified) refname from which to show notes when\n-\tshowing commit messages. The value of this variable can be set\n-\tto a glob, in which case notes from all matching refs will be\n-\tshown. You may also specify this configuration variable\n-\tseveral times. A warning will be issued for refs that do not\n-\texist, but a glob that does not match any refs is silently\n-\tignored.\n+\tWhich ref (or refs, if a glob or specified more than once), in\n+\taddition to the default set by `core.notesRef` or\n+\t`GIT_NOTES_REF`, to read notes from when showing commit\n+\tmessages with the 'git log' family of commands.\n +\n This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`\n environment variable, which must be a colon separated list of refs or\n globs.\n +\n+A warning will be issued for refs that do not exist,\n+but a glob that does not match any refs is silently ignored.\n++\n+This setting can be disabled by the `--no-notes` option to the 'git\n+log' family of commands, or by the `--notes=` option accepted by\n+those commands.\n++\n The effective value of \"core.notesRef\" (possibly overridden by\n GIT_NOTES_REF) is also implicitly added to the list of refs to be\n displayed.\n \n notes.rewrite.::\n \tWhen rewriting commits with (currently `amend` or\n-\t`rebase`) and this variable is set to `true`, Git\n-\tautomatically copies your notes from the original to the\n-\trewritten commit. Defaults to `true`, but see\n-\t\"notes.rewriteRef\" below.\n+\t`rebase`), if this variable is `false`, git will not copy\n+\tnotes from the original to the rewritten commit. Defaults to\n+\t`true`. See also \"`notes.rewriteRef`\" below.\n++\n+This setting can be overridden with the `GIT_NOTES_REWRITE_REF`\n+environment variable, which must be a colon separated list of refs or\n+globs.\n \n notes.rewriteMode::\n \tWhen copying notes during a rewrite (see the\n@@ -46,14 +56,13 @@ environment variable.\n \n notes.rewriteRef::\n \tWhen copying notes during a rewrite, specifies the (fully\n-\tqualified) ref whose notes should be copied. The ref may be a\n-\tglob, in which case notes in all matching refs will be copied.\n-\tYou may also specify this configuration several times.\n+\tqualified) ref whose notes should be copied. May be a glob,\n+\tin which case notes in all matching refs will be copied. You\n+\tmay also specify this configuration several times.\n +\n Does not have a default value; you must configure this variable to\n enable note rewriting. Set it to `refs/notes/commits` to enable\n rewriting for the default commit notes.\n +\n-This setting can be overridden with the `GIT_NOTES_REWRITE_REF`\n-environment variable, which must be a colon separated list of refs or\n-globs.\n+Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.\n+See `notes.rewrite.` above for a further description of its format.\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 20e87cecf49..ed802bb8e12 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -227,19 +227,9 @@ log.showSignature::\n mailmap.*::\n \tSee linkgit:git-shortlog[1].\n \n-notes.displayRef::\n-\tWhich refs, in addition to the default set by `core.notesRef`\n-\tor `GIT_NOTES_REF`, to read notes from when showing commit\n-\tmessages with the `log` family of commands. See\n-\tlinkgit:git-notes[1].\n-+\n-May be an unabbreviated ref name or a glob and may be specified\n-multiple times. A warning will be issued for refs that do not exist,\n-but a glob that does not match any refs is silently ignored.\n-+\n-This setting can be disabled by the `--no-notes` option,\n-overridden by the `GIT_NOTES_DISPLAY_REF` environment variable,\n-and overridden by the `--notes=` option.\n+include::includes/cmd-config-section-rest.txt[]\n+\n+include::config/notes.txt[]\n \n GIT\n ---\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 0a4200674c4..68d547e2474 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -44,7 +44,7 @@ using the `--notes` option. Such notes are added as a patch commentary\n after a three dash separator line.\n \n To change which notes are shown by 'git log', see the\n-\"notes.displayRef\" configuration in linkgit:git-log[1].\n+\"notes.displayRef\" configuration in linkgit:git-config[1].\n \n See the \"notes.rewrite.\" configuration for a way to carry\n notes across commands that rewrite commits.\n@@ -316,57 +316,9 @@ core.notesRef::\n \tThis setting can be overridden through the environment and\n \tcommand line.\n \n-notes.mergeStrategy::\n-\tWhich merge strategy to choose by default when resolving notes\n-\tconflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or\n-\t`cat_sort_uniq`. Defaults to `manual`. See \"NOTES MERGE STRATEGIES\"\n-\tsection above for more information on each strategy.\n-+\n-This setting can be overridden by passing the `--strategy` option.\n-\n-notes..mergeStrategy::\n-\tWhich merge strategy to choose when doing a notes merge into\n-\trefs/notes/. This overrides the more general\n-\t\"notes.mergeStrategy\". See the \"NOTES MERGE STRATEGIES\" section above\n-\tfor more information on each available strategy.\n-\n-notes.displayRef::\n-\tWhich ref (or refs, if a glob or specified more than once), in\n-\taddition to the default set by `core.notesRef` or\n-\t`GIT_NOTES_REF`, to read notes from when showing commit\n-\tmessages with the 'git log' family of commands.\n-\tThis setting can be overridden on the command line or by the\n-\t`GIT_NOTES_DISPLAY_REF` environment variable.\n-\tSee linkgit:git-log[1].\n-\n-notes.rewrite.::\n-\tWhen rewriting commits with (currently `amend` or\n-\t`rebase`), if this variable is `false`, git will not copy\n-\tnotes from the original to the rewritten commit. Defaults to\n-\t`true`. See also \"`notes.rewriteRef`\" below.\n-+\n-This setting can be overridden by the `GIT_NOTES_REWRITE_REF`\n-environment variable.\n+include::includes/cmd-config-section-rest.txt[]\n \n-notes.rewriteMode::\n-\tWhen copying notes during a rewrite, what to do if the target\n-\tcommit already has a note. Must be one of `overwrite`,\n-\t`concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to\n-\t`concatenate`.\n-+\n-This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`\n-environment variable.\n-\n-notes.rewriteRef::\n-\tWhen copying notes during a rewrite, specifies the (fully\n-\tqualified) ref whose notes should be copied. May be a glob,\n-\tin which case notes in all matching refs will be copied. You\n-\tmay also specify this configuration several times.\n-+\n-Does not have a default value; you must configure this variable to\n-enable note rewriting.\n-+\n-Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.\n+include::config/notes.txt[]\n \n \n ENVIRONMENT\n-- \n2.37.1.1196.g8af3636bc64\n\n"},{"id":"460177","messageId":"patch-v2-6.9-b3a5ea46bb5-20220729T081959Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v2-0.9-00000000000-20220729T081959Z-avarab@gmail.com","subject":"[PATCH v2 6/9] difftool docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-29T08:25:52Z","receivedAt":"2022-07-29T08:26:47Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Include the \"config/difftool.txt\" file in \"git-difftool.txt\", and move\nthe relevant part of git-difftool(1) configuration from\n\"config/diff.txt\" to config/difftool.txt\".\n\nDoing this is slightly odd, as we usually discuss configuration in\nalphabetical order, but by doing it we're able to include the full set\nof configuration used by git-difftool(1) (and only that configuration)\nin its own documentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/diff.txt | 15 ---------------\n Documentation/config/difftool.txt | 28 +++++++++++++++++++++++++---\n Documentation/git-difftool.txt | 27 ++++-----------------------\n 3 files changed, 29 insertions(+), 41 deletions(-)\n\ndiff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt\nindex 32f84838ac1..35a7bf86d77 100644\n--- a/Documentation/config/diff.txt\n+++ b/Documentation/config/diff.txt\n@@ -178,21 +178,6 @@ diff..cachetextconv::\n \tSet this option to true to make the diff driver cache the text\n \tconversion outputs. See linkgit:gitattributes[5] for details.\n \n-diff.tool::\n-\tControls which diff tool is used by linkgit:git-difftool[1].\n-\tThis variable overrides the value configured in `merge.tool`.\n-\tThe list below shows the valid built-in values.\n-\tAny other value is treated as a custom diff tool and requires\n-\tthat a corresponding difftool..cmd variable is defined.\n-\n-diff.guitool::\n-\tControls which diff tool is used by linkgit:git-difftool[1] when\n-\tthe -g/--gui flag is specified. This variable overrides the value\n-\tconfigured in `merge.guitool`. The list below shows the valid\n-\tbuilt-in values. Any other value is treated as a custom diff tool\n-\tand requires that a corresponding difftool..cmd variable\n-\tis defined.\n-\n include::../mergetools-diff.txt[]\n \n diff.indentHeuristic::\ndiff --git a/Documentation/config/difftool.txt b/Documentation/config/difftool.txt\nindex 67625944804..a3f82112102 100644\n--- a/Documentation/config/difftool.txt\n+++ b/Documentation/config/difftool.txt\n@@ -1,6 +1,17 @@\n-difftool..path::\n-\tOverride the path for the given tool. This is useful in case\n-\tyour tool is not in the PATH.\n+diff.tool::\n+\tControls which diff tool is used by linkgit:git-difftool[1].\n+\tThis variable overrides the value configured in `merge.tool`.\n+\tThe list below shows the valid built-in values.\n+\tAny other value is treated as a custom diff tool and requires\n+\tthat a corresponding difftool..cmd variable is defined.\n+\n+diff.guitool::\n+\tControls which diff tool is used by linkgit:git-difftool[1] when\n+\tthe -g/--gui flag is specified. This variable overrides the value\n+\tconfigured in `merge.guitool`. The list below shows the valid\n+\tbuilt-in values. Any other value is treated as a custom diff tool\n+\tand requires that a corresponding difftool..cmd variable\n+\tis defined.\n \n difftool..cmd::\n \tSpecify the command to invoke the specified diff tool.\n@@ -9,6 +20,17 @@ difftool..cmd::\n \tfile containing the contents of the diff pre-image and 'REMOTE'\n \tis set to the name of the temporary file containing the contents\n \tof the diff post-image.\n++\n+See the `--tool=` option in linkgit:git-difftool[1] for more details.\n+\n+difftool..path::\n+\tOverride the path for the given tool. This is useful in case\n+\tyour tool is not in the PATH.\n+\n+difftool.trustExitCode::\n+\tExit difftool if the invoked diff tool returns a non-zero exit status.\n++\n+See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details.\n \n difftool.prompt::\n \tPrompt before each invocation of the diff tool.\ndiff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt\nindex 143b0c49d73..9d14c3c9f09 100644\n--- a/Documentation/git-difftool.txt\n+++ b/Documentation/git-difftool.txt\n@@ -113,33 +113,14 @@ instead. `--no-symlinks` is the default on Windows.\n \n See linkgit:git-diff[1] for the full list of supported options.\n \n-CONFIG VARIABLES\n-----------------\n+CONFIGURATION\n+-------------\n 'git difftool' falls back to 'git mergetool' config variables when the\n difftool equivalents have not been defined.\n \n-diff.tool::\n-\tThe default diff tool to use.\n+include::includes/cmd-config-section-rest.txt[]\n \n-diff.guitool::\n-\tThe default diff tool to use when `--gui` is specified.\n-\n-difftool..path::\n-\tOverride the path for the given tool. This is useful in case\n-\tyour tool is not in the PATH.\n-\n-difftool..cmd::\n-\tSpecify the command to invoke the specified diff tool.\n-+\n-See the `--tool=` option above for more details.\n-\n-difftool.prompt::\n-\tPrompt before each invocation of the diff tool.\n-\n-difftool.trustExitCode::\n-\tExit difftool if the invoked diff tool returns a non-zero exit status.\n-+\n-See the `--trust-exit-code` option above for more details.\n+include::config/difftool.txt[]\n \n SEE ALSO\n --------\n-- \n2.37.1.1196.g8af3636bc64\n\n"},{"id":"460178","messageId":"patch-v2-4.9-b9750ae43e1-20220729T081959Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v2-0.9-00000000000-20220729T081959Z-avarab@gmail.com","subject":"[PATCH v2 4/9] apply docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-29T08:25:50Z","receivedAt":"2022-07-29T08:26:50Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The wording is not identical to Documentation/config/apply.txt, but\nthat version is better.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-apply.txt | 10 +++-------\n 1 file changed, 3 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt\nindex b6d77f42068..1d478cbe9b5 100644\n--- a/Documentation/git-apply.txt\n+++ b/Documentation/git-apply.txt\n@@ -263,13 +263,9 @@ has no effect when `--index` or `--cached` is in use.\n CONFIGURATION\n -------------\n \n-apply.ignoreWhitespace::\n-\tSet to 'change' if you want changes in whitespace to be ignored by default.\n-\tSet to one of: no, none, never, false if you want changes in\n-\twhitespace to be significant.\n-apply.whitespace::\n-\tWhen no `--whitespace` flag is given from the command\n-\tline, this configuration item is used as the default.\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/apply.txt[]\n \n SUBMODULES\n ----------\n-- \n2.37.1.1196.g8af3636bc64\n\n"},{"id":"460179","messageId":"patch-v2-7.9-08d98767384-20220729T081959Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v2-0.9-00000000000-20220729T081959Z-avarab@gmail.com","subject":"[PATCH v2 7/9] log docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-29T08:25:53Z","receivedAt":"2022-07-29T08:26:52Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Signed-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/log.txt | 18 +++++++++++++-----\n Documentation/git-log.txt | 33 +++++----------------------------\n 2 files changed, 18 insertions(+), 33 deletions(-)\n\ndiff --git a/Documentation/config/log.txt b/Documentation/config/log.txt\nindex 456eb07800c..12ede8e31b8 100644\n--- a/Documentation/config/log.txt\n+++ b/Documentation/config/log.txt\n@@ -1,12 +1,11 @@\n-log.abbrevCommit::\n-\tIf true, makes linkgit:git-log[1], linkgit:git-show[1], and\n-\tlinkgit:git-whatchanged[1] assume `--abbrev-commit`. You may\n-\toverride this option with `--no-abbrev-commit`.\n-\n log.date::\n \tSet the default date-time mode for the 'log' command.\n \tSetting a value for log.date is similar to using 'git log''s\n \t`--date` option. See linkgit:git-log[1] for details.\n++\n+If the format is set to \"auto:foo\" and the pager is in use, format\n+\"foo\" will be the used for the date format. Otherwise \"default\" will\n+be used.\n \n log.decorate::\n \tPrint out the ref names of any commits that are shown by the log\n@@ -45,6 +44,11 @@ log.showRoot::\n \tTools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which\n \tnormally hide the root commit will now show it. True by default.\n \n+log.abbrevCommit::\n+\tIf true, makes linkgit:git-log[1], linkgit:git-show[1], and\n+\tlinkgit:git-whatchanged[1] assume `--abbrev-commit`. You may\n+\toverride this option with `--no-abbrev-commit`.\n+\n log.showSignature::\n \tIf true, makes linkgit:git-log[1], linkgit:git-show[1], and\n \tlinkgit:git-whatchanged[1] assume `--show-signature`.\n@@ -53,3 +57,7 @@ log.mailmap::\n \tIf true, makes linkgit:git-log[1], linkgit:git-show[1], and\n \tlinkgit:git-whatchanged[1] assume `--use-mailmap`, otherwise\n \tassume `--no-use-mailmap`. True by default.\n++\n+The behavior of `log.mailmap` is impacted by the setting of the more\n+general 'mailmap.*' configuration variables, i.e. `mailmap.file` and\n+`mailmap.blob`.\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex ed802bb8e12..69c4e13833d 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -42,6 +42,9 @@ OPTIONS\n \tshown. The option `--decorate` is short-hand for `--decorate=short`.\n \tDefault to configuration value of `log.decorate` if configured,\n \totherwise, `auto`.\n++\n+This output may be colored. See `color.ui` in linkgit:git-config[1]\n+and `color.decorate` there and in the \"CONFIGURATION\" section below.\n \n --decorate-refs=::\n --decorate-refs-exclude=::\n@@ -199,36 +202,10 @@ i18n.logOutputEncoding::\n \tDefaults to the value of `i18n.commitEncoding` if set, and UTF-8\n \totherwise.\n \n-log.date::\n-\tDefault format for human-readable dates. (Compare the\n-\t`--date` option.) Defaults to \"default\", which means to write\n-\tdates like `Sat May 8 19:35:34 2010 -0500`.\n-+\n-If the format is set to \"auto:foo\" and the pager is in use, format\n-\"foo\" will be the used for the date format. Otherwise \"default\" will\n-be used.\n-\n-log.follow::\n-\tIf `true`, `git log` will act as if the `--follow` option was used when\n-\ta single is given. This has the same limitations as `--follow`,\n-\ti.e. it cannot be used to follow multiple files and does not work well\n-\ton non-linear history.\n-\n-log.showRoot::\n-\tIf `false`, `git log` and related commands will not treat the\n-\tinitial commit as a big creation event. Any root commits in\n-\t`git log -p` output would be shown without a diff attached.\n-\tThe default is `true`.\n-\n-log.showSignature::\n-\tIf `true`, `git log` and related commands will act as if the\n-\t`--show-signature` option was passed to them.\n-\n-mailmap.*::\n-\tSee linkgit:git-shortlog[1].\n-\n include::includes/cmd-config-section-rest.txt[]\n \n+include::config/log.txt[]\n+\n include::config/notes.txt[]\n \n GIT\n-- \n2.37.1.1196.g8af3636bc64\n\n"},{"id":"460180","messageId":"patch-v2-8.9-5c379ab1476-20220729T081959Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v2-0.9-00000000000-20220729T081959Z-avarab@gmail.com","subject":"[PATCH v2 8/9] docs: add CONFIGURATION sections that map to a built-in","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-29T08:25:54Z","receivedAt":"2022-07-29T08:26:53Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add a CONFIGURATION section to the documentation of various built-ins,\nfor those cases where the relevant config/NAME.txt describes\nconfiguration that is only used by the relevant built-in documented in\ngit-NAME.txt. Subsequent commits will handle more complex cases.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-add.txt | 7 +++++++\n Documentation/git-am.txt | 7 +++++++\n Documentation/git-clean.txt | 7 +++++++\n Documentation/git-clone.txt | 7 +++++++\n Documentation/git-commit-graph.txt | 7 +++++++\n Documentation/git-commit.txt | 4 ++++\n Documentation/git-fast-import.txt | 7 +++++++\n Documentation/git-mailinfo.txt | 7 +++++++\n Documentation/git-maintenance.txt | 7 +++++++\n Documentation/git-push.txt | 7 +++++++\n Documentation/git-revert.txt | 7 +++++++\n Documentation/git-show-branch.txt | 7 +++++++\n Documentation/git-stash.txt | 7 +++++++\n 13 files changed, 88 insertions(+)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex 11eb70f16c7..36da8bf9b51 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -431,6 +431,13 @@ they will make the patch impossible to apply:\n * deleting context or removal lines\n * modifying the contents of context or removal lines\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/add.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-status[1]\ndiff --git a/Documentation/git-am.txt b/Documentation/git-am.txt\nindex 09107fb1067..7ccb46b660c 100644\n--- a/Documentation/git-am.txt\n+++ b/Documentation/git-am.txt\n@@ -261,6 +261,13 @@ This command can run `applypatch-msg`, `pre-applypatch`,\n and `post-applypatch` hooks. See linkgit:githooks[5] for more\n information.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/am.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-apply[1].\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex a7f309dff5a..91742633fa8 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -133,6 +133,13 @@ help::\n \n Show brief usage of interactive git-clean.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/clean.txt[]\n+\n SEE ALSO\n --------\n linkgit:gitignore[5]\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 632bd1348ea..b9ee8a87238 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -363,6 +363,13 @@ $ cd my-linux\n $ git clone --bare -l /home/proj/.git /pub/scm/proj.git\n ------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/clone.txt[]\n+\n \n GIT\n ---\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex e1f48c95b3c..5225f674546 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -142,6 +142,13 @@ $ git show-ref -s | git commit-graph write --stdin-commits\n $ git rev-parse HEAD | git commit-graph write --stdin-commits --append\n ------------------------------------------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/commitgraph.txt[]\n+\n \n GIT\n ---\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 6c60bf98f9f..225c6c9f2e5 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -557,6 +557,10 @@ The editor used to edit the commit log message will be chosen from the\n `VISUAL` environment variable, or the `EDITOR` environment variable (in that\n order). See linkgit:git-var[1] for details.\n \n+include::includes/cmd-config-section-rest.txt[]\n+\n+include::config/commit.txt[]\n+\n HOOKS\n -----\n This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`,\ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex 39cfa05b28b..8b5dd6add00 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -1564,6 +1564,13 @@ operator can use this facility to peek at the objects and refs from an\n import in progress, at the cost of some added running time and worse\n compression.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/fastimport.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-fast-export[1]\ndiff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt\nindex 3fcfd965fde..28060283c70 100644\n--- a/Documentation/git-mailinfo.txt\n+++ b/Documentation/git-mailinfo.txt\n@@ -115,6 +115,13 @@ If no such configuration option has been set, `warn` will be used.\n ::\n \tThe patch extracted from e-mail.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/mailinfo.txt[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt\nindex e56bad28c65..9c630efe19c 100644\n--- a/Documentation/git-maintenance.txt\n+++ b/Documentation/git-maintenance.txt\n@@ -397,6 +397,13 @@ If you want to customize the background tasks, please rename the tasks\n so future calls to `git maintenance (start|stop)` do not overwrite your\n custom tasks.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/maintenance.txt[]\n+\n \n GIT\n ---\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex 2f25aa3a291..def7657ef9c 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -692,6 +692,13 @@ a `git gc` command on the origin repository.\n \n include::transfer-data-leaks.txt[]\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/push.txt[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\nindex 8463fe9cf75..700f937f60a 100644\n--- a/Documentation/git-revert.txt\n+++ b/Documentation/git-revert.txt\n@@ -145,6 +145,13 @@ EXAMPLES\n \tchanges. The revert only modifies the working tree and the\n \tindex.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/revert.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-cherry-pick[1]\ndiff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt\nindex 5cc2fcefbab..e5ec6b467f9 100644\n--- a/Documentation/git-show-branch.txt\n+++ b/Documentation/git-show-branch.txt\n@@ -199,6 +199,13 @@ shows 10 reflog entries going back from the tip as of 1 hour ago.\n Without `--list`, the output also shows how these tips are\n topologically related with each other.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/showbranch.txt[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 6e15f475257..c5d70918283 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -382,6 +382,13 @@ grep commit | cut -d\\ -f3 |\n xargs git log --merges --no-walk --grep=WIP\n ----------------------------------------------------------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/stash.txt[]\n+\n \n SEE ALSO\n --------\n-- \n2.37.1.1196.g8af3636bc64\n\n"},{"id":"460181","messageId":"patch-v2-9.9-91689154926-20220729T081959Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v2-0.9-00000000000-20220729T081959Z-avarab@gmail.com","subject":"[PATCH v2 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-07-29T08:25:55Z","receivedAt":"2022-07-29T08:26:56Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add a CONFIGURATION section to the documentation of various built-ins,\nfor those cases where the relevant config/NAME.txt doesn't map only to\none git-NAME.txt. In particular:\n\n * config/blame.txt: used by git-{blame,annotate}.txt. Since the\n git-annotate(1) documentation refers to git-blame(1) don't add a\n \"CONFIGURATION\" section to git-annotate(1), only to git-blame(1)>\n\n * config/branch.txt: maps to both git-checkout.txt and\n git-switch.txt (but nothing else).\n\n * config/init.txt: should be included in git-init(1) and\n git-clone(1).\n\n * config/column.txt: We should ideally mention the relevant subset of\n this in git-{branch,clean,status,tag}.txt, but let's punt on it for\n now. We will when we eventually split these sort of files into\n e.g. config/column.txt and\n config/column/{branch,clean,status,tag}.txt, with the former\n including the latter set.\n\nThings that are being left out, and why:\n\n * config/remote.txt: let's not include this in\n git-{fetch,remote,push}.txt etc. for now, various options there\n change their behavior.\n\n * config/remotes.txt: As we're not including config/remote.txt for\n now, let's not include this one either.\n\n * config/credential.txt: let's not include this in\n git-credential.txt, it talks more generally about how the\n credential facility is used by various other commands, not that\n command in particular.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-blame.txt | 6 ++++++\n Documentation/git-branch.txt | 4 ++++\n Documentation/git-checkout.txt | 7 +++++++\n Documentation/git-clone.txt | 2 ++\n Documentation/git-column.txt | 7 +++++++\n Documentation/git-diff.txt | 7 +++++++\n Documentation/git-fetch.txt | 7 +++++++\n Documentation/git-switch.txt | 7 +++++++\n 8 files changed, 47 insertions(+)\n\ndiff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt\nindex d7a46cc6744..4400a17330b 100644\n--- a/Documentation/git-blame.txt\n+++ b/Documentation/git-blame.txt\n@@ -241,6 +241,12 @@ MAPPING AUTHORS\n \n See linkgit:gitmailmap[5].\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/blame.txt[]\n \n SEE ALSO\n --------\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex ae82378349d..12c5f84e3be 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -336,6 +336,10 @@ CONFIGURATION\n `--list` is used or implied. The default is to use a pager.\n See linkgit:git-config[1].\n \n+include::includes/cmd-config-section-rest.txt[]\n+\n+include::config/branch.txt[]\n+\n EXAMPLES\n --------\n \ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 9f37e22e130..4cb9d555b4b 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -600,6 +600,13 @@ $ edit frotz\n $ git add frotz\n ------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/checkout.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-switch[1],\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex b9ee8a87238..43955a3b504 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -368,6 +368,8 @@ CONFIGURATION\n \n include::includes/cmd-config-section-all.txt[]\n \n+include::config/init.txt[]\n+\n include::config/clone.txt[]\n \n \ndiff --git a/Documentation/git-column.txt b/Documentation/git-column.txt\nindex 6cea9ab4638..18431647a2d 100644\n--- a/Documentation/git-column.txt\n+++ b/Documentation/git-column.txt\n@@ -74,6 +74,13 @@ v2.4.3 v2.4.4 v2.4.5 v2.4.6 v2.4.7\n v2.4.8 v2.4.9\n ------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/column.txt[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 6236c75c9b8..85ae6d6d08a 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -213,6 +213,13 @@ $ git diff -R <2>\n rewrites (very expensive).\n <2> Output diff in reverse.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/diff.txt[]\n+\n SEE ALSO\n --------\n diff(1),\ndiff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt\nindex e9d364669af..63d9569e164 100644\n--- a/Documentation/git-fetch.txt\n+++ b/Documentation/git-fetch.txt\n@@ -285,6 +285,13 @@ linkgit:git-gc[1]).\n \n include::transfer-data-leaks.txt[]\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/fetch.txt[]\n+\n BUGS\n ----\n Using --recurse-submodules can only fetch new commits in submodules that are\ndiff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt\nindex bbcbdceb459..c60fc9c138b 100644\n--- a/Documentation/git-switch.txt\n+++ b/Documentation/git-switch.txt\n@@ -265,6 +265,13 @@ always create a new name for it (without switching away):\n $ git switch -c good-surprises\n ------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/checkout.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-checkout[1],\n-- \n2.37.1.1196.g8af3636bc64\n\n"},{"id":"460282","messageId":"xmqqv8rf4m3o.fsf@gitster.g","threadId":"58160","inReplyTo":"patch-v2-8.9-5c379ab1476-20220729T081959Z-avarab@gmail.com","subject":"Re: [PATCH v2 8/9] docs: add CONFIGURATION sections that map to a built-in","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-29T21:58:51Z","receivedAt":"2022-07-29T21:58:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Add a CONFIGURATION section to the documentation of various built-ins,\n> for those cases where the relevant config/NAME.txt describes\n> configuration that is only used by the relevant built-in documented in\n> git-NAME.txt. Subsequent commits will handle more complex cases.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/git-add.txt | 7 +++++++\n> Documentation/git-am.txt | 7 +++++++\n> Documentation/git-clean.txt | 7 +++++++\n> Documentation/git-clone.txt | 7 +++++++\n> Documentation/git-commit-graph.txt | 7 +++++++\n> Documentation/git-commit.txt | 4 ++++\n> Documentation/git-fast-import.txt | 7 +++++++\n> Documentation/git-mailinfo.txt | 7 +++++++\n> Documentation/git-maintenance.txt | 7 +++++++\n> Documentation/git-push.txt | 7 +++++++\n> Documentation/git-revert.txt | 7 +++++++\n> Documentation/git-show-branch.txt | 7 +++++++\n> Documentation/git-stash.txt | 7 +++++++\n> 13 files changed, 88 insertions(+)\n\nThis is one of the larger patch in the series, but everything here\nfollows the same pattern and is easy to see that they are correct.\n\n"},{"id":"460283","messageId":"xmqqlesb4lwh.fsf@gitster.g","threadId":"58160","inReplyTo":"patch-v2-9.9-91689154926-20220729T081959Z-avarab@gmail.com","subject":"Re: [PATCH v2 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-29T22:03:10Z","receivedAt":"2022-07-29T22:03:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n> Add a CONFIGURATION section to the documentation of various built-ins,\n> for those cases where the relevant config/NAME.txt doesn't map only to\n> one git-NAME.txt. In particular:\n>\n> * config/blame.txt: used by git-{blame,annotate}.txt. Since the\n> git-annotate(1) documentation refers to git-blame(1) don't add a\n> \"CONFIGURATION\" section to git-annotate(1), only to git-blame(1)>\n\ns/>/./ I think.\n\n> * config/branch.txt: maps to both git-checkout.txt and\n> git-switch.txt (but nothing else).\n\ns|/branch.txt|/checkout.txt|, I think.\n\n> * config/init.txt: should be included in git-init(1) and\n> git-clone(1).\n>\n> * config/column.txt: We should ideally mention the relevant subset of\n> this in git-{branch,clean,status,tag}.txt, but let's punt on it for\n> now. We will when we eventually split these sort of files into\n> e.g. config/column.txt and\n> config/column/{branch,clean,status,tag}.txt, with the former\n> including the latter set.\n>\n> Things that are being left out, and why:\n>\n> * config/remote.txt: let's not include this in\n> git-{fetch,remote,push}.txt etc. for now, various options there\n> change their behavior.\n\nLeaving some stuff out is fine, but I am not sure I understand\n(note: I didn't say \"I agree with\") the reasoning. I take \"various\noptions there\" to mean the configuration variables described in\nconfig/remote.txt file? If these variables affect the behaviour of\ncommands like fetch, remote, and push, isn't it more reason to\ninclude the description of them?\n\n"},{"id":"460302","messageId":"CAHd-oW5mD-H1kvuF9VEVb8KjaSkUSUpBH-WAkpCn6_Ci8o888w@mail.gmail.com","threadId":"58160","inReplyTo":"patch-v2-1.9-ef6fa5450e7-20220729T081959Z-avarab@gmail.com","subject":"Re: [PATCH v2 1/9] docs: add and use include template for config/* includes","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-07-30T13:29:10Z","receivedAt":"2022-07-30T13:32:06Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"On Fri, Jul 29, 2022 at 5:25 AM Ævar Arnfjörð Bjarmason\n wrote:\n>\n> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\n> index 3125473cc1d..6e5db8ef4c5 100644\n> --- a/Documentation/git-merge.txt\n> +++ b/Documentation/git-merge.txt\n> @@ -386,13 +386,16 @@ include::merge-strategies.txt[]\n>\n> CONFIGURATION\n> -------------\n> -include::config/merge.txt[]\n>\n> branch..mergeOptions::\n> Sets default options for merging into branch . The syntax and\n> supported options are the same as those of 'git merge', but option\n> values containing whitespace characters are currently not supported.\n>\n> +include::includes/cmd-config-section-rest.txt[]\n\nThis will say that \"everything above this line is unique to this\ndocumentation\", but `branch..mergeOptions` is in git-config(1)\nwith the same wording that it appears here (coming from\nconfig/branch.txt).\n\nNevertheless, I'm not sure if it is worth moving this definition to a\nseparate file, to be included by both git-merge(1) and\ngit-config(1)...\n\n> +\n> +include::config/merge.txt[]\n> +\n> SEE ALSO\n> --------\n> linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],\n"},{"id":"460303","messageId":"CAHd-oW4QO_Ron6csvgbxvH2to0sbBPD8aEJ0q=xTbRY7Q5nR8A@mail.gmail.com","threadId":"58160","inReplyTo":"patch-v2-2.9-5f07f87710c-20220729T081959Z-avarab@gmail.com","subject":"Re: [PATCH v2 2/9] grep docs: de-duplicate configuration sections","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-07-30T13:31:52Z","receivedAt":"2022-07-30T13:32:10Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason\n wrote:\n>\n> Include the \"config/grep.txt\" file in \"git-grep.txt\", instead of\n> repeating an almost identical description of the \"grep\" configuration\n> variables in two places.\n>\n> There is no loss of information here that isn't shown in the addition\n> to \"grep.txt\". This change was made by copying the contents of\n> \"git-grep.txt\"'s version over the \"grep.txt\" version. Aside from the\n> change \"grep.txt\" being made here the two were identical.\n>\n> This documentation started being copy/pasted around in\n> b22520a37c8 (grep: allow -E and -n to be turned on by default via\n> configuration, 2011-03-30). After that in e.g. 6453f7b3486 (grep: add\n> grep.fullName config variable, 2014-03-17) they started drifting\n> apart, with only grep.fullName being described in the command\n> documentation.\n>\n> In 434e6e753fe (config.txt: move grep.* to a separate file,\n> 2018-10-27) we gained the include, but didn't do this next step, let's\n> do it now.\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/config/grep.txt | 7 +++++--\n> Documentation/git-grep.txt | 29 ++---------------------------\n> 2 files changed, 7 insertions(+), 29 deletions(-)\n\nLGTM. (And more elegant than my previous solution :)\n"},{"id":"460304","messageId":"CAHd-oW4ZdGxOE4djUwDvt1zVZ2A-FC39FLi=k_7pREAN8AbyYQ@mail.gmail.com","threadId":"58160","inReplyTo":"patch-v2-3.9-8138dc54e3e-20220729T081959Z-avarab@gmail.com","subject":"Re: [PATCH v2 3/9] send-email docs: de-duplicate configuration sections","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-07-30T13:45:58Z","receivedAt":"2022-07-30T13:46:17Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason\n wrote:\n>\n> De-duplicate the discussion of \"send-email\" configuration, such that\n> the \"git-config(1)\" manual page becomes the source of truth, and\n> \"git-send-email(1)\" includes the relevant part.\n>\n> Most commands that suffered from such duplication had diverging text\n> discussing the same variables, but in this case some config was also\n> only discussed in one or the other.\n>\n> This is mostly a move-only change, the exception is a minor rewording\n> of changing wording like \"see above\" to \"see linkgit:git-config[1]\",\n> as well as a clarification about the big section of command-line\n> option tweaking config being discussed in git-send-email(1)'s main\n> docs.\n\nMakes sense. And this is easy to review with --color-moved.\n\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/config/sendemail.txt | 40 +++++++++++++++++++++++++++---\n> Documentation/git-send-email.txt | 36 ++-------------------------\n> 2 files changed, 39 insertions(+), 37 deletions(-)\n>\n> diff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt\n> index 50baa5d6bfb..51da7088a84 100644\n> --- a/Documentation/config/sendemail.txt\n> +++ b/Documentation/config/sendemail.txt\n> [...]\n> sendemail.annotate::\n> sendemail.bcc::\n> sendemail.cc::\n> sendemail.ccCmd::\n> sendemail.chainReplyTo::\n> -sendemail.confirm::\n> sendemail.envelopeSender::\n> sendemail.from::\n> -sendemail.multiEdit::\n> sendemail.signedoffbycc::\n> sendemail.smtpPass::\n> sendemail.suppresscc::\n> @@ -44,7 +76,9 @@ sendemail.thread::\n> sendemail.transferEncoding::\n> sendemail.validate::\n> sendemail.xmailer::\n> - See linkgit:git-send-email[1] for description.\n> + These configuration variables all provide a default for\n> + linkgit:git-send-email[1] command-line options. See its\n> + documentation for details.\n\nOk, I looked one by one and these are all indeed mentioned in the\ngit-send-email(1) cli option documentation.\n\nThe rest looks good too.\n"},{"id":"460305","messageId":"CAHd-oW5z07MTEg8OW4ftSJXG2F3Cu+WpctefZGOmMWsAM-nb7Q@mail.gmail.com","threadId":"58160","inReplyTo":"patch-v2-4.9-b9750ae43e1-20220729T081959Z-avarab@gmail.com","subject":"Re: [PATCH v2 4/9] apply docs: de-duplicate configuration sections","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-07-30T13:50:25Z","receivedAt":"2022-07-30T13:50:42Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason\n wrote:\n>\n> The wording is not identical to Documentation/config/apply.txt, but\n> that version is better.\n\nYeah, I agree. The only potential \"loss\" of information here is that\n\"apply.whitespace is the default when the cli arg is not used\". But\nthat is the default for all configurations anyways.\n"},{"id":"460306","messageId":"CAHd-oW7FHny98ZV5KOk2kHbN7TTGR_d1mm6F8g8S1wQjviKb2g@mail.gmail.com","threadId":"58160","inReplyTo":"patch-v2-6.9-b3a5ea46bb5-20220729T081959Z-avarab@gmail.com","subject":"Re: [PATCH v2 6/9] difftool docs: de-duplicate configuration sections","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-07-30T14:09:22Z","receivedAt":"2022-07-30T14:09:40Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason\n wrote:\n>\n> diff --git a/Documentation/config/difftool.txt b/Documentation/config/difftool.txt\n> index 67625944804..a3f82112102 100644\n> --- a/Documentation/config/difftool.txt\n> +++ b/Documentation/config/difftool.txt\n> @@ -1,6 +1,17 @@\n> -difftool..path::\n> - Override the path for the given tool. This is useful in case\n> - your tool is not in the PATH.\n> +diff.tool::\n> + Controls which diff tool is used by linkgit:git-difftool[1].\n> + This variable overrides the value configured in `merge.tool`.\n> + The list below shows the valid built-in values.\n> + Any other value is treated as a custom diff tool and requires\n> + that a corresponding difftool..cmd variable is defined.\n> +\n> +diff.guitool::\n> + Controls which diff tool is used by linkgit:git-difftool[1] when\n> + the -g/--gui flag is specified. This variable overrides the value\n> + configured in `merge.guitool`. The list below shows the valid\n> + built-in values. Any other value is treated as a custom diff tool\n> + and requires that a corresponding difftool..cmd variable\n> + is defined.\n\nAt first glance I thought it was a bit weird to have this diff.*\ndefinitions moved to difftool, but it makes sense since these are\nindeed related to difftool.\n\n> difftool..cmd::\n> Specify the command to invoke the specified diff tool.\n> @@ -9,6 +20,17 @@ difftool..cmd::\n> file containing the contents of the diff pre-image and 'REMOTE'\n> is set to the name of the temporary file containing the contents\n> of the diff post-image.\n> ++\n> +See the `--tool=` option in linkgit:git-difftool[1] for more details.\n> +\n\nOK, this comes from the removed part of Documentation/git-difftool.txt.\n\n> +difftool..path::\n> + Override the path for the given tool. This is useful in case\n> + your tool is not in the PATH.\n> +\n> +difftool.trustExitCode::\n> + Exit difftool if the invoked diff tool returns a non-zero exit status.\n> ++\n> +See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details.\n\nAnd so does this.\n"},{"id":"460308","messageId":"CAHd-oW4yABvvvifHe9WqZgQcErzYmiyXqZr4ssHx8ozN0w6raQ@mail.gmail.com","threadId":"58160","inReplyTo":"patch-v2-7.9-08d98767384-20220729T081959Z-avarab@gmail.com","subject":"Re: [PATCH v2 7/9] log docs: de-duplicate configuration sections","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-07-30T18:52:59Z","receivedAt":"2022-07-30T18:53:19Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason\n wrote:\n>\n> Signed-off-by: Ævar Arnfjörð Bjarmason \n> ---\n> Documentation/config/log.txt | 18 +++++++++++++-----\n> Documentation/git-log.txt | 33 +++++----------------------------\n> 2 files changed, 18 insertions(+), 33 deletions(-)\n>\n> diff --git a/Documentation/config/log.txt b/Documentation/config/log.txt\n> index 456eb07800c..12ede8e31b8 100644\n> --- a/Documentation/config/log.txt\n> +++ b/Documentation/config/log.txt\n> @@ -1,12 +1,11 @@\n> -log.abbrevCommit::\n> - If true, makes linkgit:git-log[1], linkgit:git-show[1], and\n> - linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may\n> - override this option with `--no-abbrev-commit`.\n> -\n\nWhy was this moved ....\n\n> log.date::\n> Set the default date-time mode for the 'log' command.\n> Setting a value for log.date is similar to using 'git log''s\n> `--date` option. See linkgit:git-log[1] for details.\n> ++\n> +If the format is set to \"auto:foo\" and the pager is in use, format\n> +\"foo\" will be the used for the date format. Otherwise \"default\" will\n> +be used.\n>\n> log.decorate::\n> Print out the ref names of any commits that are shown by the log\n> @@ -45,6 +44,11 @@ log.showRoot::\n> Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which\n> normally hide the root commit will now show it. True by default.\n>\n> +log.abbrevCommit::\n> + If true, makes linkgit:git-log[1], linkgit:git-show[1], and\n> + linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may\n> + override this option with `--no-abbrev-commit`.\n> +\n\n... down here?\n\n> log.showSignature::\n> If true, makes linkgit:git-log[1], linkgit:git-show[1], and\n> linkgit:git-whatchanged[1] assume `--show-signature`.\n> @@ -53,3 +57,7 @@ log.mailmap::\n> If true, makes linkgit:git-log[1], linkgit:git-show[1], and\n> linkgit:git-whatchanged[1] assume `--use-mailmap`, otherwise\n> assume `--no-use-mailmap`. True by default.\n> ++\n> +The behavior of `log.mailmap` is impacted by the setting of the more\n> +general 'mailmap.*' configuration variables, i.e. `mailmap.file` and\n> +`mailmap.blob`.\n\nGood.\n\n> diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\n> index ed802bb8e12..69c4e13833d 100644\n> --- a/Documentation/git-log.txt\n> +++ b/Documentation/git-log.txt\n> @@ -42,6 +42,9 @@ OPTIONS\n> shown. The option `--decorate` is short-hand for `--decorate=short`.\n> Default to configuration value of `log.decorate` if configured,\n> otherwise, `auto`.\n> ++\n> +This output may be colored. See `color.ui` in linkgit:git-config[1]\n> +and `color.decorate` there and in the \"CONFIGURATION\" section below.\n\nHmm, is this related to this change?\n\n> [...]\n> -log.showRoot::\n> - If `false`, `git log` and related commands will not treat the\n> - initial commit as a big creation event. Any root commits in\n> - `git log -p` output would be shown without a diff attached.\n> - The default is `true`.\n> -\n> -log.showSignature::\n> - If `true`, `git log` and related commands will act as if the\n> - `--show-signature` option was passed to them.\n\nThese two have a different wording on config/log.txt, but they are\narguably better presented there anyway.\n"},{"id":"460309","messageId":"CAHd-oW7PV=sAmfonMDnCCEQ9NF-fmpqYAYGRS6+AJRxfyExUgQ@mail.gmail.com","threadId":"58160","inReplyTo":"patch-v2-9.9-91689154926-20220729T081959Z-avarab@gmail.com","subject":"Re: [PATCH v2 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-07-30T19:08:05Z","receivedAt":"2022-07-30T19:08:23Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason\n wrote:\n>\n> Add a CONFIGURATION section to the documentation of various built-ins,\n> for those cases where the relevant config/NAME.txt doesn't map only to\n> one git-NAME.txt. In particular:\n>\n> * config/blame.txt: used by git-{blame,annotate}.txt. Since the\n> git-annotate(1) documentation refers to git-blame(1) don't add a\n> \"CONFIGURATION\" section to git-annotate(1), only to git-blame(1)>\n>\n> * config/branch.txt: maps to both git-checkout.txt and\n> git-switch.txt (but nothing else).\n>\n> * config/init.txt: should be included in git-init(1) and\n> git-clone(1).\n\nI think the inclusion at git-init(1) is missing in the diff below.\n"},{"id":"460311","messageId":"CAHd-oW7s6Hu24uTjCW9ROBbJkA5+7TCu32a4L_BXVLhcvw5kSw@mail.gmail.com","threadId":"58160","inReplyTo":"patch-v2-5.9-1b6c8c75df7-20220729T081959Z-avarab@gmail.com","subject":"Re: [PATCH v2 5/9] notes docs: de-duplicate configuration sections","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-07-30T20:02:34Z","receivedAt":"2022-07-30T20:02:52Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason\n wrote:\n>\n> diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt\n> index aeef56d49ae..c7c4811734b 100644\n> --- a/Documentation/config/notes.txt\n> +++ b/Documentation/config/notes.txt\n> [...]\n> notes.displayRef::\n> - The (fully qualified) refname from which to show notes when\n> - showing commit messages. The value of this variable can be set\n> - to a glob, in which case notes from all matching refs will be\n> - shown. You may also specify this configuration variable\n> - several times. A warning will be issued for refs that do not\n> - exist, but a glob that does not match any refs is silently\n> - ignored.\n> + Which ref (or refs, if a glob or specified more than once), in\n> + addition to the default set by `core.notesRef` or\n> + `GIT_NOTES_REF`, to read notes from when showing commit\n> + messages with the 'git log' family of commands.\n> +\n> This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`\n> environment variable, which must be a colon separated list of refs or\n> globs.\n> +\n> +A warning will be issued for refs that do not exist,\n> +but a glob that does not match any refs is silently ignored.\n> ++\n> +This setting can be disabled by the `--no-notes` option to the 'git\n> +log' family of commands, or by the `--notes=` option accepted by\n> +those commands.\n> ++\n> The effective value of \"core.notesRef\" (possibly overridden by\n> GIT_NOTES_REF) is also implicitly added to the list of refs to be\n> displayed.\n\nThis change is a bit complex since it agglutinates the definition of\nnotes.displayRef from three different places with different wordings\neach. Perhaps it would be helpful to acknowledge it in the commit\nmessage and/or justify the chosen parts?\n\n> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\n> index 0a4200674c4..68d547e2474 100644\n> --- a/Documentation/git-notes.txt\n> +++ b/Documentation/git-notes.txt\n> @@ -44,7 +44,7 @@ using the `--notes` option. Such notes are added as a patch commentary\n> after a three dash separator line.\n>\n> To change which notes are shown by 'git log', see the\n> -\"notes.displayRef\" configuration in linkgit:git-log[1].\n> +\"notes.displayRef\" configuration in linkgit:git-config[1].\n\nSince notes.displayRef now comes from config/notes.txt which will be\nincluded here, I think we could replace this reference to\ngit-config(1) with \"in the CONFIGURATION section below\".\n"},{"id":"460312","messageId":"CAHd-oW5VuqvMY55z-XsYUACWv+pmS6-AD7C0RG7BBq9XpshHuw@mail.gmail.com","threadId":"58160","inReplyTo":"cover-v2-0.9-00000000000-20220729T081959Z-avarab@gmail.com","subject":"Re: [PATCH v2 0/9] docs: de-duplicate sections, add more CONFIGURATION sections","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-07-30T20:05:50Z","receivedAt":"2022-07-30T20:06:08Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"On Fri, Jul 29, 2022 at 5:25 AM Ævar Arnfjörð Bjarmason\n wrote:\n>\n> This series is a follow-up to Matheus Tavares's v1[1] patches to\n> de-duplicate some of our configuration documentation, per [2] I'm\n> submitting this as a replacement series.\n\nThanks for submitting this version, which I very much appreciate. I\nleft some comments in the patches, but overall it is looking good to\nme.\n"},{"id":"460315","messageId":"xmqqpmhm1gbt.fsf@gitster.g","threadId":"58160","inReplyTo":"CAHd-oW7PV=sAmfonMDnCCEQ9NF-fmpqYAYGRS6+AJRxfyExUgQ@mail.gmail.com","subject":"Re: [PATCH v2 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-07-30T20:44:06Z","receivedAt":"2022-07-30T20:44:15Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matheus Tavares writes:\n\n> On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason\n> wrote:\n>>\n>> Add a CONFIGURATION section to the documentation of various built-ins,\n>> for those cases where the relevant config/NAME.txt doesn't map only to\n>> one git-NAME.txt. In particular:\n>>\n>> * config/blame.txt: used by git-{blame,annotate}.txt. Since the\n>> git-annotate(1) documentation refers to git-blame(1) don't add a\n>> \"CONFIGURATION\" section to git-annotate(1), only to git-blame(1)>\n>>\n>> * config/branch.txt: maps to both git-checkout.txt and\n>> git-switch.txt (but nothing else).\n>>\n>> * config/init.txt: should be included in git-init(1) and\n>> git-clone(1).\n>\n> I think the inclusion at git-init(1) is missing in the diff below.\n\nGood eyes. Thanks for carefully reviewing.\n"},{"id":"462258","messageId":"cover-v3-0.9-00000000000-20220831T083759Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v2-0.9-00000000000-20220729T081959Z-avarab@gmail.com","subject":"[PATCH v3 0/9] docs: de-duplicate sections, add more CONFIGURATION sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-31T08:41:31Z","receivedAt":"2022-08-31T08:41:58Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"This series:\n\n * De-duplicates and combines configuration discussion that was split\n or spread across Documentation/config/*.txt and\n Documentation/git-*.txt, moving it to Documentation/config/*.txt.\n\n * Includes that relevant Documentation/config/*.txt in the\n Documentation/git-*.txt files.\n\n * Introduces and uses included prose for those \"CONFIGURATION\"\n sections in various Documentation/git-*.txt files, informing the\n reader that what they see there is included from \"git-config(1)\".\n\nThis v3 attempts to address all the feedback on v2. I think this\nshould be good for merging down at this point. Sorry about the late\nre-roll.\n\nÆvar Arnfjörð Bjarmason (9):\n docs: add and use include template for config/* includes\n grep docs: de-duplicate configuration sections\n send-email docs: de-duplicate configuration sections\n apply docs: de-duplicate configuration sections\n notes docs: de-duplicate and combine configuration sections\n difftool docs: de-duplicate configuration sections\n log docs: de-duplicate configuration sections\n docs: add CONFIGURATION sections that map to a built-in\n docs: add CONFIGURATION sections that fuzzy map to built-ins\n\n Documentation/Makefile | 1 +\n Documentation/config/diff.txt | 15 -----\n Documentation/config/difftool.txt | 28 +++++++++-\n Documentation/config/grep.txt | 7 ++-\n Documentation/config/log.txt | 4 ++\n Documentation/config/notes.txt | 43 +++++++++------\n Documentation/config/sendemail.txt | 40 +++++++++++++-\n Documentation/git-add.txt | 7 +++\n Documentation/git-am.txt | 7 +++\n Documentation/git-apply.txt | 10 +---\n Documentation/git-blame.txt | 6 ++\n Documentation/git-branch.txt | 4 ++\n Documentation/git-checkout.txt | 7 +++\n Documentation/git-clean.txt | 7 +++\n Documentation/git-clone.txt | 9 +++\n Documentation/git-column.txt | 7 +++\n Documentation/git-commit-graph.txt | 7 +++\n Documentation/git-commit.txt | 4 ++\n Documentation/git-diff.txt | 7 +++\n Documentation/git-difftool.txt | 27 ++-------\n Documentation/git-fast-import.txt | 7 +++\n Documentation/git-fetch.txt | 7 +++\n Documentation/git-fsck.txt | 2 +\n Documentation/git-gc.txt | 3 +-\n Documentation/git-grep.txt | 29 +---------\n Documentation/git-imap-send.txt | 2 +\n Documentation/git-init.txt | 7 +++\n Documentation/git-log.txt | 46 ++--------------\n Documentation/git-mailinfo.txt | 7 +++\n Documentation/git-maintenance.txt | 7 +++\n Documentation/git-merge.txt | 5 +-\n Documentation/git-mergetool.txt | 3 +\n Documentation/git-notes.txt | 55 ++-----------------\n Documentation/git-push.txt | 7 +++\n Documentation/git-rebase.txt | 2 +\n Documentation/git-revert.txt | 7 +++\n Documentation/git-send-email.txt | 36 +-----------\n Documentation/git-show-branch.txt | 7 +++\n Documentation/git-stash.txt | 7 +++\n Documentation/git-switch.txt | 7 +++\n .../includes/cmd-config-section-all.txt | 3 +\n .../includes/cmd-config-section-rest.txt | 3 +\n 42 files changed, 280 insertions(+), 226 deletions(-)\n create mode 100644 Documentation/includes/cmd-config-section-all.txt\n create mode 100644 Documentation/includes/cmd-config-section-rest.txt\n\nRange-diff against v2:\n 1: ef6fa5450e7 ! 1: da21c19978c docs: add and use include template for config/* includes\n @@ Documentation/includes/cmd-config-section-all.txt (new)\n \n ## Documentation/includes/cmd-config-section-rest.txt (new) ##\n @@\n -+The discussion above this line is unique to this documentation, but\n -+everything below is included from section(s) in linkgit:git-config[1]\n -+aplicable to this command:\n ++Everything above this line in this section isn't included from the\n ++linkgit:git-config[1] documentation. The content that follows is the\n ++same as what's found there:\n 2: 5f07f87710c = 2: d16e927caa2 grep docs: de-duplicate configuration sections\n 3: 8138dc54e3e = 3: c36feb6f35a send-email docs: de-duplicate configuration sections\n 4: b9750ae43e1 = 4: 5707c9dd635 apply docs: de-duplicate configuration sections\n 5: 1b6c8c75df7 ! 5: 5b0ea00aa33 notes docs: de-duplicate configuration sections\n @@ Metadata\n Author: Ævar Arnfjörð Bjarmason \n \n ## Commit message ##\n - notes docs: de-duplicate configuration sections\n + notes docs: de-duplicate and combine configuration sections\n \n - Let's also fix the \"git-notes(1)\" docs so that we link to\n - \"git-config(1)\", not \"git-log(1)\" as a reference for the \"notes\" docs.\n + Combine the various \"notes\" configuration sections spread across\n + Documentation/config/notes.txt and Documentation/git-notes.txt to live\n + in the former, and to be included in the latter.\n +\n + We'll now forward link from \"git notes\" to the \"CONFIGURATION\" section\n + below, rather than to \"git-config(1)\" when discussing configuration\n + variables that are (also) discussed in that section.\n \n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n @@ Documentation/git-notes.txt: using the `--notes` option. Such notes are added as\n \n To change which notes are shown by 'git log', see the\n -\"notes.displayRef\" configuration in linkgit:git-log[1].\n -+\"notes.displayRef\" configuration in linkgit:git-config[1].\n ++\"notes.displayRef\" discussion in <>.\n \n See the \"notes.rewrite.\" configuration for a way to carry\n notes across commands that rewrite commits.\n +@@ Documentation/git-notes.txt: with 'git log', so if you use such notes, you'll probably need to write\n + some special-purpose tools to do something useful with them.\n + \n + \n ++[[CONFIGURATION]]\n + CONFIGURATION\n + -------------\n + \n @@ Documentation/git-notes.txt: core.notesRef::\n \tThis setting can be overridden through the environment and\n \tcommand line.\n 6: b3a5ea46bb5 = 6: c4c3fa14190 difftool docs: de-duplicate configuration sections\n 7: 08d98767384 ! 7: e07585ba085 log docs: de-duplicate configuration sections\n @@ Commit message\n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n ## Documentation/config/log.txt ##\n -@@\n --log.abbrevCommit::\n --\tIf true, makes linkgit:git-log[1], linkgit:git-show[1], and\n --\tlinkgit:git-whatchanged[1] assume `--abbrev-commit`. You may\n --\toverride this option with `--no-abbrev-commit`.\n --\n - log.date::\n +@@ Documentation/config/log.txt: log.date::\n \tSet the default date-time mode for the 'log' command.\n \tSetting a value for log.date is similar to using 'git log''s\n \t`--date` option. See linkgit:git-log[1] for details.\n @@ Documentation/config/log.txt\n \n log.decorate::\n \tPrint out the ref names of any commits that are shown by the log\n -@@ Documentation/config/log.txt: log.showRoot::\n - \tTools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which\n - \tnormally hide the root commit will now show it. True by default.\n - \n -+log.abbrevCommit::\n -+\tIf true, makes linkgit:git-log[1], linkgit:git-show[1], and\n -+\tlinkgit:git-whatchanged[1] assume `--abbrev-commit`. You may\n -+\toverride this option with `--no-abbrev-commit`.\n -+\n - log.showSignature::\n - \tIf true, makes linkgit:git-log[1], linkgit:git-show[1], and\n - \tlinkgit:git-whatchanged[1] assume `--show-signature`.\n -@@ Documentation/config/log.txt: log.mailmap::\n - \tIf true, makes linkgit:git-log[1], linkgit:git-show[1], and\n - \tlinkgit:git-whatchanged[1] assume `--use-mailmap`, otherwise\n - \tassume `--no-use-mailmap`. True by default.\n -++\n -+The behavior of `log.mailmap` is impacted by the setting of the more\n -+general 'mailmap.*' configuration variables, i.e. `mailmap.file` and\n -+`mailmap.blob`.\n \n ## Documentation/git-log.txt ##\n -@@ Documentation/git-log.txt: OPTIONS\n - \tshown. The option `--decorate` is short-hand for `--decorate=short`.\n - \tDefault to configuration value of `log.decorate` if configured,\n - \totherwise, `auto`.\n -++\n -+This output may be colored. See `color.ui` in linkgit:git-config[1]\n -+and `color.decorate` there and in the \"CONFIGURATION\" section below.\n - \n - --decorate-refs=::\n - --decorate-refs-exclude=::\n @@ Documentation/git-log.txt: i18n.logOutputEncoding::\n \tDefaults to the value of `i18n.commitEncoding` if set, and UTF-8\n \totherwise.\n 8: 5c379ab1476 ! 8: af912e9ca65 docs: add CONFIGURATION sections that map to a built-in\n @@ Documentation/git-commit-graph.txt: $ git show-ref -s | git commit-graph write -\n +include::config/commitgraph.txt[]\n +\n \n - GIT\n - ---\n + FILE FORMAT\n + -----------\n \n ## Documentation/git-commit.txt ##\n @@ Documentation/git-commit.txt: The editor used to edit the commit log message will be chosen from the\n @@ Documentation/git-fast-import.txt: operator can use this facility to peek at the\n --------\n linkgit:git-fast-export[1]\n \n + ## Documentation/git-init.txt ##\n +@@ Documentation/git-init.txt: $ git commit <3>\n + <2> Add all existing files to the index.\n + <3> Record the pristine state as the first commit in the history.\n + \n ++CONFIGURATION\n ++-------------\n ++\n ++include::includes/cmd-config-section-all.txt[]\n ++\n ++include::config/init.txt[]\n ++\n + GIT\n + ---\n + Part of the linkgit:git[1] suite\n +\n ## Documentation/git-mailinfo.txt ##\n @@ Documentation/git-mailinfo.txt: If no such configuration option has been set, `warn` will be used.\n ::\n 9: 91689154926 ! 9: 5ef36654bba docs: add CONFIGURATION sections that fuzzy map to built-ins\n @@ Commit message\n \n * config/blame.txt: used by git-{blame,annotate}.txt. Since the\n git-annotate(1) documentation refers to git-blame(1) don't add a\n - \"CONFIGURATION\" section to git-annotate(1), only to git-blame(1)>\n + \"CONFIGURATION\" section to git-annotate(1), only to git-blame(1).\n \n - * config/branch.txt: maps to both git-checkout.txt and\n + * config/checkout.txt: maps to both git-checkout.txt and\n git-switch.txt (but nothing else).\n \n * config/init.txt: should be included in git-init(1) and\n @@ Commit message\n \n Things that are being left out, and why:\n \n - * config/remote.txt: let's not include this in\n - git-{fetch,remote,push}.txt etc. for now, various options there\n - change their behavior.\n -\n - * config/remotes.txt: As we're not including config/remote.txt for\n - now, let's not include this one either.\n -\n - * config/credential.txt: let's not include this in\n - git-credential.txt, it talks more generally about how the\n - credential facility is used by various other commands, not that\n - command in particular.\n + * config/{remote,remotes,credential}.txt: Configuration that affects\n + how we talk to remote repositories is harder to untangle. We'll need\n + to include some of this in git-{fetch,remote,push,ls-remote}.txt\n + etc., but some of those only use a small subset of these\n + options. Let's leave this for now.\n \n Signed-off-by: Ævar Arnfjörð Bjarmason \n \n-- \n2.37.3.1406.g184357183a6\n\n"},{"id":"462259","messageId":"patch-v3-1.9-da21c19978c-20220831T083759Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v3-0.9-00000000000-20220831T083759Z-avarab@gmail.com","subject":"[PATCH v3 1/9] docs: add and use include template for config/* includes","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-31T08:41:32Z","receivedAt":"2022-08-31T08:41:58Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"In b6a8d09f6d8 (gc docs: include the \"gc.*\" section from \"config\" in\n\"gc\", 2019-04-07) the \"git gc\" documentation was made to include the\nconfig/gc.txt in its \"CONFIGURATION\" section. We do that in several\nother places, but \"git gc\" was the only one with a blurb above the\ninclude to orient the reader.\n\nWe don't want readers to carefully scrutinize \"git-config(1)\" and\n\"git-gc(1)\" looking for discrepancies, instead we should tell them\nthat the latter includes a part of the former.\n\nThis change formalizes that wording in two new templates to be\nincluded, one for the \"git gc\" case where the entire section is\nincluded from \"git-config(1)\", and another for when the inclusion of\n\"git-config(1)\" follows discussion unique to that documentation. In\norder to use that re-arrange the order of those being discussed in the\n\"git-merge(1)\" documentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-fsck.txt | 2 ++\n Documentation/git-gc.txt | 3 +--\n Documentation/git-imap-send.txt | 2 ++\n Documentation/git-merge.txt | 5 ++++-\n Documentation/git-mergetool.txt | 3 +++\n Documentation/git-rebase.txt | 2 ++\n Documentation/includes/cmd-config-section-all.txt | 3 +++\n Documentation/includes/cmd-config-section-rest.txt | 3 +++\n 9 files changed, 21 insertions(+), 3 deletions(-)\n create mode 100644 Documentation/includes/cmd-config-section-all.txt\n create mode 100644 Documentation/includes/cmd-config-section-rest.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex bd6b6fcb930..849af6da307 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -62,6 +62,7 @@ HOWTO_TXT += $(wildcard howto/*.txt)\n \n DOC_DEP_TXT += $(wildcard *.txt)\n DOC_DEP_TXT += $(wildcard config/*.txt)\n+DOC_DEP_TXT += $(wildcard includes/*.txt)\n \n ifdef MAN_FILTER\n MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))\ndiff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt\nindex 5088783dccb..29318ea957e 100644\n--- a/Documentation/git-fsck.txt\n+++ b/Documentation/git-fsck.txt\n@@ -107,6 +107,8 @@ care about this output and want to speed it up further.\n CONFIGURATION\n -------------\n \n+include::includes/cmd-config-section-all.txt[]\n+\n include::config/fsck.txt[]\n \n DISCUSSION\ndiff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt\nindex 0af7540a0c8..a65c9aa62d6 100644\n--- a/Documentation/git-gc.txt\n+++ b/Documentation/git-gc.txt\n@@ -110,8 +110,7 @@ users and their repositories.\n CONFIGURATION\n -------------\n \n-The below documentation is the same as what's found in\n-linkgit:git-config[1]:\n+include::includes/cmd-config-section-all.txt[]\n \n include::config/gc.txt[]\n \ndiff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt\nindex 63cf498ce9f..f7b18515141 100644\n--- a/Documentation/git-imap-send.txt\n+++ b/Documentation/git-imap-send.txt\n@@ -54,6 +54,8 @@ CONFIGURATION\n To use the tool, `imap.folder` and either `imap.tunnel` or `imap.host` must be set\n to appropriate values.\n \n+include::includes/cmd-config-section-rest.txt[]\n+\n include::config/imap.txt[]\n \n EXAMPLES\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex fee1dc2df28..2d6a1391c89 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -383,13 +383,16 @@ include::merge-strategies.txt[]\n \n CONFIGURATION\n -------------\n-include::config/merge.txt[]\n \n branch..mergeOptions::\n \tSets default options for merging into branch . The syntax and\n \tsupported options are the same as those of 'git merge', but option\n \tvalues containing whitespace characters are currently not supported.\n \n+include::includes/cmd-config-section-rest.txt[]\n+\n+include::config/merge.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],\ndiff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt\nindex f784027bc13..c44e205629b 100644\n--- a/Documentation/git-mergetool.txt\n+++ b/Documentation/git-mergetool.txt\n@@ -102,6 +102,9 @@ success of the resolution after the custom tool has exited.\n CONFIGURATION\n -------------\n :git-mergetool: 1\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n include::config/mergetool.txt[]\n \n TEMPORARY FILES\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex 1877942180e..9cb8931c7ac 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -1259,6 +1259,8 @@ merge cmake\n CONFIGURATION\n -------------\n \n+include::includes/cmd-config-section-all.txt[]\n+\n include::config/rebase.txt[]\n include::config/sequencer.txt[]\n \ndiff --git a/Documentation/includes/cmd-config-section-all.txt b/Documentation/includes/cmd-config-section-all.txt\nnew file mode 100644\nindex 00000000000..296a239f2ab\n--- /dev/null\n+++ b/Documentation/includes/cmd-config-section-all.txt\n@@ -0,0 +1,3 @@\n+Everything below this line in this section is selectively included\n+from the linkgit:git-config[1] documentation. The content is the same\n+as what's found there:\ndiff --git a/Documentation/includes/cmd-config-section-rest.txt b/Documentation/includes/cmd-config-section-rest.txt\nnew file mode 100644\nindex 00000000000..b1e7682c1dc\n--- /dev/null\n+++ b/Documentation/includes/cmd-config-section-rest.txt\n@@ -0,0 +1,3 @@\n+Everything above this line in this section isn't included from the\n+linkgit:git-config[1] documentation. The content that follows is the\n+same as what's found there:\n-- \n2.37.3.1406.g184357183a6\n\n"},{"id":"462260","messageId":"patch-v3-2.9-d16e927caa2-20220831T083759Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v3-0.9-00000000000-20220831T083759Z-avarab@gmail.com","subject":"[PATCH v3 2/9] grep docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-31T08:41:33Z","receivedAt":"2022-08-31T08:42:01Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Include the \"config/grep.txt\" file in \"git-grep.txt\", instead of\nrepeating an almost identical description of the \"grep\" configuration\nvariables in two places.\n\nThere is no loss of information here that isn't shown in the addition\nto \"grep.txt\". This change was made by copying the contents of\n\"git-grep.txt\"'s version over the \"grep.txt\" version. Aside from the\nchange \"grep.txt\" being made here the two were identical.\n\nThis documentation started being copy/pasted around in\nb22520a37c8 (grep: allow -E and -n to be turned on by default via\nconfiguration, 2011-03-30). After that in e.g. 6453f7b3486 (grep: add\ngrep.fullName config variable, 2014-03-17) they started drifting\napart, with only grep.fullName being described in the command\ndocumentation.\n\nIn 434e6e753fe (config.txt: move grep.* to a separate file,\n2018-10-27) we gained the include, but didn't do this next step, let's\ndo it now.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/grep.txt | 7 +++++--\n Documentation/git-grep.txt | 29 ++---------------------------\n 2 files changed, 7 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt\nindex 182edd813a5..e521f20390c 100644\n--- a/Documentation/config/grep.txt\n+++ b/Documentation/config/grep.txt\n@@ -17,8 +17,11 @@ grep.extendedRegexp::\n \tother than 'default'.\n \n grep.threads::\n-\tNumber of grep worker threads to use.\n-\tSee `grep.threads` in linkgit:git-grep[1] for more information.\n+\tNumber of grep worker threads to use. If unset (or set to 0), Git will\n+\tuse as many threads as the number of logical cores available.\n+\n+grep.fullName::\n+\tIf set to true, enable `--full-name` option by default.\n \n grep.fallbackToNoIndex::\n \tIf set to true, fall back to git grep --no-index if git grep\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 58d944bd578..dabdbe8471d 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -343,34 +343,9 @@ performance in this case, it might be desirable to use `--threads=1`.\n CONFIGURATION\n -------------\n \n-grep.lineNumber::\n-\tIf set to true, enable `-n` option by default.\n-\n-grep.column::\n-\tIf set to true, enable the `--column` option by default.\n-\n-grep.patternType::\n-\tSet the default matching behavior. Using a value of 'basic', 'extended',\n-\t'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,\n-\t`--fixed-strings`, or `--perl-regexp` option accordingly, while the\n-\tvalue 'default' will return to the default matching behavior.\n-\n-grep.extendedRegexp::\n-\tIf set to true, enable `--extended-regexp` option by default. This\n-\toption is ignored when the `grep.patternType` option is set to a value\n-\tother than 'default'.\n-\n-grep.threads::\n-\tNumber of grep worker threads to use. If unset (or set to 0), Git will\n-\tuse as many threads as the number of logical cores available.\n-\n-grep.fullName::\n-\tIf set to true, enable `--full-name` option by default.\n-\n-grep.fallbackToNoIndex::\n-\tIf set to true, fall back to git grep --no-index if git grep\n-\tis executed outside of a git repository. Defaults to false.\n+include::includes/cmd-config-section-all.txt[]\n \n+include::config/grep.txt[]\n \n GIT\n ---\n-- \n2.37.3.1406.g184357183a6\n\n"},{"id":"462261","messageId":"patch-v3-4.9-5707c9dd635-20220831T083759Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v3-0.9-00000000000-20220831T083759Z-avarab@gmail.com","subject":"[PATCH v3 4/9] apply docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-31T08:41:35Z","receivedAt":"2022-08-31T08:42:06Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The wording is not identical to Documentation/config/apply.txt, but\nthat version is better.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-apply.txt | 10 +++-------\n 1 file changed, 3 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt\nindex b6d77f42068..1d478cbe9b5 100644\n--- a/Documentation/git-apply.txt\n+++ b/Documentation/git-apply.txt\n@@ -263,13 +263,9 @@ has no effect when `--index` or `--cached` is in use.\n CONFIGURATION\n -------------\n \n-apply.ignoreWhitespace::\n-\tSet to 'change' if you want changes in whitespace to be ignored by default.\n-\tSet to one of: no, none, never, false if you want changes in\n-\twhitespace to be significant.\n-apply.whitespace::\n-\tWhen no `--whitespace` flag is given from the command\n-\tline, this configuration item is used as the default.\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/apply.txt[]\n \n SUBMODULES\n ----------\n-- \n2.37.3.1406.g184357183a6\n\n"},{"id":"462262","messageId":"patch-v3-3.9-c36feb6f35a-20220831T083759Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v3-0.9-00000000000-20220831T083759Z-avarab@gmail.com","subject":"[PATCH v3 3/9] send-email docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-31T08:41:34Z","receivedAt":"2022-08-31T08:42:09Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"De-duplicate the discussion of \"send-email\" configuration, such that\nthe \"git-config(1)\" manual page becomes the source of truth, and\n\"git-send-email(1)\" includes the relevant part.\n\nMost commands that suffered from such duplication had diverging text\ndiscussing the same variables, but in this case some config was also\nonly discussed in one or the other.\n\nThis is mostly a move-only change, the exception is a minor rewording\nof changing wording like \"see above\" to \"see linkgit:git-config[1]\",\nas well as a clarification about the big section of command-line\noption tweaking config being discussed in git-send-email(1)'s main\ndocs.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/sendemail.txt | 40 +++++++++++++++++++++++++++---\n Documentation/git-send-email.txt | 36 ++-------------------------\n 2 files changed, 39 insertions(+), 37 deletions(-)\n\ndiff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt\nindex 50baa5d6bfb..51da7088a84 100644\n--- a/Documentation/config/sendemail.txt\n+++ b/Documentation/config/sendemail.txt\n@@ -18,17 +18,49 @@ sendemail..*::\n \tidentity is selected, through either the command-line or\n \t`sendemail.identity`.\n \n+sendemail.multiEdit::\n+\tIf true (default), a single editor instance will be spawned to edit\n+\tfiles you have to edit (patches when `--annotate` is used, and the\n+\tsummary when `--compose` is used). If false, files will be edited one\n+\tafter the other, spawning a new editor each time.\n+\n+sendemail.confirm::\n+\tSets the default for whether to confirm before sending. Must be\n+\tone of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`\n+\tin the linkgit:git-send-email[1] documentation for the meaning of these\n+\tvalues.\n+\n sendemail.aliasesFile::\n+\tTo avoid typing long email addresses, point this to one or more\n+\temail aliases files. You must also supply `sendemail.aliasFileType`.\n+\n sendemail.aliasFileType::\n+\tFormat of the file(s) specified in sendemail.aliasesFile. Must be\n+\tone of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.\n++\n+What an alias file in each format looks like can be found in\n+the documentation of the email program of the same name. The\n+differences and limitations from the standard formats are\n+described below:\n++\n+--\n+sendmail;;\n+*\tQuoted aliases and quoted addresses are not supported: lines that\n+\tcontain a `\"` symbol are ignored.\n+*\tRedirection to a file (`/path/name`) or pipe (`|command`) is not\n+\tsupported.\n+*\tFile inclusion (`:include: /path/name`) is not supported.\n+*\tWarnings are printed on the standard error output for any\n+\texplicitly unsupported constructs, and any other lines that are not\n+\trecognized by the parser.\n+--\n sendemail.annotate::\n sendemail.bcc::\n sendemail.cc::\n sendemail.ccCmd::\n sendemail.chainReplyTo::\n-sendemail.confirm::\n sendemail.envelopeSender::\n sendemail.from::\n-sendemail.multiEdit::\n sendemail.signedoffbycc::\n sendemail.smtpPass::\n sendemail.suppresscc::\n@@ -44,7 +76,9 @@ sendemail.thread::\n sendemail.transferEncoding::\n sendemail.validate::\n sendemail.xmailer::\n-\tSee linkgit:git-send-email[1] for description.\n+\tThese configuration variables all provide a default for\n+\tlinkgit:git-send-email[1] command-line options. See its\n+\tdocumentation for details.\n \n sendemail.signedoffcc (deprecated)::\n \tDeprecated alias for `sendemail.signedoffbycc`.\ndiff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\nindex 41cd8cb4247..3290043053a 100644\n--- a/Documentation/git-send-email.txt\n+++ b/Documentation/git-send-email.txt\n@@ -456,41 +456,9 @@ Information\n CONFIGURATION\n -------------\n \n-sendemail.aliasesFile::\n-\tTo avoid typing long email addresses, point this to one or more\n-\temail aliases files. You must also supply `sendemail.aliasFileType`.\n+include::includes/cmd-config-section-all.txt[]\n \n-sendemail.aliasFileType::\n-\tFormat of the file(s) specified in sendemail.aliasesFile. Must be\n-\tone of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.\n-+\n-What an alias file in each format looks like can be found in\n-the documentation of the email program of the same name. The\n-differences and limitations from the standard formats are\n-described below:\n-+\n---\n-sendmail;;\n-*\tQuoted aliases and quoted addresses are not supported: lines that\n-\tcontain a `\"` symbol are ignored.\n-*\tRedirection to a file (`/path/name`) or pipe (`|command`) is not\n-\tsupported.\n-*\tFile inclusion (`:include: /path/name`) is not supported.\n-*\tWarnings are printed on the standard error output for any\n-\texplicitly unsupported constructs, and any other lines that are not\n-\trecognized by the parser.\n---\n-\n-sendemail.multiEdit::\n-\tIf true (default), a single editor instance will be spawned to edit\n-\tfiles you have to edit (patches when `--annotate` is used, and the\n-\tsummary when `--compose` is used). If false, files will be edited one\n-\tafter the other, spawning a new editor each time.\n-\n-sendemail.confirm::\n-\tSets the default for whether to confirm before sending. Must be\n-\tone of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`\n-\tin the previous section for the meaning of these values.\n+include::config/sendemail.txt[]\n \n EXAMPLES\n --------\n-- \n2.37.3.1406.g184357183a6\n\n"},{"id":"462263","messageId":"patch-v3-5.9-5b0ea00aa33-20220831T083759Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v3-0.9-00000000000-20220831T083759Z-avarab@gmail.com","subject":"[PATCH v3 5/9] notes docs: de-duplicate and combine configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-31T08:41:36Z","receivedAt":"2022-08-31T08:42:10Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Combine the various \"notes\" configuration sections spread across\nDocumentation/config/notes.txt and Documentation/git-notes.txt to live\nin the former, and to be included in the latter.\n\nWe'll now forward link from \"git notes\" to the \"CONFIGURATION\" section\nbelow, rather than to \"git-config(1)\" when discussing configuration\nvariables that are (also) discussed in that section.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/notes.txt | 43 +++++++++++++++-----------\n Documentation/git-log.txt | 16 ++--------\n Documentation/git-notes.txt | 55 +++-------------------------------\n 3 files changed, 33 insertions(+), 81 deletions(-)\n\ndiff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt\nindex aeef56d49ae..c7c4811734b 100644\n--- a/Documentation/config/notes.txt\n+++ b/Documentation/config/notes.txt\n@@ -3,6 +3,9 @@ notes.mergeStrategy::\n \tconflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or\n \t`cat_sort_uniq`. Defaults to `manual`. See \"NOTES MERGE STRATEGIES\"\n \tsection of linkgit:git-notes[1] for more information on each strategy.\n++\n+This setting can be overridden by passing the `--strategy` option to\n+linkgit:git-notes[1].\n \n notes..mergeStrategy::\n \tWhich merge strategy to choose when doing a notes merge into\n@@ -11,28 +14,35 @@ notes..mergeStrategy::\n \tlinkgit:git-notes[1] for more information on the available strategies.\n \n notes.displayRef::\n-\tThe (fully qualified) refname from which to show notes when\n-\tshowing commit messages. The value of this variable can be set\n-\tto a glob, in which case notes from all matching refs will be\n-\tshown. You may also specify this configuration variable\n-\tseveral times. A warning will be issued for refs that do not\n-\texist, but a glob that does not match any refs is silently\n-\tignored.\n+\tWhich ref (or refs, if a glob or specified more than once), in\n+\taddition to the default set by `core.notesRef` or\n+\t`GIT_NOTES_REF`, to read notes from when showing commit\n+\tmessages with the 'git log' family of commands.\n +\n This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`\n environment variable, which must be a colon separated list of refs or\n globs.\n +\n+A warning will be issued for refs that do not exist,\n+but a glob that does not match any refs is silently ignored.\n++\n+This setting can be disabled by the `--no-notes` option to the 'git\n+log' family of commands, or by the `--notes=` option accepted by\n+those commands.\n++\n The effective value of \"core.notesRef\" (possibly overridden by\n GIT_NOTES_REF) is also implicitly added to the list of refs to be\n displayed.\n \n notes.rewrite.::\n \tWhen rewriting commits with (currently `amend` or\n-\t`rebase`) and this variable is set to `true`, Git\n-\tautomatically copies your notes from the original to the\n-\trewritten commit. Defaults to `true`, but see\n-\t\"notes.rewriteRef\" below.\n+\t`rebase`), if this variable is `false`, git will not copy\n+\tnotes from the original to the rewritten commit. Defaults to\n+\t`true`. See also \"`notes.rewriteRef`\" below.\n++\n+This setting can be overridden with the `GIT_NOTES_REWRITE_REF`\n+environment variable, which must be a colon separated list of refs or\n+globs.\n \n notes.rewriteMode::\n \tWhen copying notes during a rewrite (see the\n@@ -46,14 +56,13 @@ environment variable.\n \n notes.rewriteRef::\n \tWhen copying notes during a rewrite, specifies the (fully\n-\tqualified) ref whose notes should be copied. The ref may be a\n-\tglob, in which case notes in all matching refs will be copied.\n-\tYou may also specify this configuration several times.\n+\tqualified) ref whose notes should be copied. May be a glob,\n+\tin which case notes in all matching refs will be copied. You\n+\tmay also specify this configuration several times.\n +\n Does not have a default value; you must configure this variable to\n enable note rewriting. Set it to `refs/notes/commits` to enable\n rewriting for the default commit notes.\n +\n-This setting can be overridden with the `GIT_NOTES_REWRITE_REF`\n-environment variable, which must be a colon separated list of refs or\n-globs.\n+Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.\n+See `notes.rewrite.` above for a further description of its format.\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex b1285aee3c2..410095e9a4f 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -237,19 +237,9 @@ log.showSignature::\n mailmap.*::\n \tSee linkgit:git-shortlog[1].\n \n-notes.displayRef::\n-\tWhich refs, in addition to the default set by `core.notesRef`\n-\tor `GIT_NOTES_REF`, to read notes from when showing commit\n-\tmessages with the `log` family of commands. See\n-\tlinkgit:git-notes[1].\n-+\n-May be an unabbreviated ref name or a glob and may be specified\n-multiple times. A warning will be issued for refs that do not exist,\n-but a glob that does not match any refs is silently ignored.\n-+\n-This setting can be disabled by the `--no-notes` option,\n-overridden by the `GIT_NOTES_DISPLAY_REF` environment variable,\n-and overridden by the `--notes=` option.\n+include::includes/cmd-config-section-rest.txt[]\n+\n+include::config/notes.txt[]\n \n GIT\n ---\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 0a4200674c4..efbc10f0f59 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -44,7 +44,7 @@ using the `--notes` option. Such notes are added as a patch commentary\n after a three dash separator line.\n \n To change which notes are shown by 'git log', see the\n-\"notes.displayRef\" configuration in linkgit:git-log[1].\n+\"notes.displayRef\" discussion in <>.\n \n See the \"notes.rewrite.\" configuration for a way to carry\n notes across commands that rewrite commits.\n@@ -307,6 +307,7 @@ with 'git log', so if you use such notes, you'll probably need to write\n some special-purpose tools to do something useful with them.\n \n \n+[[CONFIGURATION]]\n CONFIGURATION\n -------------\n \n@@ -316,57 +317,9 @@ core.notesRef::\n \tThis setting can be overridden through the environment and\n \tcommand line.\n \n-notes.mergeStrategy::\n-\tWhich merge strategy to choose by default when resolving notes\n-\tconflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or\n-\t`cat_sort_uniq`. Defaults to `manual`. See \"NOTES MERGE STRATEGIES\"\n-\tsection above for more information on each strategy.\n-+\n-This setting can be overridden by passing the `--strategy` option.\n-\n-notes..mergeStrategy::\n-\tWhich merge strategy to choose when doing a notes merge into\n-\trefs/notes/. This overrides the more general\n-\t\"notes.mergeStrategy\". See the \"NOTES MERGE STRATEGIES\" section above\n-\tfor more information on each available strategy.\n-\n-notes.displayRef::\n-\tWhich ref (or refs, if a glob or specified more than once), in\n-\taddition to the default set by `core.notesRef` or\n-\t`GIT_NOTES_REF`, to read notes from when showing commit\n-\tmessages with the 'git log' family of commands.\n-\tThis setting can be overridden on the command line or by the\n-\t`GIT_NOTES_DISPLAY_REF` environment variable.\n-\tSee linkgit:git-log[1].\n-\n-notes.rewrite.::\n-\tWhen rewriting commits with (currently `amend` or\n-\t`rebase`), if this variable is `false`, git will not copy\n-\tnotes from the original to the rewritten commit. Defaults to\n-\t`true`. See also \"`notes.rewriteRef`\" below.\n-+\n-This setting can be overridden by the `GIT_NOTES_REWRITE_REF`\n-environment variable.\n+include::includes/cmd-config-section-rest.txt[]\n \n-notes.rewriteMode::\n-\tWhen copying notes during a rewrite, what to do if the target\n-\tcommit already has a note. Must be one of `overwrite`,\n-\t`concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to\n-\t`concatenate`.\n-+\n-This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`\n-environment variable.\n-\n-notes.rewriteRef::\n-\tWhen copying notes during a rewrite, specifies the (fully\n-\tqualified) ref whose notes should be copied. May be a glob,\n-\tin which case notes in all matching refs will be copied. You\n-\tmay also specify this configuration several times.\n-+\n-Does not have a default value; you must configure this variable to\n-enable note rewriting.\n-+\n-Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.\n+include::config/notes.txt[]\n \n \n ENVIRONMENT\n-- \n2.37.3.1406.g184357183a6\n\n"},{"id":"462264","messageId":"patch-v3-6.9-c4c3fa14190-20220831T083759Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v3-0.9-00000000000-20220831T083759Z-avarab@gmail.com","subject":"[PATCH v3 6/9] difftool docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-31T08:41:37Z","receivedAt":"2022-08-31T08:42:13Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Include the \"config/difftool.txt\" file in \"git-difftool.txt\", and move\nthe relevant part of git-difftool(1) configuration from\n\"config/diff.txt\" to config/difftool.txt\".\n\nDoing this is slightly odd, as we usually discuss configuration in\nalphabetical order, but by doing it we're able to include the full set\nof configuration used by git-difftool(1) (and only that configuration)\nin its own documentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/diff.txt | 15 ---------------\n Documentation/config/difftool.txt | 28 +++++++++++++++++++++++++---\n Documentation/git-difftool.txt | 27 ++++-----------------------\n 3 files changed, 29 insertions(+), 41 deletions(-)\n\ndiff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt\nindex 32f84838ac1..35a7bf86d77 100644\n--- a/Documentation/config/diff.txt\n+++ b/Documentation/config/diff.txt\n@@ -178,21 +178,6 @@ diff..cachetextconv::\n \tSet this option to true to make the diff driver cache the text\n \tconversion outputs. See linkgit:gitattributes[5] for details.\n \n-diff.tool::\n-\tControls which diff tool is used by linkgit:git-difftool[1].\n-\tThis variable overrides the value configured in `merge.tool`.\n-\tThe list below shows the valid built-in values.\n-\tAny other value is treated as a custom diff tool and requires\n-\tthat a corresponding difftool..cmd variable is defined.\n-\n-diff.guitool::\n-\tControls which diff tool is used by linkgit:git-difftool[1] when\n-\tthe -g/--gui flag is specified. This variable overrides the value\n-\tconfigured in `merge.guitool`. The list below shows the valid\n-\tbuilt-in values. Any other value is treated as a custom diff tool\n-\tand requires that a corresponding difftool..cmd variable\n-\tis defined.\n-\n include::../mergetools-diff.txt[]\n \n diff.indentHeuristic::\ndiff --git a/Documentation/config/difftool.txt b/Documentation/config/difftool.txt\nindex 67625944804..a3f82112102 100644\n--- a/Documentation/config/difftool.txt\n+++ b/Documentation/config/difftool.txt\n@@ -1,6 +1,17 @@\n-difftool..path::\n-\tOverride the path for the given tool. This is useful in case\n-\tyour tool is not in the PATH.\n+diff.tool::\n+\tControls which diff tool is used by linkgit:git-difftool[1].\n+\tThis variable overrides the value configured in `merge.tool`.\n+\tThe list below shows the valid built-in values.\n+\tAny other value is treated as a custom diff tool and requires\n+\tthat a corresponding difftool..cmd variable is defined.\n+\n+diff.guitool::\n+\tControls which diff tool is used by linkgit:git-difftool[1] when\n+\tthe -g/--gui flag is specified. This variable overrides the value\n+\tconfigured in `merge.guitool`. The list below shows the valid\n+\tbuilt-in values. Any other value is treated as a custom diff tool\n+\tand requires that a corresponding difftool..cmd variable\n+\tis defined.\n \n difftool..cmd::\n \tSpecify the command to invoke the specified diff tool.\n@@ -9,6 +20,17 @@ difftool..cmd::\n \tfile containing the contents of the diff pre-image and 'REMOTE'\n \tis set to the name of the temporary file containing the contents\n \tof the diff post-image.\n++\n+See the `--tool=` option in linkgit:git-difftool[1] for more details.\n+\n+difftool..path::\n+\tOverride the path for the given tool. This is useful in case\n+\tyour tool is not in the PATH.\n+\n+difftool.trustExitCode::\n+\tExit difftool if the invoked diff tool returns a non-zero exit status.\n++\n+See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details.\n \n difftool.prompt::\n \tPrompt before each invocation of the diff tool.\ndiff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt\nindex 143b0c49d73..9d14c3c9f09 100644\n--- a/Documentation/git-difftool.txt\n+++ b/Documentation/git-difftool.txt\n@@ -113,33 +113,14 @@ instead. `--no-symlinks` is the default on Windows.\n \n See linkgit:git-diff[1] for the full list of supported options.\n \n-CONFIG VARIABLES\n-----------------\n+CONFIGURATION\n+-------------\n 'git difftool' falls back to 'git mergetool' config variables when the\n difftool equivalents have not been defined.\n \n-diff.tool::\n-\tThe default diff tool to use.\n+include::includes/cmd-config-section-rest.txt[]\n \n-diff.guitool::\n-\tThe default diff tool to use when `--gui` is specified.\n-\n-difftool..path::\n-\tOverride the path for the given tool. This is useful in case\n-\tyour tool is not in the PATH.\n-\n-difftool..cmd::\n-\tSpecify the command to invoke the specified diff tool.\n-+\n-See the `--tool=` option above for more details.\n-\n-difftool.prompt::\n-\tPrompt before each invocation of the diff tool.\n-\n-difftool.trustExitCode::\n-\tExit difftool if the invoked diff tool returns a non-zero exit status.\n-+\n-See the `--trust-exit-code` option above for more details.\n+include::config/difftool.txt[]\n \n SEE ALSO\n --------\n-- \n2.37.3.1406.g184357183a6\n\n"},{"id":"462265","messageId":"patch-v3-7.9-e07585ba085-20220831T083759Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v3-0.9-00000000000-20220831T083759Z-avarab@gmail.com","subject":"[PATCH v3 7/9] log docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-31T08:41:38Z","receivedAt":"2022-08-31T08:42:14Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Signed-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/log.txt | 4 ++++\n Documentation/git-log.txt | 30 ++----------------------------\n 2 files changed, 6 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/config/log.txt b/Documentation/config/log.txt\nindex 5250ba45fb4..bc63bc3939c 100644\n--- a/Documentation/config/log.txt\n+++ b/Documentation/config/log.txt\n@@ -7,6 +7,10 @@ log.date::\n \tSet the default date-time mode for the 'log' command.\n \tSetting a value for log.date is similar to using 'git log''s\n \t`--date` option. See linkgit:git-log[1] for details.\n++\n+If the format is set to \"auto:foo\" and the pager is in use, format\n+\"foo\" will be the used for the date format. Otherwise \"default\" will\n+be used.\n \n log.decorate::\n \tPrint out the ref names of any commits that are shown by the log\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 410095e9a4f..2a66cf88807 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -209,36 +209,10 @@ i18n.logOutputEncoding::\n \tDefaults to the value of `i18n.commitEncoding` if set, and UTF-8\n \totherwise.\n \n-log.date::\n-\tDefault format for human-readable dates. (Compare the\n-\t`--date` option.) Defaults to \"default\", which means to write\n-\tdates like `Sat May 8 19:35:34 2010 -0500`.\n-+\n-If the format is set to \"auto:foo\" and the pager is in use, format\n-\"foo\" will be the used for the date format. Otherwise \"default\" will\n-be used.\n-\n-log.follow::\n-\tIf `true`, `git log` will act as if the `--follow` option was used when\n-\ta single is given. This has the same limitations as `--follow`,\n-\ti.e. it cannot be used to follow multiple files and does not work well\n-\ton non-linear history.\n-\n-log.showRoot::\n-\tIf `false`, `git log` and related commands will not treat the\n-\tinitial commit as a big creation event. Any root commits in\n-\t`git log -p` output would be shown without a diff attached.\n-\tThe default is `true`.\n-\n-log.showSignature::\n-\tIf `true`, `git log` and related commands will act as if the\n-\t`--show-signature` option was passed to them.\n-\n-mailmap.*::\n-\tSee linkgit:git-shortlog[1].\n-\n include::includes/cmd-config-section-rest.txt[]\n \n+include::config/log.txt[]\n+\n include::config/notes.txt[]\n \n GIT\n-- \n2.37.3.1406.g184357183a6\n\n"},{"id":"462266","messageId":"patch-v3-8.9-af912e9ca65-20220831T083759Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v3-0.9-00000000000-20220831T083759Z-avarab@gmail.com","subject":"[PATCH v3 8/9] docs: add CONFIGURATION sections that map to a built-in","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-31T08:41:39Z","receivedAt":"2022-08-31T08:42:16Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add a CONFIGURATION section to the documentation of various built-ins,\nfor those cases where the relevant config/NAME.txt describes\nconfiguration that is only used by the relevant built-in documented in\ngit-NAME.txt. Subsequent commits will handle more complex cases.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-add.txt | 7 +++++++\n Documentation/git-am.txt | 7 +++++++\n Documentation/git-clean.txt | 7 +++++++\n Documentation/git-clone.txt | 7 +++++++\n Documentation/git-commit-graph.txt | 7 +++++++\n Documentation/git-commit.txt | 4 ++++\n Documentation/git-fast-import.txt | 7 +++++++\n Documentation/git-init.txt | 7 +++++++\n Documentation/git-mailinfo.txt | 7 +++++++\n Documentation/git-maintenance.txt | 7 +++++++\n Documentation/git-push.txt | 7 +++++++\n Documentation/git-revert.txt | 7 +++++++\n Documentation/git-show-branch.txt | 7 +++++++\n Documentation/git-stash.txt | 7 +++++++\n 14 files changed, 95 insertions(+)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex 9b37f356542..a030d33c6e7 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -433,6 +433,13 @@ they will make the patch impossible to apply:\n * deleting context or removal lines\n * modifying the contents of context or removal lines\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/add.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-status[1]\ndiff --git a/Documentation/git-am.txt b/Documentation/git-am.txt\nindex 320da6c4f76..326276e51ce 100644\n--- a/Documentation/git-am.txt\n+++ b/Documentation/git-am.txt\n@@ -258,6 +258,13 @@ This command can run `applypatch-msg`, `pre-applypatch`,\n and `post-applypatch` hooks. See linkgit:githooks[5] for more\n information.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/am.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-apply[1].\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex a7f309dff5a..91742633fa8 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -133,6 +133,13 @@ help::\n \n Show brief usage of interactive git-clean.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/clean.txt[]\n+\n SEE ALSO\n --------\n linkgit:gitignore[5]\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 632bd1348ea..b9ee8a87238 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -363,6 +363,13 @@ $ cd my-linux\n $ git clone --bare -l /home/proj/.git /pub/scm/proj.git\n ------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/clone.txt[]\n+\n \n GIT\n ---\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex 047decdb65b..36fe56c2c71 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -142,6 +142,13 @@ $ git show-ref -s | git commit-graph write --stdin-commits\n $ git rev-parse HEAD | git commit-graph write --stdin-commits --append\n ------------------------------------------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/commitgraph.txt[]\n+\n \n FILE FORMAT\n -----------\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 6c60bf98f9f..225c6c9f2e5 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -557,6 +557,10 @@ The editor used to edit the commit log message will be chosen from the\n `VISUAL` environment variable, or the `EDITOR` environment variable (in that\n order). See linkgit:git-var[1] for details.\n \n+include::includes/cmd-config-section-rest.txt[]\n+\n+include::config/commit.txt[]\n+\n HOOKS\n -----\n This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`,\ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex 39cfa05b28b..8b5dd6add00 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -1564,6 +1564,13 @@ operator can use this facility to peek at the objects and refs from an\n import in progress, at the cost of some added running time and worse\n compression.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/fastimport.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-fast-export[1]\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex ad921fe782e..160dea1372c 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -169,6 +169,13 @@ $ git commit <3>\n <2> Add all existing files to the index.\n <3> Record the pristine state as the first commit in the history.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/init.txt[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt\nindex 3fcfd965fde..28060283c70 100644\n--- a/Documentation/git-mailinfo.txt\n+++ b/Documentation/git-mailinfo.txt\n@@ -115,6 +115,13 @@ If no such configuration option has been set, `warn` will be used.\n ::\n \tThe patch extracted from e-mail.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/mailinfo.txt[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt\nindex e56bad28c65..9c630efe19c 100644\n--- a/Documentation/git-maintenance.txt\n+++ b/Documentation/git-maintenance.txt\n@@ -397,6 +397,13 @@ If you want to customize the background tasks, please rename the tasks\n so future calls to `git maintenance (start|stop)` do not overwrite your\n custom tasks.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/maintenance.txt[]\n+\n \n GIT\n ---\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex 2f25aa3a291..def7657ef9c 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -692,6 +692,13 @@ a `git gc` command on the origin repository.\n \n include::transfer-data-leaks.txt[]\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/push.txt[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\nindex 0105a54c1a5..5016755efb6 100644\n--- a/Documentation/git-revert.txt\n+++ b/Documentation/git-revert.txt\n@@ -142,6 +142,13 @@ EXAMPLES\n \tchanges. The revert only modifies the working tree and the\n \tindex.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/revert.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-cherry-pick[1]\ndiff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt\nindex 5cc2fcefbab..e5ec6b467f9 100644\n--- a/Documentation/git-show-branch.txt\n+++ b/Documentation/git-show-branch.txt\n@@ -199,6 +199,13 @@ shows 10 reflog entries going back from the tip as of 1 hour ago.\n Without `--list`, the output also shows how these tips are\n topologically related with each other.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/showbranch.txt[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 6e15f475257..c5d70918283 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -382,6 +382,13 @@ grep commit | cut -d\\ -f3 |\n xargs git log --merges --no-walk --grep=WIP\n ----------------------------------------------------------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/stash.txt[]\n+\n \n SEE ALSO\n --------\n-- \n2.37.3.1406.g184357183a6\n\n"},{"id":"462267","messageId":"patch-v3-9.9-5ef36654bba-20220831T083759Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v3-0.9-00000000000-20220831T083759Z-avarab@gmail.com","subject":"[PATCH v3 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-08-31T08:41:40Z","receivedAt":"2022-08-31T08:42:37Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add a CONFIGURATION section to the documentation of various built-ins,\nfor those cases where the relevant config/NAME.txt doesn't map only to\none git-NAME.txt. In particular:\n\n * config/blame.txt: used by git-{blame,annotate}.txt. Since the\n git-annotate(1) documentation refers to git-blame(1) don't add a\n \"CONFIGURATION\" section to git-annotate(1), only to git-blame(1).\n\n * config/checkout.txt: maps to both git-checkout.txt and\n git-switch.txt (but nothing else).\n\n * config/init.txt: should be included in git-init(1) and\n git-clone(1).\n\n * config/column.txt: We should ideally mention the relevant subset of\n this in git-{branch,clean,status,tag}.txt, but let's punt on it for\n now. We will when we eventually split these sort of files into\n e.g. config/column.txt and\n config/column/{branch,clean,status,tag}.txt, with the former\n including the latter set.\n\nThings that are being left out, and why:\n\n * config/{remote,remotes,credential}.txt: Configuration that affects\n how we talk to remote repositories is harder to untangle. We'll need\n to include some of this in git-{fetch,remote,push,ls-remote}.txt\n etc., but some of those only use a small subset of these\n options. Let's leave this for now.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-blame.txt | 6 ++++++\n Documentation/git-branch.txt | 4 ++++\n Documentation/git-checkout.txt | 7 +++++++\n Documentation/git-clone.txt | 2 ++\n Documentation/git-column.txt | 7 +++++++\n Documentation/git-diff.txt | 7 +++++++\n Documentation/git-fetch.txt | 7 +++++++\n Documentation/git-switch.txt | 7 +++++++\n 8 files changed, 47 insertions(+)\n\ndiff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt\nindex d7a46cc6744..4400a17330b 100644\n--- a/Documentation/git-blame.txt\n+++ b/Documentation/git-blame.txt\n@@ -241,6 +241,12 @@ MAPPING AUTHORS\n \n See linkgit:gitmailmap[5].\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/blame.txt[]\n \n SEE ALSO\n --------\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex ae82378349d..12c5f84e3be 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -336,6 +336,10 @@ CONFIGURATION\n `--list` is used or implied. The default is to use a pager.\n See linkgit:git-config[1].\n \n+include::includes/cmd-config-section-rest.txt[]\n+\n+include::config/branch.txt[]\n+\n EXAMPLES\n --------\n \ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 9f37e22e130..4cb9d555b4b 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -600,6 +600,13 @@ $ edit frotz\n $ git add frotz\n ------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/checkout.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-switch[1],\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex b9ee8a87238..43955a3b504 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -368,6 +368,8 @@ CONFIGURATION\n \n include::includes/cmd-config-section-all.txt[]\n \n+include::config/init.txt[]\n+\n include::config/clone.txt[]\n \n \ndiff --git a/Documentation/git-column.txt b/Documentation/git-column.txt\nindex 6cea9ab4638..18431647a2d 100644\n--- a/Documentation/git-column.txt\n+++ b/Documentation/git-column.txt\n@@ -74,6 +74,13 @@ v2.4.3 v2.4.4 v2.4.5 v2.4.6 v2.4.7\n v2.4.8 v2.4.9\n ------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/column.txt[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 6236c75c9b8..85ae6d6d08a 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -213,6 +213,13 @@ $ git diff -R <2>\n rewrites (very expensive).\n <2> Output diff in reverse.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/diff.txt[]\n+\n SEE ALSO\n --------\n diff(1),\ndiff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt\nindex e9d364669af..63d9569e164 100644\n--- a/Documentation/git-fetch.txt\n+++ b/Documentation/git-fetch.txt\n@@ -285,6 +285,13 @@ linkgit:git-gc[1]).\n \n include::transfer-data-leaks.txt[]\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/fetch.txt[]\n+\n BUGS\n ----\n Using --recurse-submodules can only fetch new commits in submodules that are\ndiff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt\nindex bbcbdceb459..c60fc9c138b 100644\n--- a/Documentation/git-switch.txt\n+++ b/Documentation/git-switch.txt\n@@ -265,6 +265,13 @@ always create a new name for it (without switching away):\n $ git switch -c good-surprises\n ------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/checkout.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-checkout[1],\n-- \n2.37.3.1406.g184357183a6\n\n"},{"id":"462579","messageId":"CAHd-oW4QpPBUqo5ToWXtBg7-LHbEam7aqSALSrwaA3OABma8ng@mail.gmail.com","threadId":"58160","inReplyTo":"cover-v3-0.9-00000000000-20220831T083759Z-avarab@gmail.com","subject":"Re: [PATCH v3 0/9] docs: de-duplicate sections, add more CONFIGURATION sections","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-09-03T13:29:31Z","receivedAt":"2022-09-03T13:29:50Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"Hi, Ævar\n\nThanks for the reroll. I looked at the range-diff, and you've\naddressed almost all of my comments from the previous version. I only\nspot one issue:\n\nOn Wed, Aug 31, 2022 at 5:41 AM Ævar Arnfjörð Bjarmason\n wrote:\n>\n> Range-diff against v2:\n> [...]\n> 8: 5c379ab1476 ! 8: af912e9ca65 docs: add CONFIGURATION sections that map to a built-in\n> @@ Documentation/git-fast-import.txt: operator can use this facility to peek at the\n> --------\n> linkgit:git-fast-export[1]\n>\n> + ## Documentation/git-init.txt ##\n> +@@ Documentation/git-init.txt: $ git commit <3>\n> + <2> Add all existing files to the index.\n> + <3> Record the pristine state as the first commit in the history.\n> +\n> ++CONFIGURATION\n> ++-------------\n> ++\n> ++include::includes/cmd-config-section-all.txt[]\n> ++\n> ++include::config/init.txt[]\n> ++\n> + GIT\n> + ---\n> + Part of the linkgit:git[1] suite\n> +\n\nShouldn't this change be part of commit 9 instead of 8?\n"},{"id":"462684","messageId":"cover-v4-0.9-00000000000-20220907T082419Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v3-0.9-00000000000-20220831T083759Z-avarab@gmail.com","subject":"[PATCH v4 0/9] docs: de-duplicate sections, add more CONFIGURATION sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-07T08:26:56Z","receivedAt":"2022-09-07T08:27:18Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"This series:\n\n * De-duplicates and combines configuration discussion that was split\n or spread across Documentation/config/*.txt and\n Documentation/git-*.txt, moving it to Documentation/config/*.txt.\n\n * Includes that relevant Documentation/config/*.txt in the\n Documentation/git-*.txt files.\n\n * Introduces and uses included prose for those \"CONFIGURATION\"\n sections in various Documentation/git-*.txt files, informing the\n reader that what they see there is included from \"git-config(1)\".\n\nThis v4 addresses the feedback from Matheus Tavares on v3 (thanks for\nthe review!): A hunk belonged in 9/9, not 8/9 (init's config is used\nby e.g. \"clone\" too). The end-state at the end of this series is\nexactly the same.\n\n1. https://lore.kernel.org/git/CAHd-oW4QpPBUqo5ToWXtBg7-LHbEam7aqSALSrwaA3OABma8ng@mail.gmail.com/\n\nÆvar Arnfjörð Bjarmason (9):\n docs: add and use include template for config/* includes\n grep docs: de-duplicate configuration sections\n send-email docs: de-duplicate configuration sections\n apply docs: de-duplicate configuration sections\n notes docs: de-duplicate and combine configuration sections\n difftool docs: de-duplicate configuration sections\n log docs: de-duplicate configuration sections\n docs: add CONFIGURATION sections that map to a built-in\n docs: add CONFIGURATION sections that fuzzy map to built-ins\n\n Documentation/Makefile | 1 +\n Documentation/config/diff.txt | 15 -----\n Documentation/config/difftool.txt | 28 +++++++++-\n Documentation/config/grep.txt | 7 ++-\n Documentation/config/log.txt | 4 ++\n Documentation/config/notes.txt | 43 +++++++++------\n Documentation/config/sendemail.txt | 40 +++++++++++++-\n Documentation/git-add.txt | 7 +++\n Documentation/git-am.txt | 7 +++\n Documentation/git-apply.txt | 10 +---\n Documentation/git-blame.txt | 6 ++\n Documentation/git-branch.txt | 4 ++\n Documentation/git-checkout.txt | 7 +++\n Documentation/git-clean.txt | 7 +++\n Documentation/git-clone.txt | 9 +++\n Documentation/git-column.txt | 7 +++\n Documentation/git-commit-graph.txt | 7 +++\n Documentation/git-commit.txt | 4 ++\n Documentation/git-diff.txt | 7 +++\n Documentation/git-difftool.txt | 27 ++-------\n Documentation/git-fast-import.txt | 7 +++\n Documentation/git-fetch.txt | 7 +++\n Documentation/git-fsck.txt | 2 +\n Documentation/git-gc.txt | 3 +-\n Documentation/git-grep.txt | 29 +---------\n Documentation/git-imap-send.txt | 2 +\n Documentation/git-init.txt | 7 +++\n Documentation/git-log.txt | 46 ++--------------\n Documentation/git-mailinfo.txt | 7 +++\n Documentation/git-maintenance.txt | 7 +++\n Documentation/git-merge.txt | 5 +-\n Documentation/git-mergetool.txt | 3 +\n Documentation/git-notes.txt | 55 ++-----------------\n Documentation/git-push.txt | 7 +++\n Documentation/git-rebase.txt | 2 +\n Documentation/git-revert.txt | 7 +++\n Documentation/git-send-email.txt | 36 +-----------\n Documentation/git-show-branch.txt | 7 +++\n Documentation/git-stash.txt | 7 +++\n Documentation/git-switch.txt | 7 +++\n .../includes/cmd-config-section-all.txt | 3 +\n .../includes/cmd-config-section-rest.txt | 3 +\n 42 files changed, 280 insertions(+), 226 deletions(-)\n create mode 100644 Documentation/includes/cmd-config-section-all.txt\n create mode 100644 Documentation/includes/cmd-config-section-rest.txt\n\nRange-diff against v3:\n 1: da21c19978c = 1: ddcae390002 docs: add and use include template for config/* includes\n 2: d16e927caa2 = 2: e5ad838e1d7 grep docs: de-duplicate configuration sections\n 3: c36feb6f35a = 3: f73c148a06e send-email docs: de-duplicate configuration sections\n 4: 5707c9dd635 = 4: 5523095fe7e apply docs: de-duplicate configuration sections\n 5: 5b0ea00aa33 = 5: 9f1b90298d8 notes docs: de-duplicate and combine configuration sections\n 6: c4c3fa14190 = 6: 73e6804db13 difftool docs: de-duplicate configuration sections\n 7: e07585ba085 = 7: 6465a98ec0a log docs: de-duplicate configuration sections\n 8: af912e9ca65 ! 8: 929fd693bdf docs: add CONFIGURATION sections that map to a built-in\n @@ Documentation/git-fast-import.txt: operator can use this facility to peek at the\n --------\n linkgit:git-fast-export[1]\n \n - ## Documentation/git-init.txt ##\n -@@ Documentation/git-init.txt: $ git commit <3>\n - <2> Add all existing files to the index.\n - <3> Record the pristine state as the first commit in the history.\n - \n -+CONFIGURATION\n -+-------------\n -+\n -+include::includes/cmd-config-section-all.txt[]\n -+\n -+include::config/init.txt[]\n -+\n - GIT\n - ---\n - Part of the linkgit:git[1] suite\n -\n ## Documentation/git-mailinfo.txt ##\n @@ Documentation/git-mailinfo.txt: If no such configuration option has been set, `warn` will be used.\n ::\n 9: 5ef36654bba ! 9: 738ee46512d docs: add CONFIGURATION sections that fuzzy map to built-ins\n @@ Documentation/git-fetch.txt: linkgit:git-gc[1]).\n ----\n Using --recurse-submodules can only fetch new commits in submodules that are\n \n + ## Documentation/git-init.txt ##\n +@@ Documentation/git-init.txt: $ git commit <3>\n + <2> Add all existing files to the index.\n + <3> Record the pristine state as the first commit in the history.\n + \n ++CONFIGURATION\n ++-------------\n ++\n ++include::includes/cmd-config-section-all.txt[]\n ++\n ++include::config/init.txt[]\n ++\n + GIT\n + ---\n + Part of the linkgit:git[1] suite\n +\n ## Documentation/git-switch.txt ##\n @@ Documentation/git-switch.txt: always create a new name for it (without switching away):\n $ git switch -c good-surprises\n-- \n2.37.3.1490.g9adf4224da0\n\n"},{"id":"462685","messageId":"patch-v4-1.9-ddcae390002-20220907T082419Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v4-0.9-00000000000-20220907T082419Z-avarab@gmail.com","subject":"[PATCH v4 1/9] docs: add and use include template for config/* includes","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-07T08:26:57Z","receivedAt":"2022-09-07T08:27:20Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"In b6a8d09f6d8 (gc docs: include the \"gc.*\" section from \"config\" in\n\"gc\", 2019-04-07) the \"git gc\" documentation was made to include the\nconfig/gc.txt in its \"CONFIGURATION\" section. We do that in several\nother places, but \"git gc\" was the only one with a blurb above the\ninclude to orient the reader.\n\nWe don't want readers to carefully scrutinize \"git-config(1)\" and\n\"git-gc(1)\" looking for discrepancies, instead we should tell them\nthat the latter includes a part of the former.\n\nThis change formalizes that wording in two new templates to be\nincluded, one for the \"git gc\" case where the entire section is\nincluded from \"git-config(1)\", and another for when the inclusion of\n\"git-config(1)\" follows discussion unique to that documentation. In\norder to use that re-arrange the order of those being discussed in the\n\"git-merge(1)\" documentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/Makefile | 1 +\n Documentation/git-fsck.txt | 2 ++\n Documentation/git-gc.txt | 3 +--\n Documentation/git-imap-send.txt | 2 ++\n Documentation/git-merge.txt | 5 ++++-\n Documentation/git-mergetool.txt | 3 +++\n Documentation/git-rebase.txt | 2 ++\n Documentation/includes/cmd-config-section-all.txt | 3 +++\n Documentation/includes/cmd-config-section-rest.txt | 3 +++\n 9 files changed, 21 insertions(+), 3 deletions(-)\n create mode 100644 Documentation/includes/cmd-config-section-all.txt\n create mode 100644 Documentation/includes/cmd-config-section-rest.txt\n\ndiff --git a/Documentation/Makefile b/Documentation/Makefile\nindex bd6b6fcb930..849af6da307 100644\n--- a/Documentation/Makefile\n+++ b/Documentation/Makefile\n@@ -62,6 +62,7 @@ HOWTO_TXT += $(wildcard howto/*.txt)\n \n DOC_DEP_TXT += $(wildcard *.txt)\n DOC_DEP_TXT += $(wildcard config/*.txt)\n+DOC_DEP_TXT += $(wildcard includes/*.txt)\n \n ifdef MAN_FILTER\n MAN_TXT = $(filter $(MAN_FILTER),$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT))\ndiff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt\nindex 5088783dccb..29318ea957e 100644\n--- a/Documentation/git-fsck.txt\n+++ b/Documentation/git-fsck.txt\n@@ -107,6 +107,8 @@ care about this output and want to speed it up further.\n CONFIGURATION\n -------------\n \n+include::includes/cmd-config-section-all.txt[]\n+\n include::config/fsck.txt[]\n \n DISCUSSION\ndiff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt\nindex 0af7540a0c8..a65c9aa62d6 100644\n--- a/Documentation/git-gc.txt\n+++ b/Documentation/git-gc.txt\n@@ -110,8 +110,7 @@ users and their repositories.\n CONFIGURATION\n -------------\n \n-The below documentation is the same as what's found in\n-linkgit:git-config[1]:\n+include::includes/cmd-config-section-all.txt[]\n \n include::config/gc.txt[]\n \ndiff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt\nindex 63cf498ce9f..f7b18515141 100644\n--- a/Documentation/git-imap-send.txt\n+++ b/Documentation/git-imap-send.txt\n@@ -54,6 +54,8 @@ CONFIGURATION\n To use the tool, `imap.folder` and either `imap.tunnel` or `imap.host` must be set\n to appropriate values.\n \n+include::includes/cmd-config-section-rest.txt[]\n+\n include::config/imap.txt[]\n \n EXAMPLES\ndiff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt\nindex fee1dc2df28..2d6a1391c89 100644\n--- a/Documentation/git-merge.txt\n+++ b/Documentation/git-merge.txt\n@@ -383,13 +383,16 @@ include::merge-strategies.txt[]\n \n CONFIGURATION\n -------------\n-include::config/merge.txt[]\n \n branch..mergeOptions::\n \tSets default options for merging into branch . The syntax and\n \tsupported options are the same as those of 'git merge', but option\n \tvalues containing whitespace characters are currently not supported.\n \n+include::includes/cmd-config-section-rest.txt[]\n+\n+include::config/merge.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-fmt-merge-msg[1], linkgit:git-pull[1],\ndiff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt\nindex f784027bc13..c44e205629b 100644\n--- a/Documentation/git-mergetool.txt\n+++ b/Documentation/git-mergetool.txt\n@@ -102,6 +102,9 @@ success of the resolution after the custom tool has exited.\n CONFIGURATION\n -------------\n :git-mergetool: 1\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n include::config/mergetool.txt[]\n \n TEMPORARY FILES\ndiff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt\nindex 1877942180e..9cb8931c7ac 100644\n--- a/Documentation/git-rebase.txt\n+++ b/Documentation/git-rebase.txt\n@@ -1259,6 +1259,8 @@ merge cmake\n CONFIGURATION\n -------------\n \n+include::includes/cmd-config-section-all.txt[]\n+\n include::config/rebase.txt[]\n include::config/sequencer.txt[]\n \ndiff --git a/Documentation/includes/cmd-config-section-all.txt b/Documentation/includes/cmd-config-section-all.txt\nnew file mode 100644\nindex 00000000000..296a239f2ab\n--- /dev/null\n+++ b/Documentation/includes/cmd-config-section-all.txt\n@@ -0,0 +1,3 @@\n+Everything below this line in this section is selectively included\n+from the linkgit:git-config[1] documentation. The content is the same\n+as what's found there:\ndiff --git a/Documentation/includes/cmd-config-section-rest.txt b/Documentation/includes/cmd-config-section-rest.txt\nnew file mode 100644\nindex 00000000000..b1e7682c1dc\n--- /dev/null\n+++ b/Documentation/includes/cmd-config-section-rest.txt\n@@ -0,0 +1,3 @@\n+Everything above this line in this section isn't included from the\n+linkgit:git-config[1] documentation. The content that follows is the\n+same as what's found there:\n-- \n2.37.3.1490.g9adf4224da0\n\n"},{"id":"462686","messageId":"patch-v4-2.9-e5ad838e1d7-20220907T082419Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v4-0.9-00000000000-20220907T082419Z-avarab@gmail.com","subject":"[PATCH v4 2/9] grep docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-07T08:26:58Z","receivedAt":"2022-09-07T08:27:21Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Include the \"config/grep.txt\" file in \"git-grep.txt\", instead of\nrepeating an almost identical description of the \"grep\" configuration\nvariables in two places.\n\nThere is no loss of information here that isn't shown in the addition\nto \"grep.txt\". This change was made by copying the contents of\n\"git-grep.txt\"'s version over the \"grep.txt\" version. Aside from the\nchange \"grep.txt\" being made here the two were identical.\n\nThis documentation started being copy/pasted around in\nb22520a37c8 (grep: allow -E and -n to be turned on by default via\nconfiguration, 2011-03-30). After that in e.g. 6453f7b3486 (grep: add\ngrep.fullName config variable, 2014-03-17) they started drifting\napart, with only grep.fullName being described in the command\ndocumentation.\n\nIn 434e6e753fe (config.txt: move grep.* to a separate file,\n2018-10-27) we gained the include, but didn't do this next step, let's\ndo it now.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/grep.txt | 7 +++++--\n Documentation/git-grep.txt | 29 ++---------------------------\n 2 files changed, 7 insertions(+), 29 deletions(-)\n\ndiff --git a/Documentation/config/grep.txt b/Documentation/config/grep.txt\nindex 182edd813a5..e521f20390c 100644\n--- a/Documentation/config/grep.txt\n+++ b/Documentation/config/grep.txt\n@@ -17,8 +17,11 @@ grep.extendedRegexp::\n \tother than 'default'.\n \n grep.threads::\n-\tNumber of grep worker threads to use.\n-\tSee `grep.threads` in linkgit:git-grep[1] for more information.\n+\tNumber of grep worker threads to use. If unset (or set to 0), Git will\n+\tuse as many threads as the number of logical cores available.\n+\n+grep.fullName::\n+\tIf set to true, enable `--full-name` option by default.\n \n grep.fallbackToNoIndex::\n \tIf set to true, fall back to git grep --no-index if git grep\ndiff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt\nindex 58d944bd578..dabdbe8471d 100644\n--- a/Documentation/git-grep.txt\n+++ b/Documentation/git-grep.txt\n@@ -343,34 +343,9 @@ performance in this case, it might be desirable to use `--threads=1`.\n CONFIGURATION\n -------------\n \n-grep.lineNumber::\n-\tIf set to true, enable `-n` option by default.\n-\n-grep.column::\n-\tIf set to true, enable the `--column` option by default.\n-\n-grep.patternType::\n-\tSet the default matching behavior. Using a value of 'basic', 'extended',\n-\t'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`,\n-\t`--fixed-strings`, or `--perl-regexp` option accordingly, while the\n-\tvalue 'default' will return to the default matching behavior.\n-\n-grep.extendedRegexp::\n-\tIf set to true, enable `--extended-regexp` option by default. This\n-\toption is ignored when the `grep.patternType` option is set to a value\n-\tother than 'default'.\n-\n-grep.threads::\n-\tNumber of grep worker threads to use. If unset (or set to 0), Git will\n-\tuse as many threads as the number of logical cores available.\n-\n-grep.fullName::\n-\tIf set to true, enable `--full-name` option by default.\n-\n-grep.fallbackToNoIndex::\n-\tIf set to true, fall back to git grep --no-index if git grep\n-\tis executed outside of a git repository. Defaults to false.\n+include::includes/cmd-config-section-all.txt[]\n \n+include::config/grep.txt[]\n \n GIT\n ---\n-- \n2.37.3.1490.g9adf4224da0\n\n"},{"id":"462687","messageId":"patch-v4-3.9-f73c148a06e-20220907T082419Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v4-0.9-00000000000-20220907T082419Z-avarab@gmail.com","subject":"[PATCH v4 3/9] send-email docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-07T08:26:59Z","receivedAt":"2022-09-07T08:27:30Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"De-duplicate the discussion of \"send-email\" configuration, such that\nthe \"git-config(1)\" manual page becomes the source of truth, and\n\"git-send-email(1)\" includes the relevant part.\n\nMost commands that suffered from such duplication had diverging text\ndiscussing the same variables, but in this case some config was also\nonly discussed in one or the other.\n\nThis is mostly a move-only change, the exception is a minor rewording\nof changing wording like \"see above\" to \"see linkgit:git-config[1]\",\nas well as a clarification about the big section of command-line\noption tweaking config being discussed in git-send-email(1)'s main\ndocs.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/sendemail.txt | 40 +++++++++++++++++++++++++++---\n Documentation/git-send-email.txt | 36 ++-------------------------\n 2 files changed, 39 insertions(+), 37 deletions(-)\n\ndiff --git a/Documentation/config/sendemail.txt b/Documentation/config/sendemail.txt\nindex 50baa5d6bfb..51da7088a84 100644\n--- a/Documentation/config/sendemail.txt\n+++ b/Documentation/config/sendemail.txt\n@@ -18,17 +18,49 @@ sendemail..*::\n \tidentity is selected, through either the command-line or\n \t`sendemail.identity`.\n \n+sendemail.multiEdit::\n+\tIf true (default), a single editor instance will be spawned to edit\n+\tfiles you have to edit (patches when `--annotate` is used, and the\n+\tsummary when `--compose` is used). If false, files will be edited one\n+\tafter the other, spawning a new editor each time.\n+\n+sendemail.confirm::\n+\tSets the default for whether to confirm before sending. Must be\n+\tone of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`\n+\tin the linkgit:git-send-email[1] documentation for the meaning of these\n+\tvalues.\n+\n sendemail.aliasesFile::\n+\tTo avoid typing long email addresses, point this to one or more\n+\temail aliases files. You must also supply `sendemail.aliasFileType`.\n+\n sendemail.aliasFileType::\n+\tFormat of the file(s) specified in sendemail.aliasesFile. Must be\n+\tone of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.\n++\n+What an alias file in each format looks like can be found in\n+the documentation of the email program of the same name. The\n+differences and limitations from the standard formats are\n+described below:\n++\n+--\n+sendmail;;\n+*\tQuoted aliases and quoted addresses are not supported: lines that\n+\tcontain a `\"` symbol are ignored.\n+*\tRedirection to a file (`/path/name`) or pipe (`|command`) is not\n+\tsupported.\n+*\tFile inclusion (`:include: /path/name`) is not supported.\n+*\tWarnings are printed on the standard error output for any\n+\texplicitly unsupported constructs, and any other lines that are not\n+\trecognized by the parser.\n+--\n sendemail.annotate::\n sendemail.bcc::\n sendemail.cc::\n sendemail.ccCmd::\n sendemail.chainReplyTo::\n-sendemail.confirm::\n sendemail.envelopeSender::\n sendemail.from::\n-sendemail.multiEdit::\n sendemail.signedoffbycc::\n sendemail.smtpPass::\n sendemail.suppresscc::\n@@ -44,7 +76,9 @@ sendemail.thread::\n sendemail.transferEncoding::\n sendemail.validate::\n sendemail.xmailer::\n-\tSee linkgit:git-send-email[1] for description.\n+\tThese configuration variables all provide a default for\n+\tlinkgit:git-send-email[1] command-line options. See its\n+\tdocumentation for details.\n \n sendemail.signedoffcc (deprecated)::\n \tDeprecated alias for `sendemail.signedoffbycc`.\ndiff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\nindex 41cd8cb4247..3290043053a 100644\n--- a/Documentation/git-send-email.txt\n+++ b/Documentation/git-send-email.txt\n@@ -456,41 +456,9 @@ Information\n CONFIGURATION\n -------------\n \n-sendemail.aliasesFile::\n-\tTo avoid typing long email addresses, point this to one or more\n-\temail aliases files. You must also supply `sendemail.aliasFileType`.\n+include::includes/cmd-config-section-all.txt[]\n \n-sendemail.aliasFileType::\n-\tFormat of the file(s) specified in sendemail.aliasesFile. Must be\n-\tone of 'mutt', 'mailrc', 'pine', 'elm', or 'gnus', or 'sendmail'.\n-+\n-What an alias file in each format looks like can be found in\n-the documentation of the email program of the same name. The\n-differences and limitations from the standard formats are\n-described below:\n-+\n---\n-sendmail;;\n-*\tQuoted aliases and quoted addresses are not supported: lines that\n-\tcontain a `\"` symbol are ignored.\n-*\tRedirection to a file (`/path/name`) or pipe (`|command`) is not\n-\tsupported.\n-*\tFile inclusion (`:include: /path/name`) is not supported.\n-*\tWarnings are printed on the standard error output for any\n-\texplicitly unsupported constructs, and any other lines that are not\n-\trecognized by the parser.\n---\n-\n-sendemail.multiEdit::\n-\tIf true (default), a single editor instance will be spawned to edit\n-\tfiles you have to edit (patches when `--annotate` is used, and the\n-\tsummary when `--compose` is used). If false, files will be edited one\n-\tafter the other, spawning a new editor each time.\n-\n-sendemail.confirm::\n-\tSets the default for whether to confirm before sending. Must be\n-\tone of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm`\n-\tin the previous section for the meaning of these values.\n+include::config/sendemail.txt[]\n \n EXAMPLES\n --------\n-- \n2.37.3.1490.g9adf4224da0\n\n"},{"id":"462688","messageId":"patch-v4-4.9-5523095fe7e-20220907T082419Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v4-0.9-00000000000-20220907T082419Z-avarab@gmail.com","subject":"[PATCH v4 4/9] apply docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-07T08:27:00Z","receivedAt":"2022-09-07T08:27:32Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The wording is not identical to Documentation/config/apply.txt, but\nthat version is better.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-apply.txt | 10 +++-------\n 1 file changed, 3 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt\nindex b6d77f42068..1d478cbe9b5 100644\n--- a/Documentation/git-apply.txt\n+++ b/Documentation/git-apply.txt\n@@ -263,13 +263,9 @@ has no effect when `--index` or `--cached` is in use.\n CONFIGURATION\n -------------\n \n-apply.ignoreWhitespace::\n-\tSet to 'change' if you want changes in whitespace to be ignored by default.\n-\tSet to one of: no, none, never, false if you want changes in\n-\twhitespace to be significant.\n-apply.whitespace::\n-\tWhen no `--whitespace` flag is given from the command\n-\tline, this configuration item is used as the default.\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/apply.txt[]\n \n SUBMODULES\n ----------\n-- \n2.37.3.1490.g9adf4224da0\n\n"},{"id":"462689","messageId":"patch-v4-5.9-9f1b90298d8-20220907T082419Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v4-0.9-00000000000-20220907T082419Z-avarab@gmail.com","subject":"[PATCH v4 5/9] notes docs: de-duplicate and combine configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-07T08:27:01Z","receivedAt":"2022-09-07T08:27:33Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Combine the various \"notes\" configuration sections spread across\nDocumentation/config/notes.txt and Documentation/git-notes.txt to live\nin the former, and to be included in the latter.\n\nWe'll now forward link from \"git notes\" to the \"CONFIGURATION\" section\nbelow, rather than to \"git-config(1)\" when discussing configuration\nvariables that are (also) discussed in that section.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/notes.txt | 43 +++++++++++++++-----------\n Documentation/git-log.txt | 16 ++--------\n Documentation/git-notes.txt | 55 +++-------------------------------\n 3 files changed, 33 insertions(+), 81 deletions(-)\n\ndiff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt\nindex aeef56d49ae..c7c4811734b 100644\n--- a/Documentation/config/notes.txt\n+++ b/Documentation/config/notes.txt\n@@ -3,6 +3,9 @@ notes.mergeStrategy::\n \tconflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or\n \t`cat_sort_uniq`. Defaults to `manual`. See \"NOTES MERGE STRATEGIES\"\n \tsection of linkgit:git-notes[1] for more information on each strategy.\n++\n+This setting can be overridden by passing the `--strategy` option to\n+linkgit:git-notes[1].\n \n notes..mergeStrategy::\n \tWhich merge strategy to choose when doing a notes merge into\n@@ -11,28 +14,35 @@ notes..mergeStrategy::\n \tlinkgit:git-notes[1] for more information on the available strategies.\n \n notes.displayRef::\n-\tThe (fully qualified) refname from which to show notes when\n-\tshowing commit messages. The value of this variable can be set\n-\tto a glob, in which case notes from all matching refs will be\n-\tshown. You may also specify this configuration variable\n-\tseveral times. A warning will be issued for refs that do not\n-\texist, but a glob that does not match any refs is silently\n-\tignored.\n+\tWhich ref (or refs, if a glob or specified more than once), in\n+\taddition to the default set by `core.notesRef` or\n+\t`GIT_NOTES_REF`, to read notes from when showing commit\n+\tmessages with the 'git log' family of commands.\n +\n This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`\n environment variable, which must be a colon separated list of refs or\n globs.\n +\n+A warning will be issued for refs that do not exist,\n+but a glob that does not match any refs is silently ignored.\n++\n+This setting can be disabled by the `--no-notes` option to the 'git\n+log' family of commands, or by the `--notes=` option accepted by\n+those commands.\n++\n The effective value of \"core.notesRef\" (possibly overridden by\n GIT_NOTES_REF) is also implicitly added to the list of refs to be\n displayed.\n \n notes.rewrite.::\n \tWhen rewriting commits with (currently `amend` or\n-\t`rebase`) and this variable is set to `true`, Git\n-\tautomatically copies your notes from the original to the\n-\trewritten commit. Defaults to `true`, but see\n-\t\"notes.rewriteRef\" below.\n+\t`rebase`), if this variable is `false`, git will not copy\n+\tnotes from the original to the rewritten commit. Defaults to\n+\t`true`. See also \"`notes.rewriteRef`\" below.\n++\n+This setting can be overridden with the `GIT_NOTES_REWRITE_REF`\n+environment variable, which must be a colon separated list of refs or\n+globs.\n \n notes.rewriteMode::\n \tWhen copying notes during a rewrite (see the\n@@ -46,14 +56,13 @@ environment variable.\n \n notes.rewriteRef::\n \tWhen copying notes during a rewrite, specifies the (fully\n-\tqualified) ref whose notes should be copied. The ref may be a\n-\tglob, in which case notes in all matching refs will be copied.\n-\tYou may also specify this configuration several times.\n+\tqualified) ref whose notes should be copied. May be a glob,\n+\tin which case notes in all matching refs will be copied. You\n+\tmay also specify this configuration several times.\n +\n Does not have a default value; you must configure this variable to\n enable note rewriting. Set it to `refs/notes/commits` to enable\n rewriting for the default commit notes.\n +\n-This setting can be overridden with the `GIT_NOTES_REWRITE_REF`\n-environment variable, which must be a colon separated list of refs or\n-globs.\n+Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.\n+See `notes.rewrite.` above for a further description of its format.\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex b1285aee3c2..410095e9a4f 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -237,19 +237,9 @@ log.showSignature::\n mailmap.*::\n \tSee linkgit:git-shortlog[1].\n \n-notes.displayRef::\n-\tWhich refs, in addition to the default set by `core.notesRef`\n-\tor `GIT_NOTES_REF`, to read notes from when showing commit\n-\tmessages with the `log` family of commands. See\n-\tlinkgit:git-notes[1].\n-+\n-May be an unabbreviated ref name or a glob and may be specified\n-multiple times. A warning will be issued for refs that do not exist,\n-but a glob that does not match any refs is silently ignored.\n-+\n-This setting can be disabled by the `--no-notes` option,\n-overridden by the `GIT_NOTES_DISPLAY_REF` environment variable,\n-and overridden by the `--notes=` option.\n+include::includes/cmd-config-section-rest.txt[]\n+\n+include::config/notes.txt[]\n \n GIT\n ---\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 0a4200674c4..efbc10f0f59 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -44,7 +44,7 @@ using the `--notes` option. Such notes are added as a patch commentary\n after a three dash separator line.\n \n To change which notes are shown by 'git log', see the\n-\"notes.displayRef\" configuration in linkgit:git-log[1].\n+\"notes.displayRef\" discussion in <>.\n \n See the \"notes.rewrite.\" configuration for a way to carry\n notes across commands that rewrite commits.\n@@ -307,6 +307,7 @@ with 'git log', so if you use such notes, you'll probably need to write\n some special-purpose tools to do something useful with them.\n \n \n+[[CONFIGURATION]]\n CONFIGURATION\n -------------\n \n@@ -316,57 +317,9 @@ core.notesRef::\n \tThis setting can be overridden through the environment and\n \tcommand line.\n \n-notes.mergeStrategy::\n-\tWhich merge strategy to choose by default when resolving notes\n-\tconflicts. Must be one of `manual`, `ours`, `theirs`, `union`, or\n-\t`cat_sort_uniq`. Defaults to `manual`. See \"NOTES MERGE STRATEGIES\"\n-\tsection above for more information on each strategy.\n-+\n-This setting can be overridden by passing the `--strategy` option.\n-\n-notes..mergeStrategy::\n-\tWhich merge strategy to choose when doing a notes merge into\n-\trefs/notes/. This overrides the more general\n-\t\"notes.mergeStrategy\". See the \"NOTES MERGE STRATEGIES\" section above\n-\tfor more information on each available strategy.\n-\n-notes.displayRef::\n-\tWhich ref (or refs, if a glob or specified more than once), in\n-\taddition to the default set by `core.notesRef` or\n-\t`GIT_NOTES_REF`, to read notes from when showing commit\n-\tmessages with the 'git log' family of commands.\n-\tThis setting can be overridden on the command line or by the\n-\t`GIT_NOTES_DISPLAY_REF` environment variable.\n-\tSee linkgit:git-log[1].\n-\n-notes.rewrite.::\n-\tWhen rewriting commits with (currently `amend` or\n-\t`rebase`), if this variable is `false`, git will not copy\n-\tnotes from the original to the rewritten commit. Defaults to\n-\t`true`. See also \"`notes.rewriteRef`\" below.\n-+\n-This setting can be overridden by the `GIT_NOTES_REWRITE_REF`\n-environment variable.\n+include::includes/cmd-config-section-rest.txt[]\n \n-notes.rewriteMode::\n-\tWhen copying notes during a rewrite, what to do if the target\n-\tcommit already has a note. Must be one of `overwrite`,\n-\t`concatenate`, `cat_sort_uniq`, or `ignore`. Defaults to\n-\t`concatenate`.\n-+\n-This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`\n-environment variable.\n-\n-notes.rewriteRef::\n-\tWhen copying notes during a rewrite, specifies the (fully\n-\tqualified) ref whose notes should be copied. May be a glob,\n-\tin which case notes in all matching refs will be copied. You\n-\tmay also specify this configuration several times.\n-+\n-Does not have a default value; you must configure this variable to\n-enable note rewriting.\n-+\n-Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.\n+include::config/notes.txt[]\n \n \n ENVIRONMENT\n-- \n2.37.3.1490.g9adf4224da0\n\n"},{"id":"462690","messageId":"patch-v4-6.9-73e6804db13-20220907T082419Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v4-0.9-00000000000-20220907T082419Z-avarab@gmail.com","subject":"[PATCH v4 6/9] difftool docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-07T08:27:02Z","receivedAt":"2022-09-07T08:27:34Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Include the \"config/difftool.txt\" file in \"git-difftool.txt\", and move\nthe relevant part of git-difftool(1) configuration from\n\"config/diff.txt\" to config/difftool.txt\".\n\nDoing this is slightly odd, as we usually discuss configuration in\nalphabetical order, but by doing it we're able to include the full set\nof configuration used by git-difftool(1) (and only that configuration)\nin its own documentation.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/diff.txt | 15 ---------------\n Documentation/config/difftool.txt | 28 +++++++++++++++++++++++++---\n Documentation/git-difftool.txt | 27 ++++-----------------------\n 3 files changed, 29 insertions(+), 41 deletions(-)\n\ndiff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt\nindex 32f84838ac1..35a7bf86d77 100644\n--- a/Documentation/config/diff.txt\n+++ b/Documentation/config/diff.txt\n@@ -178,21 +178,6 @@ diff..cachetextconv::\n \tSet this option to true to make the diff driver cache the text\n \tconversion outputs. See linkgit:gitattributes[5] for details.\n \n-diff.tool::\n-\tControls which diff tool is used by linkgit:git-difftool[1].\n-\tThis variable overrides the value configured in `merge.tool`.\n-\tThe list below shows the valid built-in values.\n-\tAny other value is treated as a custom diff tool and requires\n-\tthat a corresponding difftool..cmd variable is defined.\n-\n-diff.guitool::\n-\tControls which diff tool is used by linkgit:git-difftool[1] when\n-\tthe -g/--gui flag is specified. This variable overrides the value\n-\tconfigured in `merge.guitool`. The list below shows the valid\n-\tbuilt-in values. Any other value is treated as a custom diff tool\n-\tand requires that a corresponding difftool..cmd variable\n-\tis defined.\n-\n include::../mergetools-diff.txt[]\n \n diff.indentHeuristic::\ndiff --git a/Documentation/config/difftool.txt b/Documentation/config/difftool.txt\nindex 67625944804..a3f82112102 100644\n--- a/Documentation/config/difftool.txt\n+++ b/Documentation/config/difftool.txt\n@@ -1,6 +1,17 @@\n-difftool..path::\n-\tOverride the path for the given tool. This is useful in case\n-\tyour tool is not in the PATH.\n+diff.tool::\n+\tControls which diff tool is used by linkgit:git-difftool[1].\n+\tThis variable overrides the value configured in `merge.tool`.\n+\tThe list below shows the valid built-in values.\n+\tAny other value is treated as a custom diff tool and requires\n+\tthat a corresponding difftool..cmd variable is defined.\n+\n+diff.guitool::\n+\tControls which diff tool is used by linkgit:git-difftool[1] when\n+\tthe -g/--gui flag is specified. This variable overrides the value\n+\tconfigured in `merge.guitool`. The list below shows the valid\n+\tbuilt-in values. Any other value is treated as a custom diff tool\n+\tand requires that a corresponding difftool..cmd variable\n+\tis defined.\n \n difftool..cmd::\n \tSpecify the command to invoke the specified diff tool.\n@@ -9,6 +20,17 @@ difftool..cmd::\n \tfile containing the contents of the diff pre-image and 'REMOTE'\n \tis set to the name of the temporary file containing the contents\n \tof the diff post-image.\n++\n+See the `--tool=` option in linkgit:git-difftool[1] for more details.\n+\n+difftool..path::\n+\tOverride the path for the given tool. This is useful in case\n+\tyour tool is not in the PATH.\n+\n+difftool.trustExitCode::\n+\tExit difftool if the invoked diff tool returns a non-zero exit status.\n++\n+See the `--trust-exit-code` option in linkgit:git-difftool[1] for more details.\n \n difftool.prompt::\n \tPrompt before each invocation of the diff tool.\ndiff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt\nindex 143b0c49d73..9d14c3c9f09 100644\n--- a/Documentation/git-difftool.txt\n+++ b/Documentation/git-difftool.txt\n@@ -113,33 +113,14 @@ instead. `--no-symlinks` is the default on Windows.\n \n See linkgit:git-diff[1] for the full list of supported options.\n \n-CONFIG VARIABLES\n-----------------\n+CONFIGURATION\n+-------------\n 'git difftool' falls back to 'git mergetool' config variables when the\n difftool equivalents have not been defined.\n \n-diff.tool::\n-\tThe default diff tool to use.\n+include::includes/cmd-config-section-rest.txt[]\n \n-diff.guitool::\n-\tThe default diff tool to use when `--gui` is specified.\n-\n-difftool..path::\n-\tOverride the path for the given tool. This is useful in case\n-\tyour tool is not in the PATH.\n-\n-difftool..cmd::\n-\tSpecify the command to invoke the specified diff tool.\n-+\n-See the `--tool=` option above for more details.\n-\n-difftool.prompt::\n-\tPrompt before each invocation of the diff tool.\n-\n-difftool.trustExitCode::\n-\tExit difftool if the invoked diff tool returns a non-zero exit status.\n-+\n-See the `--trust-exit-code` option above for more details.\n+include::config/difftool.txt[]\n \n SEE ALSO\n --------\n-- \n2.37.3.1490.g9adf4224da0\n\n"},{"id":"462691","messageId":"patch-v4-7.9-6465a98ec0a-20220907T082419Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v4-0.9-00000000000-20220907T082419Z-avarab@gmail.com","subject":"[PATCH v4 7/9] log docs: de-duplicate configuration sections","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-07T08:27:03Z","receivedAt":"2022-09-07T08:27:36Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Signed-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/config/log.txt | 4 ++++\n Documentation/git-log.txt | 30 ++----------------------------\n 2 files changed, 6 insertions(+), 28 deletions(-)\n\ndiff --git a/Documentation/config/log.txt b/Documentation/config/log.txt\nindex 5250ba45fb4..bc63bc3939c 100644\n--- a/Documentation/config/log.txt\n+++ b/Documentation/config/log.txt\n@@ -7,6 +7,10 @@ log.date::\n \tSet the default date-time mode for the 'log' command.\n \tSetting a value for log.date is similar to using 'git log''s\n \t`--date` option. See linkgit:git-log[1] for details.\n++\n+If the format is set to \"auto:foo\" and the pager is in use, format\n+\"foo\" will be the used for the date format. Otherwise \"default\" will\n+be used.\n \n log.decorate::\n \tPrint out the ref names of any commits that are shown by the log\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex 410095e9a4f..2a66cf88807 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -209,36 +209,10 @@ i18n.logOutputEncoding::\n \tDefaults to the value of `i18n.commitEncoding` if set, and UTF-8\n \totherwise.\n \n-log.date::\n-\tDefault format for human-readable dates. (Compare the\n-\t`--date` option.) Defaults to \"default\", which means to write\n-\tdates like `Sat May 8 19:35:34 2010 -0500`.\n-+\n-If the format is set to \"auto:foo\" and the pager is in use, format\n-\"foo\" will be the used for the date format. Otherwise \"default\" will\n-be used.\n-\n-log.follow::\n-\tIf `true`, `git log` will act as if the `--follow` option was used when\n-\ta single is given. This has the same limitations as `--follow`,\n-\ti.e. it cannot be used to follow multiple files and does not work well\n-\ton non-linear history.\n-\n-log.showRoot::\n-\tIf `false`, `git log` and related commands will not treat the\n-\tinitial commit as a big creation event. Any root commits in\n-\t`git log -p` output would be shown without a diff attached.\n-\tThe default is `true`.\n-\n-log.showSignature::\n-\tIf `true`, `git log` and related commands will act as if the\n-\t`--show-signature` option was passed to them.\n-\n-mailmap.*::\n-\tSee linkgit:git-shortlog[1].\n-\n include::includes/cmd-config-section-rest.txt[]\n \n+include::config/log.txt[]\n+\n include::config/notes.txt[]\n \n GIT\n-- \n2.37.3.1490.g9adf4224da0\n\n"},{"id":"462692","messageId":"patch-v4-8.9-929fd693bdf-20220907T082419Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v4-0.9-00000000000-20220907T082419Z-avarab@gmail.com","subject":"[PATCH v4 8/9] docs: add CONFIGURATION sections that map to a built-in","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-07T08:27:04Z","receivedAt":"2022-09-07T08:27:38Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add a CONFIGURATION section to the documentation of various built-ins,\nfor those cases where the relevant config/NAME.txt describes\nconfiguration that is only used by the relevant built-in documented in\ngit-NAME.txt. Subsequent commits will handle more complex cases.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-add.txt | 7 +++++++\n Documentation/git-am.txt | 7 +++++++\n Documentation/git-clean.txt | 7 +++++++\n Documentation/git-clone.txt | 7 +++++++\n Documentation/git-commit-graph.txt | 7 +++++++\n Documentation/git-commit.txt | 4 ++++\n Documentation/git-fast-import.txt | 7 +++++++\n Documentation/git-mailinfo.txt | 7 +++++++\n Documentation/git-maintenance.txt | 7 +++++++\n Documentation/git-push.txt | 7 +++++++\n Documentation/git-revert.txt | 7 +++++++\n Documentation/git-show-branch.txt | 7 +++++++\n Documentation/git-stash.txt | 7 +++++++\n 13 files changed, 88 insertions(+)\n\ndiff --git a/Documentation/git-add.txt b/Documentation/git-add.txt\nindex 9b37f356542..a030d33c6e7 100644\n--- a/Documentation/git-add.txt\n+++ b/Documentation/git-add.txt\n@@ -433,6 +433,13 @@ they will make the patch impossible to apply:\n * deleting context or removal lines\n * modifying the contents of context or removal lines\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/add.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-status[1]\ndiff --git a/Documentation/git-am.txt b/Documentation/git-am.txt\nindex 320da6c4f76..326276e51ce 100644\n--- a/Documentation/git-am.txt\n+++ b/Documentation/git-am.txt\n@@ -258,6 +258,13 @@ This command can run `applypatch-msg`, `pre-applypatch`,\n and `post-applypatch` hooks. See linkgit:githooks[5] for more\n information.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/am.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-apply[1].\ndiff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt\nindex a7f309dff5a..91742633fa8 100644\n--- a/Documentation/git-clean.txt\n+++ b/Documentation/git-clean.txt\n@@ -133,6 +133,13 @@ help::\n \n Show brief usage of interactive git-clean.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/clean.txt[]\n+\n SEE ALSO\n --------\n linkgit:gitignore[5]\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex d032d971dd7..1c3d7017646 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -370,6 +370,13 @@ $ cd my-linux\n $ git clone --bare -l /home/proj/.git /pub/scm/proj.git\n ------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/clone.txt[]\n+\n \n GIT\n ---\ndiff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt\nindex 047decdb65b..36fe56c2c71 100644\n--- a/Documentation/git-commit-graph.txt\n+++ b/Documentation/git-commit-graph.txt\n@@ -142,6 +142,13 @@ $ git show-ref -s | git commit-graph write --stdin-commits\n $ git rev-parse HEAD | git commit-graph write --stdin-commits --append\n ------------------------------------------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/commitgraph.txt[]\n+\n \n FILE FORMAT\n -----------\ndiff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt\nindex 6c60bf98f9f..225c6c9f2e5 100644\n--- a/Documentation/git-commit.txt\n+++ b/Documentation/git-commit.txt\n@@ -557,6 +557,10 @@ The editor used to edit the commit log message will be chosen from the\n `VISUAL` environment variable, or the `EDITOR` environment variable (in that\n order). See linkgit:git-var[1] for details.\n \n+include::includes/cmd-config-section-rest.txt[]\n+\n+include::config/commit.txt[]\n+\n HOOKS\n -----\n This command can run `commit-msg`, `prepare-commit-msg`, `pre-commit`,\ndiff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt\nindex 39cfa05b28b..8b5dd6add00 100644\n--- a/Documentation/git-fast-import.txt\n+++ b/Documentation/git-fast-import.txt\n@@ -1564,6 +1564,13 @@ operator can use this facility to peek at the objects and refs from an\n import in progress, at the cost of some added running time and worse\n compression.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/fastimport.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-fast-export[1]\ndiff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt\nindex 3fcfd965fde..28060283c70 100644\n--- a/Documentation/git-mailinfo.txt\n+++ b/Documentation/git-mailinfo.txt\n@@ -115,6 +115,13 @@ If no such configuration option has been set, `warn` will be used.\n ::\n \tThe patch extracted from e-mail.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/mailinfo.txt[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt\nindex e56bad28c65..9c630efe19c 100644\n--- a/Documentation/git-maintenance.txt\n+++ b/Documentation/git-maintenance.txt\n@@ -397,6 +397,13 @@ If you want to customize the background tasks, please rename the tasks\n so future calls to `git maintenance (start|stop)` do not overwrite your\n custom tasks.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/maintenance.txt[]\n+\n \n GIT\n ---\ndiff --git a/Documentation/git-push.txt b/Documentation/git-push.txt\nindex 2f25aa3a291..def7657ef9c 100644\n--- a/Documentation/git-push.txt\n+++ b/Documentation/git-push.txt\n@@ -692,6 +692,13 @@ a `git gc` command on the origin repository.\n \n include::transfer-data-leaks.txt[]\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/push.txt[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt\nindex 0105a54c1a5..5016755efb6 100644\n--- a/Documentation/git-revert.txt\n+++ b/Documentation/git-revert.txt\n@@ -142,6 +142,13 @@ EXAMPLES\n \tchanges. The revert only modifies the working tree and the\n \tindex.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/revert.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-cherry-pick[1]\ndiff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt\nindex 5cc2fcefbab..e5ec6b467f9 100644\n--- a/Documentation/git-show-branch.txt\n+++ b/Documentation/git-show-branch.txt\n@@ -199,6 +199,13 @@ shows 10 reflog entries going back from the tip as of 1 hour ago.\n Without `--list`, the output also shows how these tips are\n topologically related with each other.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/showbranch.txt[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt\nindex 6e15f475257..c5d70918283 100644\n--- a/Documentation/git-stash.txt\n+++ b/Documentation/git-stash.txt\n@@ -382,6 +382,13 @@ grep commit | cut -d\\ -f3 |\n xargs git log --merges --no-walk --grep=WIP\n ----------------------------------------------------------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/stash.txt[]\n+\n \n SEE ALSO\n --------\n-- \n2.37.3.1490.g9adf4224da0\n\n"},{"id":"462693","messageId":"patch-v4-9.9-738ee46512d-20220907T082419Z-avarab@gmail.com","threadId":"58160","inReplyTo":"cover-v4-0.9-00000000000-20220907T082419Z-avarab@gmail.com","subject":"[PATCH v4 9/9] docs: add CONFIGURATION sections that fuzzy map to built-ins","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-09-07T08:27:05Z","receivedAt":"2022-09-07T08:27:39Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"Add a CONFIGURATION section to the documentation of various built-ins,\nfor those cases where the relevant config/NAME.txt doesn't map only to\none git-NAME.txt. In particular:\n\n * config/blame.txt: used by git-{blame,annotate}.txt. Since the\n git-annotate(1) documentation refers to git-blame(1) don't add a\n \"CONFIGURATION\" section to git-annotate(1), only to git-blame(1).\n\n * config/checkout.txt: maps to both git-checkout.txt and\n git-switch.txt (but nothing else).\n\n * config/init.txt: should be included in git-init(1) and\n git-clone(1).\n\n * config/column.txt: We should ideally mention the relevant subset of\n this in git-{branch,clean,status,tag}.txt, but let's punt on it for\n now. We will when we eventually split these sort of files into\n e.g. config/column.txt and\n config/column/{branch,clean,status,tag}.txt, with the former\n including the latter set.\n\nThings that are being left out, and why:\n\n * config/{remote,remotes,credential}.txt: Configuration that affects\n how we talk to remote repositories is harder to untangle. We'll need\n to include some of this in git-{fetch,remote,push,ls-remote}.txt\n etc., but some of those only use a small subset of these\n options. Let's leave this for now.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason \n---\n Documentation/git-blame.txt | 6 ++++++\n Documentation/git-branch.txt | 4 ++++\n Documentation/git-checkout.txt | 7 +++++++\n Documentation/git-clone.txt | 2 ++\n Documentation/git-column.txt | 7 +++++++\n Documentation/git-diff.txt | 7 +++++++\n Documentation/git-fetch.txt | 7 +++++++\n Documentation/git-init.txt | 7 +++++++\n Documentation/git-switch.txt | 7 +++++++\n 9 files changed, 54 insertions(+)\n\ndiff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt\nindex d7a46cc6744..4400a17330b 100644\n--- a/Documentation/git-blame.txt\n+++ b/Documentation/git-blame.txt\n@@ -241,6 +241,12 @@ MAPPING AUTHORS\n \n See linkgit:gitmailmap[5].\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/blame.txt[]\n \n SEE ALSO\n --------\ndiff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt\nindex ae82378349d..12c5f84e3be 100644\n--- a/Documentation/git-branch.txt\n+++ b/Documentation/git-branch.txt\n@@ -336,6 +336,10 @@ CONFIGURATION\n `--list` is used or implied. The default is to use a pager.\n See linkgit:git-config[1].\n \n+include::includes/cmd-config-section-rest.txt[]\n+\n+include::config/branch.txt[]\n+\n EXAMPLES\n --------\n \ndiff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt\nindex 9f37e22e130..4cb9d555b4b 100644\n--- a/Documentation/git-checkout.txt\n+++ b/Documentation/git-checkout.txt\n@@ -600,6 +600,13 @@ $ edit frotz\n $ git add frotz\n ------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/checkout.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-switch[1],\ndiff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt\nindex 1c3d7017646..d6434d262d6 100644\n--- a/Documentation/git-clone.txt\n+++ b/Documentation/git-clone.txt\n@@ -375,6 +375,8 @@ CONFIGURATION\n \n include::includes/cmd-config-section-all.txt[]\n \n+include::config/init.txt[]\n+\n include::config/clone.txt[]\n \n \ndiff --git a/Documentation/git-column.txt b/Documentation/git-column.txt\nindex 6cea9ab4638..18431647a2d 100644\n--- a/Documentation/git-column.txt\n+++ b/Documentation/git-column.txt\n@@ -74,6 +74,13 @@ v2.4.3 v2.4.4 v2.4.5 v2.4.6 v2.4.7\n v2.4.8 v2.4.9\n ------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/column.txt[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt\nindex 6236c75c9b8..85ae6d6d08a 100644\n--- a/Documentation/git-diff.txt\n+++ b/Documentation/git-diff.txt\n@@ -213,6 +213,13 @@ $ git diff -R <2>\n rewrites (very expensive).\n <2> Output diff in reverse.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/diff.txt[]\n+\n SEE ALSO\n --------\n diff(1),\ndiff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt\nindex e9d364669af..63d9569e164 100644\n--- a/Documentation/git-fetch.txt\n+++ b/Documentation/git-fetch.txt\n@@ -285,6 +285,13 @@ linkgit:git-gc[1]).\n \n include::transfer-data-leaks.txt[]\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/fetch.txt[]\n+\n BUGS\n ----\n Using --recurse-submodules can only fetch new commits in submodules that are\ndiff --git a/Documentation/git-init.txt b/Documentation/git-init.txt\nindex ad921fe782e..160dea1372c 100644\n--- a/Documentation/git-init.txt\n+++ b/Documentation/git-init.txt\n@@ -169,6 +169,13 @@ $ git commit <3>\n <2> Add all existing files to the index.\n <3> Record the pristine state as the first commit in the history.\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/init.txt[]\n+\n GIT\n ---\n Part of the linkgit:git[1] suite\ndiff --git a/Documentation/git-switch.txt b/Documentation/git-switch.txt\nindex bbcbdceb459..c60fc9c138b 100644\n--- a/Documentation/git-switch.txt\n+++ b/Documentation/git-switch.txt\n@@ -265,6 +265,13 @@ always create a new name for it (without switching away):\n $ git switch -c good-surprises\n ------------\n \n+CONFIGURATION\n+-------------\n+\n+include::includes/cmd-config-section-all.txt[]\n+\n+include::config/checkout.txt[]\n+\n SEE ALSO\n --------\n linkgit:git-checkout[1],\n-- \n2.37.3.1490.g9adf4224da0\n\n"},{"id":"462706","messageId":"CAHd-oW71qvhG16YtMweA26SDCLKn+LHZe13njn18CD==9Ewbnw@mail.gmail.com","threadId":"58160","inReplyTo":"cover-v4-0.9-00000000000-20220907T082419Z-avarab@gmail.com","subject":"Re: [PATCH v4 0/9] docs: de-duplicate sections, add more CONFIGURATION sections","fromName":"Matheus Tavares","fromEmail":"matheus.bernardino@usp.br","sentAt":"2022-09-07T11:51:48Z","receivedAt":"2022-09-07T11:52:06Z","isPatch":true,"sender":{"key":"matheus.tavb@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12701583?v=4"},"body":"On Wed, Sep 7, 2022 at 5:27 AM Ævar Arnfjörð Bjarmason wrote:\n>\n> This series:\n>\n> * De-duplicates and combines configuration discussion that was split\n> or spread across Documentation/config/*.txt and\n> Documentation/git-*.txt, moving it to Documentation/config/*.txt.\n>\n> * Includes that relevant Documentation/config/*.txt in the\n> Documentation/git-*.txt files.\n>\n> * Introduces and uses included prose for those \"CONFIGURATION\"\n> sections in various Documentation/git-*.txt files, informing the\n> reader that what they see there is included from \"git-config(1)\".\n>\n> This v4 addresses the feedback from Matheus Tavares on v3 (thanks for\n> the review!): A hunk belonged in 9/9, not 8/9 (init's config is used\n> by e.g. \"clone\" too). The end-state at the end of this series is\n> exactly the same.\n\nThis version LGTM. Thanks!\n"},{"id":"462735","messageId":"xmqqy1uvxhdz.fsf@gitster.g","threadId":"58160","inReplyTo":"CAHd-oW71qvhG16YtMweA26SDCLKn+LHZe13njn18CD==9Ewbnw@mail.gmail.com","subject":"Re: [PATCH v4 0/9] docs: de-duplicate sections, add more CONFIGURATION sections","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-09-07T16:45:44Z","receivedAt":"2022-09-07T16:46:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Matheus Tavares writes:\n\n> On Wed, Sep 7, 2022 at 5:27 AM Ævar Arnfjörð Bjarmason wrote:\n>>\n>> This series:\n>>\n>> * De-duplicates and combines configuration discussion that was split\n>> or spread across Documentation/config/*.txt and\n>> Documentation/git-*.txt, moving it to Documentation/config/*.txt.\n>>\n>> * Includes that relevant Documentation/config/*.txt in the\n>> Documentation/git-*.txt files.\n>>\n>> * Introduces and uses included prose for those \"CONFIGURATION\"\n>> sections in various Documentation/git-*.txt files, informing the\n>> reader that what they see there is included from \"git-config(1)\".\n>>\n>> This v4 addresses the feedback from Matheus Tavares on v3 (thanks for\n>> the review!): A hunk belonged in 9/9, not 8/9 (init's config is used\n>> by e.g. \"clone\" too). The end-state at the end of this series is\n>> exactly the same.\n>\n> This version LGTM. Thanks!\n\nThanks, both.\n"}]}