This series: * De-duplicates and combines configuration discussion that was split or spread across Documentation/config/*.txt and Documentation/git-*.txt, moving it to Documentation/config/*.txt. * Includes that relevant Documentation/config/*.txt in the Documentation/git-*.txt files. * Introduces and uses included prose for those "CONFIGURATION" sections in various Documentation/git-*.txt files, informing the reader that what they see there is included from "git-config(1)". This v3 attempts to address all the feedback on v2. I think this should be good for merging down at this point. Sorry about the late re-roll. Ævar Arnfjörð Bjarmason (9): docs: add and use include template for config/* includes grep docs: de-duplicate configuration sections send-email docs: de-duplicate configuration sections apply docs: de-duplicate configuration sections notes docs: de-duplicate and combine configuration sections difftool docs: de-duplicate configuration sections log docs: de-duplicate configuration sections docs: add CONFIGURATION sections that map to a built-in docs: add CONFIGURATION sections that fuzzy map to built-ins Documentation/Makefile | 1 + Documentation/config/diff.txt | 15 ----- Documentation/config/difftool.txt | 28 +++++++++- Documentation/config/grep.txt | 7 ++- Documentation/config/log.txt | 4 ++ Documentation/config/notes.txt | 43 +++++++++------ Documentation/config/sendemail.txt | 40 +++++++++++++- Documentation/git-add.txt | 7 +++ Documentation/git-am.txt | 7 +++ Documentation/git-apply.txt | 10 +--- Documentation/git-blame.txt | 6 ++ Documentation/git-branch.txt | 4 ++ Documentation/git-checkout.txt | 7 +++ Documentation/git-clean.txt | 7 +++ Documentation/git-clone.txt | 9 +++ Documentation/git-column.txt | 7 +++ Documentation/git-commit-graph.txt | 7 +++ Documentation/git-commit.txt | 4 ++ Documentation/git-diff.txt | 7 +++ Documentation/git-difftool.txt | 27 ++------- Documentation/git-fast-import.txt | 7 +++ Documentation/git-fetch.txt | 7 +++ Documentation/git-fsck.txt | 2 + Documentation/git-gc.txt | 3 +- Documentation/git-grep.txt | 29 +--------- Documentation/git-imap-send.txt | 2 + Documentation/git-init.txt | 7 +++ Documentation/git-log.txt | 46 ++-------------- Documentation/git-mailinfo.txt | 7 +++ Documentation/git-maintenance.txt | 7 +++ Documentation/git-merge.txt | 5 +- Documentation/git-mergetool.txt | 3 + Documentation/git-notes.txt | 55 ++----------------- Documentation/git-push.txt | 7 +++ Documentation/git-rebase.txt | 2 + Documentation/git-revert.txt | 7 +++ Documentation/git-send-email.txt | 36 +----------- Documentation/git-show-branch.txt | 7 +++ Documentation/git-stash.txt | 7 +++ Documentation/git-switch.txt | 7 +++ .../includes/cmd-config-section-all.txt | 3 + .../includes/cmd-config-section-rest.txt | 3 + 42 files changed, 280 insertions(+), 226 deletions(-) create mode 100644 Documentation/includes/cmd-config-section-all.txt create mode 100644 Documentation/includes/cmd-config-section-rest.txt Range-diff against v2: 1: ef6fa5450e7 ! 1: da21c19978c docs: add and use include template for config/* includes @@ Documentation/includes/cmd-config-section-all.txt (new) ## Documentation/includes/cmd-config-section-rest.txt (new) ## @@ -+The discussion above this line is unique to this documentation, but -+everything below is included from section(s) in linkgit:git-config[1] -+aplicable to this command: ++Everything above this line in this section isn't included from the ++linkgit:git-config[1] documentation. The content that follows is the ++same as what's found there: 2: 5f07f87710c = 2: d16e927caa2 grep docs: de-duplicate configuration sections 3: 8138dc54e3e = 3: c36feb6f35a send-email docs: de-duplicate configuration sections 4: b9750ae43e1 = 4: 5707c9dd635 apply docs: de-duplicate configuration sections 5: 1b6c8c75df7 ! 5: 5b0ea00aa33 notes docs: de-duplicate configuration sections @@ Metadata Author: Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> ## Commit message ## - notes docs: de-duplicate configuration sections + notes docs: de-duplicate and combine configuration sections - Let's also fix the "git-notes(1)" docs so that we link to - "git-config(1)", not "git-log(1)" as a reference for the "notes" docs. + Combine the various "notes" configuration sections spread across + Documentation/config/notes.txt and Documentation/git-notes.txt to live + in the former, and to be included in the latter. + + We'll now forward link from "git notes" to the "CONFIGURATION" section + below, rather than to "git-config(1)" when discussing configuration + variables that are (also) discussed in that section. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> @@ Documentation/git-notes.txt: using the `--notes` option. Such notes are added as To change which notes are shown by 'git log', see the -"notes.displayRef" configuration in linkgit:git-log[1]. -+"notes.displayRef" configuration in linkgit:git-config[1]. ++"notes.displayRef" discussion in <<CONFIGURATION>>. See the "notes.rewrite.<command>" configuration for a way to carry notes across commands that rewrite commits. +@@ Documentation/git-notes.txt: with 'git log', so if you use such notes, you'll probably need to write + some special-purpose tools to do something useful with them. + + ++[[CONFIGURATION]] + CONFIGURATION + ------------- + @@ Documentation/git-notes.txt: core.notesRef:: This setting can be overridden through the environment and command line. 6: b3a5ea46bb5 = 6: c4c3fa14190 difftool docs: de-duplicate configuration sections 7: 08d98767384 ! 7: e07585ba085 log docs: de-duplicate configuration sections @@ Commit message Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> ## Documentation/config/log.txt ## -@@ --log.abbrevCommit:: -- If true, makes linkgit:git-log[1], linkgit:git-show[1], and -- linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may -- override this option with `--no-abbrev-commit`. -- - log.date:: +@@ Documentation/config/log.txt: log.date:: Set the default date-time mode for the 'log' command. Setting a value for log.date is similar to using 'git log''s `--date` option. See linkgit:git-log[1] for details. @@ Documentation/config/log.txt log.decorate:: Print out the ref names of any commits that are shown by the log -@@ Documentation/config/log.txt: log.showRoot:: - Tools like linkgit:git-log[1] or linkgit:git-whatchanged[1], which - normally hide the root commit will now show it. True by default. - -+log.abbrevCommit:: -+ If true, makes linkgit:git-log[1], linkgit:git-show[1], and -+ linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may -+ override this option with `--no-abbrev-commit`. -+ - log.showSignature:: - If true, makes linkgit:git-log[1], linkgit:git-show[1], and - linkgit:git-whatchanged[1] assume `--show-signature`. -@@ Documentation/config/log.txt: log.mailmap:: - If true, makes linkgit:git-log[1], linkgit:git-show[1], and - linkgit:git-whatchanged[1] assume `--use-mailmap`, otherwise - assume `--no-use-mailmap`. True by default. -++ -+The behavior of `log.mailmap` is impacted by the setting of the more -+general 'mailmap.*' configuration variables, i.e. `mailmap.file` and -+`mailmap.blob`. ## Documentation/git-log.txt ## -@@ Documentation/git-log.txt: OPTIONS - shown. The option `--decorate` is short-hand for `--decorate=short`. - Default to configuration value of `log.decorate` if configured, - otherwise, `auto`. -++ -+This output may be colored. See `color.ui` in linkgit:git-config[1] -+and `color.decorate` there and in the "CONFIGURATION" section below. - - --decorate-refs=<pattern>:: - --decorate-refs-exclude=<pattern>:: @@ Documentation/git-log.txt: i18n.logOutputEncoding:: Defaults to the value of `i18n.commitEncoding` if set, and UTF-8 otherwise. 8: 5c379ab1476 ! 8: af912e9ca65 docs: add CONFIGURATION sections that map to a built-in @@ Documentation/git-commit-graph.txt: $ git show-ref -s | git commit-graph write - +include::config/commitgraph.txt[] + - GIT - --- + FILE FORMAT + ----------- ## Documentation/git-commit.txt ## @@ Documentation/git-commit.txt: The editor used to edit the commit log message will be chosen from the @@ Documentation/git-fast-import.txt: operator can use this facility to peek at the -------- linkgit:git-fast-export[1] + ## Documentation/git-init.txt ## +@@ Documentation/git-init.txt: $ git commit <3> + <2> Add all existing files to the index. + <3> Record the pristine state as the first commit in the history. + ++CONFIGURATION ++------------- ++ ++include::includes/cmd-config-section-all.txt[] ++ ++include::config/init.txt[] ++ + GIT + --- + Part of the linkgit:git[1] suite + ## Documentation/git-mailinfo.txt ## @@ Documentation/git-mailinfo.txt: If no such configuration option has been set, `warn` will be used. <patch>:: 9: 91689154926 ! 9: 5ef36654bba docs: add CONFIGURATION sections that fuzzy map to built-ins @@ Commit message * config/blame.txt: used by git-{blame,annotate}.txt. Since the git-annotate(1) documentation refers to git-blame(1) don't add a - "CONFIGURATION" section to git-annotate(1), only to git-blame(1)> + "CONFIGURATION" section to git-annotate(1), only to git-blame(1). - * config/branch.txt: maps to both git-checkout.txt and + * config/checkout.txt: maps to both git-checkout.txt and git-switch.txt (but nothing else). * config/init.txt: should be included in git-init(1) and @@ Commit message Things that are being left out, and why: - * config/remote.txt: let's not include this in - git-{fetch,remote,push}.txt etc. for now, various options there - change their behavior. - - * config/remotes.txt: As we're not including config/remote.txt for - now, let's not include this one either. - - * config/credential.txt: let's not include this in - git-credential.txt, it talks more generally about how the - credential facility is used by various other commands, not that - command in particular. + * config/{remote,remotes,credential}.txt: Configuration that affects + how we talk to remote repositories is harder to untangle. We'll need + to include some of this in git-{fetch,remote,push,ls-remote}.txt + etc., but some of those only use a small subset of these + options. Let's leave this for now. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> -- 2.37.3.1406.g184357183a6