Documentation/notes: clean up description of rewriting configuration

Clarify that the GIT_NOTES_REWRITE_REFS environment variable
overrides both ‘[notes "rewrite"] <command>’ and ‘[notes] rewriteRef’.

Add explanations of GIT_NOTES_REWRITE_MODE and GIT_NOTES_REWRITE_REFS
to the ENVIRONMENT section.

Cc: Leif Arne Storset <lstorset@opera.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 7856b286f72e13a367e16ccf4e84870e69186cae..d868535ee9a99b59f1a55d9ce872e2a1c9ded66a 100644 (file)
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -38,9 +38,8 @@ message, after an unindented line saying "Notes (<refname>):" (or
 To change which notes are shown by 'git log', see the
 "notes.displayRef" configuration in linkgit:git-log[1].
 
-See the description of "notes.rewrite.<command>" in
-linkgit:git-config[1] for a way of carrying your notes across commands
-that rewrite commits.
+See the "notes.rewrite.<command>" configuration for a way to carry
+notes across commands that rewrite commits.
 
 
 SUBCOMMANDS
@@ -206,33 +205,31 @@ notes.displayRef::
 
 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 by the 'GIT_NOTES_REWRITE_REF'
+environment variable.
 
 notes.rewriteMode::
-       When copying notes during a rewrite (see the
-       "notes.rewrite.<command>" option), determines what to do if
-       the target commit already has a note.  Must be one of
-       `overwrite`, `concatenate`, or `ignore`.  Defaults to
-       `concatenate`.
+       When copying notes during a rewrite, what to do if the target
+       commit already has a note.  Must be one of `overwrite`,
+       `concatenate`, and `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.  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.
 +
-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.
 
 
 ENVIRONMENT
@@ -252,6 +249,20 @@ ENVIRONMENT
 A warning will be issued for refs that do not exist, but a glob that
 does not match any refs is silently ignored.
 
+'GIT_NOTES_REWRITE_MODE'::
+       When copying notes during a rewrite, what to do if the target
+       commit already has a note.
+       Must be one of `overwrite`, `concatenate`, and `ignore`.
+       This overrides the `core.rewriteMode` setting.
+
+'GIT_NOTES_REWRITE_REF'::
+       When rewriting commits, which notes to copy from the original
+       to the rewritten commit.  Must be a colon-delimited list of
+       refs or globs.
++
+If not set in the environment, the list of notes to copy depends
+on the `notes.rewrite.<command>` and `notes.rewriteRef` settings.
+
 
 Author
 ------