[PATCH 1/4] Documentation/notes: describe effect of environment and configuration

[Jonathan Nieder <jrnieder@gmail.com>]

Based on the description from Documentation/config.txt.

For now, this does not share text with Documentation/config.txt
because that makes it easier to think about how to describe the
environment variables.

Cc: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-notes.txt |   82 +++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 82 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 4e5113b..b26598e 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -135,6 +135,88 @@ usual rules (see linkgit:git-commit[1]).  These details may change in
 the future.
 
 
+CONFIGURATION
+-------------
+
+core.notesRef::
+	By default, 'git notes' and other commands read and manipulate
+	the notes referred to by `refs/notes/commits`.  This
+	configuration item allows one to specify an alternative
+	default ref (to be overridden by environment variables or
+	command-line options).
+
+notes.displayRef::
+	Which refs, in addition to the default set by `core.notesRef`
+	or 'GIT_NOTES_REF', for 'git log' to read notes from when
+	showing commit messages.  Can be a (fully qualified) ref name
+	or glob.  You may also specify this configuration variable
+	several times.
++
+This setting can be overridden with the 'GIT_NOTES_DISPLAY_REF'
+environment variable.
+
+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.
+
+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`, 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.  Configure this variable to enable note
+rewriting.
++
+Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable.
+
+See linkgit:git-config[1] for details.
+
+ENVIRONMENT
+-----------
+
+'GIT_NOTES_REF'::
+	Which ref to manipulate notes from, instead of `refs/notes/commits`.
+	This overrides the `core.notesRef` setting.
+
+'GIT_NOTES_DISPLAY_REF'::
+	Which refs, in addition to the default from `core.notesRef` or
+	'GIT_NOTES_REF', to read notes from when showing commit
+	messages.
+	Must be a colon-delimited list of refs or globs.
+	This overrides the `notes.displayRef` setting.
++
+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`, or `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 will depend
+on the `notes.rewrite.<command>` and `notes.rewriteRef` settings.
+
+
 Author
 ------
 Written by Johannes Schindelin <johannes.schindelin@gmx.de> and
-- 
1.7.1