notes docs: de-duplicate and combine configuration sections

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>
Reviewed-by: Matheus Tavares <matheus.bernardino@usp.br>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt
index aeef56d49ae97dc0df99b1e63f0a842f36f3142e..c7c4811734b5c935c89b52eb3b3ddef58f49689d 100644 (file)
--- a/Documentation/config/notes.txt
+++ b/Documentation/config/notes.txt
@@ -3,6 +3,9 @@ notes.mergeStrategy::
        conflicts.  Must be one of `manual`, `ours`, `theirs`, `union`, or
        `cat_sort_uniq`.  Defaults to `manual`.  See "NOTES MERGE STRATEGIES"
        section of linkgit:git-notes[1] for more information on each strategy.
++
+This setting can be overridden by passing the `--strategy` option to
+linkgit:git-notes[1].
 
 notes.<name>.mergeStrategy::
        Which merge strategy to choose when doing a notes merge into
@@ -11,28 +14,35 @@ notes.<name>.mergeStrategy::
        linkgit:git-notes[1] for more information on the available strategies.
 
 notes.displayRef::
-       The (fully qualified) refname from which to show notes when
-       showing commit messages.  The value of this variable can be set
-       to a glob, in which case notes from all matching refs will be
-       shown.  You may also specify this configuration variable
-       several times.  A warning will be issued for refs that do not
-       exist, but a glob that does not match any refs is silently
-       ignored.
+       Which ref (or refs, if a glob or specified more than once), in
+       addition to the default set by `core.notesRef` or
+       `GIT_NOTES_REF`, to read notes from when showing commit
+       messages with the 'git log' family of commands.
 +
 This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`
 environment variable, which must be a colon separated list of refs or
 globs.
 +
+A warning will be issued for refs that do not exist,
+but a glob that does not match any refs is silently ignored.
++
+This setting can be disabled by the `--no-notes` option to the 'git
+log' family of commands, or by the `--notes=<ref>` option accepted by
+those commands.
++
 The effective value of "core.notesRef" (possibly overridden by
 GIT_NOTES_REF) is also implicitly added to the list of refs to be
 displayed.
 
 notes.rewrite.<command>::
        When rewriting commits with <command> (currently `amend` or
-       `rebase`) and this variable is set to `true`, Git
-       automatically copies your notes from the original to the
-       rewritten commit.  Defaults to `true`, but see
-       "notes.rewriteRef" below.
+       `rebase`), if this variable is `false`, git will not copy
+       notes from the original to the rewritten commit.  Defaults to
+       `true`.  See also "`notes.rewriteRef`" below.
++
+This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
+environment variable, which must be a colon separated list of refs or
+globs.
 
 notes.rewriteMode::
        When copying notes during a rewrite (see the
@@ -46,14 +56,13 @@ environment variable.
 
 notes.rewriteRef::
        When copying notes during a rewrite, specifies the (fully
-       qualified) ref whose notes should be copied.  The ref may be a
-       glob, in which case notes in all matching refs will be copied.
-       You may also specify this configuration several times.
+       qualified) ref whose notes should be copied.  May be a glob,
+       in which case notes in all matching refs will be copied.  You
+       may also specify this configuration several times.
 +
 Does not have a default value; you must configure this variable to
 enable note rewriting.  Set it to `refs/notes/commits` to enable
 rewriting for the default commit notes.
 +
-This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
-environment variable, which must be a colon separated list of refs or
-globs.
+Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.
+See `notes.rewrite.<command>` above for a further description of its format.

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index 20e87cecf4917fdbb18c2ffe675a1b2d9e4c3177..ed802bb8e12956c9ef4ab6db662303f2db95a39d 100644 (file)
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -227,19 +227,9 @@ log.showSignature::
 mailmap.*::
        See linkgit:git-shortlog[1].
 
-notes.displayRef::
-       Which refs, in addition to the default set by `core.notesRef`
-       or `GIT_NOTES_REF`, to read notes from when showing commit
-       messages with the `log` family of commands.  See
-       linkgit:git-notes[1].
-+
-May be an unabbreviated ref name or a glob and may be specified
-multiple times.  A warning will be issued for refs that do not exist,
-but a glob that does not match any refs is silently ignored.
-+
-This setting can be disabled by the `--no-notes` option,
-overridden by the `GIT_NOTES_DISPLAY_REF` environment variable,
-and overridden by the `--notes=<ref>` option.
+include::includes/cmd-config-section-rest.txt[]
+
+include::config/notes.txt[]
 
 GIT
 ---

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 0a4200674c40af473d135ccd5df129f28a684864..efbc10f0f598eccd247f13c3e5d1ecf9473a6f78 100644 (file)
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -44,7 +44,7 @@ using the `--notes` option. Such notes are added as a patch commentary
 after a three dash separator line.
 
 To change which notes are shown by 'git log', see the
-"notes.displayRef" configuration in linkgit:git-log[1].
+"notes.displayRef" discussion in <<CONFIGURATION>>.
 
 See the "notes.rewrite.<command>" configuration for a way to carry
 notes across commands that rewrite commits.
@@ -307,6 +307,7 @@ with 'git log', so if you use such notes, you'll probably need to write
 some special-purpose tools to do something useful with them.
 
 
+[[CONFIGURATION]]
 CONFIGURATION
 -------------
 
@@ -316,57 +317,9 @@ core.notesRef::
        This setting can be overridden through the environment and
        command line.
 
-notes.mergeStrategy::
-       Which merge strategy to choose by default when resolving notes
-       conflicts.  Must be one of `manual`, `ours`, `theirs`, `union`, or
-       `cat_sort_uniq`.  Defaults to `manual`.  See "NOTES MERGE STRATEGIES"
-       section above for more information on each strategy.
-+
-This setting can be overridden by passing the `--strategy` option.
-
-notes.<name>.mergeStrategy::
-       Which merge strategy to choose when doing a notes merge into
-       refs/notes/<name>.  This overrides the more general
-       "notes.mergeStrategy".  See the "NOTES MERGE STRATEGIES" section above
-       for more information on each available strategy.
-
-notes.displayRef::
-       Which ref (or refs, if a glob or specified more than once), in
-       addition to the default set by `core.notesRef` or
-       `GIT_NOTES_REF`, to read notes from when showing commit
-       messages with the 'git log' family of commands.
-       This setting can be overridden on the command line or by the
-       `GIT_NOTES_DISPLAY_REF` environment variable.
-       See linkgit:git-log[1].
-
-notes.rewrite.<command>::
-       When rewriting commits with <command> (currently `amend` or
-       `rebase`), if this variable is `false`, git will not copy
-       notes from the original to the rewritten commit.  Defaults to
-       `true`.  See also "`notes.rewriteRef`" below.
-+
-This setting can be overridden by the `GIT_NOTES_REWRITE_REF`
-environment variable.
+include::includes/cmd-config-section-rest.txt[]
 
-notes.rewriteMode::
-       When copying notes during a rewrite, what to do if the target
-       commit already has a note.  Must be one of `overwrite`,
-       `concatenate`, `cat_sort_uniq`, or `ignore`.  Defaults to
-       `concatenate`.
-+
-This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
-environment variable.
-
-notes.rewriteRef::
-       When copying notes during a rewrite, specifies the (fully
-       qualified) ref whose notes should be copied.  May be a glob,
-       in which case notes in all matching refs will be copied.  You
-       may also specify this configuration several times.
-+
-Does not have a default value; you must configure this variable to
-enable note rewriting.
-+
-Can be overridden with the `GIT_NOTES_REWRITE_REF` environment variable.
+include::config/notes.txt[]
 
 
 ENVIRONMENT