git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v3 0/9] docs: de-duplicate sections, add more CONFIGURATION sections

From
Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date
Aug 31, 2022, 08:41 UTC
Message-ID
<cover-v3-0.9-00000000000-20220831T083759Z-avarab@gmail.com>
In-Reply-To
<cover-v2-0.9-00000000000-20220729T081959Z-avarab@gmail.com>
This series:
 * De-duplicates and combines configuration discussion that was split
   or spread across Documentation/config/*.txt and
   Documentation/git-*.txt, moving it to Documentation/config/*.txt.
 * Includes that relevant Documentation/config/*.txt in the
   Documentation/git-*.txt files.
 * Introduces and uses included prose for those "CONFIGURATION"
   sections in various Documentation/git-*.txt files, informing the
   reader that what they see there is included from "git-config(1)".

This v3 attempts to address all the feedback on v2. I think this should be good for merging down at this point. Sorry about the late re-roll.

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

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.