[PATCH v2 0/8] filling out the notes man page

[PATCH v2 0/8] filling out the notes man page

[Jonathan Nieder]

Hi,

Many thanks for the feedback from last round[1].  I tried to take your
comments to heart and carry them out as well as I could.  I hope you
like the result.  Doubtless some of the new text I added is unclear,
so as usual, your comments are welcome.

The first two patches sum up the low-level basics that a reader should
know.  For the format of trees, I renamed the NOTES section to
DISCUSSION and added a paragraph or two (and a footnote, triggering a
bug in docbook-xsl; more on that later); for the format of notes
blobs, I added an example to illustrate Johan’s trick for arbitrary
binary notes.  Thanks for the tip.

The next five patches aim to make the treatment of configuration a
little more systematic.  git-notes.1 gains Configuration and
Environment sections and git-log.1 gains a Configuration section (but
not Environment, because I am lazy).

Of course, there is a lot still to document.  It is not obvious to me
yet what relationship notes will have to other commands, such as
format-patch.

Thanks,
Jonathan Nieder (8):
  Documentation/notes: document format of notes trees
  Documentation/notes: describe content of notes blobs
  Documentation/notes: add configuration section
  Documentation/notes: simplify treatment of default notes ref
  Documentation/log: add a CONFIGURATION section
  Documentation/notes: simplify treatment of default display refs
  Documentation/notes: clean up description of rewriting configuration
  Documentation/notes: nitpicks

 Documentation/config.txt    |   16 +---
 Documentation/git-log.txt   |   42 ++++++++++
 Documentation/git-notes.txt |  177 +++++++++++++++++++++++++++++++++++++------
 t/t3307-notes-man.sh        |   38 +++++++++
 4 files changed, 238 insertions(+), 35 deletions(-)
 create mode 100755 t/t3307-notes-man.sh

[1] http://thread.gmane.org/gmane.comp.version-control.git/146269

[PATCH 1/8] Documentation/notes: document format of notes trees

[Jonathan Nieder]

Separate the specification of the notes format exposed in
git-config.1 from the description of the option; or in other
words, move the explanation for what to expect to find at
refs/notes/commits from git-config.1 to git-notes.1.

Suggested-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
How well does ‘git notes’ handle notes trees without a commit
currently?  I remembered some rumor about a commitless mode in which
the only history is the reflog, but I am not sure how much of that is
implemented yet and I did not check.

If it was only groundless rumor (read: I made it up), then the last
paragraph of the discussion should be removed.

 Documentation/config.txt    |   16 +++++-----------
 Documentation/git-notes.txt |   30 +++++++++++++++++++++---------
 2 files changed, 26 insertions(+), 20 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 8f86050..cc4bc20 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -518,18 +518,12 @@ check that makes sure that existing object files will not get overwritten.
 
 core.notesRef::
 	When showing commit messages, also show notes which are stored in
-	the given ref.  This ref is expected to contain files named
-	after the full SHA-1 of the commit they annotate.  The ref
-	must be fully qualified.
+	the given ref.  The ref must be fully qualified.  If the given
+	ref does not exist, it is not an error but means that no
+	notes should be printed.
 +
-If such a file exists in the given ref, the referenced blob is read, and
-appended to the commit message, separated by a "Notes (<refname>):"
-line (shortened to "Notes:" in the case of "refs/notes/commits").  If the
-given ref itself does not exist, it is not an error, but means that no
-notes should be printed.
-+
-This setting defaults to "refs/notes/commits", and can be overridden by
-the `GIT_NOTES_REF` environment variable.
+This setting defaults to "refs/notes/commits", and it can be overridden by
+the 'GIT_NOTES_REF' environment variable.  See linkgit:git-notes[1].
 
 core.sparseCheckout::
 	Enable "sparse checkout" feature. See section "Sparse checkout" in
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 4e5113b..af12c3c 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -28,7 +28,7 @@ to change the commit itself. Such commit notes can be shown by `git log`
 along with the original commit message. To discern these notes from the
 message stored in the commit object, the notes are indented like the
 message, after an unindented line saying "Notes (<refname>):" (or
-"Notes:" for the default setting).
+"Notes:" for `refs/notes/commits`).
 
 This command always manipulates the notes specified in "core.notesRef"
 (see linkgit:git-config[1]), which can be overridden by GIT_NOTES_REF.
@@ -122,17 +122,29 @@ OPTIONS
 	is taken to be in `refs/notes/` if it is not qualified.
 
 
-NOTES
------
+DISCUSSION
+----------
+
+Commit notes are blobs containing extra information about an object
+(usually information to supplement a commit's message).  These blobs
+are taken from notes refs.  A notes ref is usually a branch which
+contains "files" whose paths are the object names for the objects
+they describe, with some directory separators included for performance
+reasons footnote:[Permitted pathnames have the form
+'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory
+names of two hexadecimal digits each followed by a filename with the
+rest of the object ID.].
 
 Every notes change creates a new commit at the specified notes ref.
 You can therefore inspect the history of the notes by invoking, e.g.,
-`git log -p notes/commits`.
-
-Currently the commit message only records which operation triggered
-the update, and the commit authorship is determined according to the
-usual rules (see linkgit:git-commit[1]).  These details may change in
-the future.
+`git log -p notes/commits`.  Currently the commit message only records
+which operation triggered the update, and the commit authorship is
+determined according to the usual rules (see linkgit:git-commit[1]).
+These details may change in the future.
+
+It is also permitted for a notes ref to point directly to a tree
+object, in which case the history of the notes can be read with
+`git log -p -g <refname>`.
 
 
 Author
-- 
1.7.1

[PATCH 2/8] Documentation/notes: describe content of notes blobs

[Jonathan Nieder]

stripspace/text-based formatting kicks in when specifying the notes
content with -m or -F, or when an editor is used to edit the notes.
To binary-safely create notes from files, the following construct is
required:

    git notes add -C $(git hash-object -w <file>) <object>

Explain this trick (thanks, Johan!) in the manual.  Add an ordinary
example, too, to keep this esoteric one company.

Cc: Johan Herland <johan@herland.net>
Cc: Thomas Rast <trast@student.ethz.ch>
Cc: Jeff King <peff@peff.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-notes.txt |   38 +++++++++++++++++++++++++++++++++++++-
 t/t3307-notes-man.sh        |   38 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+), 1 deletions(-)
 create mode 100755 t/t3307-notes-man.sh

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index af12c3c..97b9d81 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -101,15 +101,20 @@ OPTIONS
 	Use the given note message (instead of prompting).
 	If multiple `-m` options are given, their values
 	are concatenated as separate paragraphs.
+	Lines starting with `#` and empty lines other than a
+	single line between paragraphs will be stripped out.
 
 -F <file>::
 --file=<file>::
 	Take the note message from the given file.  Use '-' to
 	read the note message from the standard input.
+	Lines starting with `#` and empty lines other than a
+	single line between paragraphs will be stripped out.
 
 -C <object>::
 --reuse-message=<object>::
-	Reuse the note message from the given note object.
+	Take the note message from the given blob object (for
+	example, another note).
 
 -c <object>::
 --reedit-message=<object>::
@@ -147,6 +152,37 @@ object, in which case the history of the notes can be read with
 `git log -p -g <refname>`.
 
 
+EXAMPLES
+--------
+
+You can use notes to add annotations with information that was not
+available at the time a commit was written.
+
+------------
+$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2
+$ git show -s 72a144e
+[...]
+    Signed-off-by: Junio C Hamano <gitster@pobox.com>
+
+Notes:
+    Tested-by: Johannes Sixt <j6t@kdbg.org>
+------------
+
+In principle, a note is a regular Git blob, and any kind of
+(non-)format is accepted.  You can binary-safely create notes from
+arbitrary files using 'git hash-object':
+
+------------
+$ cc *.c
+$ blob=$(git hash-object -w a.out)
+$ git notes --ref=built add -C "$blob" HEAD
+------------
+
+Of course, it doesn't make much sense to display non-text-format notes
+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.
+
+
 Author
 ------
 Written by Johannes Schindelin <johannes.schindelin@gmx.de> and
diff --git a/t/t3307-notes-man.sh b/t/t3307-notes-man.sh
new file mode 100755
index 0000000..3269f2e
--- /dev/null
+++ b/t/t3307-notes-man.sh
@@ -0,0 +1,38 @@
+#!/bin/sh
+
+test_description='Examples from the git-notes man page
+
+Make sure the manual is not full of lies.'
+
+. ./test-lib.sh
+
+test_expect_success 'setup' '
+	test_commit A &&
+	test_commit B &&
+	test_commit C
+'
+
+test_expect_success 'example 1: notes to add an Acked-by line' '
+	cat <<-\EOF >expect &&
+	    B
+
+	Notes:
+	    Acked-by: A C Ker <acker@example.com>
+	EOF
+	git notes add -m "Acked-by: A C Ker <acker@example.com>" B &&
+	git show -s B^{commit} >log &&
+	tail -n 4 log >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'example 2: binary notes' '
+	cp "$TEST_DIRECTORY"/test4012.png .
+	git checkout B &&
+	blob=$(git hash-object -w test4012.png) &&
+	git notes --ref=logo add -C "$blob" &&
+	git notes --ref=logo copy B C &&
+	git notes --ref=logo show C >actual &&
+	test_cmp test4012.png actual
+'
+
+test_done
-- 
1.7.1

[PATCH 3/8] Documentation/notes: add configuration section

[Jonathan Nieder]

Copy the descriptions of configuration variables from git-config.1.
Once the descriptions have been ironed out, it would be nice to
refactor them to share text, but for now it is simplest to experiment
with separate copies.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
This is straight copy and paste.

 Documentation/git-notes.txt |   59 +++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 59 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 97b9d81..f561457 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -183,6 +183,65 @@ 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
+-------------
+
+core.notesRef::
+	When showing commit messages, also show notes which are stored in
+	the given ref.  The ref must be fully qualified.  If the given
+	ref does not exist, it is not an error but means that no
+	notes should be printed.
++
+This setting defaults to "refs/notes/commits", and it can be overridden by
+the 'GIT_NOTES_REF' environment variable.  See linkgit:git-notes[1].
+
+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.
++
+This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`
+environment variable, which must be a colon separated list of refs or
+globs.
++
+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.
+
+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`.
++
+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.
++
+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.
+
 Author
 ------
 Written by Johannes Schindelin <johannes.schindelin@gmx.de> and
-- 
1.7.1

[PATCH 4/8] Documentation/notes: simplify treatment of default notes ref

[Jonathan Nieder]

Separate the documentation of the semantics, command-line option,
configuration item, and environment variable for the default notes
ref.  The documentation is easier to digest in bite-sized pieces.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-notes.txt |   31 ++++++++++++++++++++-----------
 1 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index f561457..28ac862 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -23,6 +23,11 @@ DESCRIPTION
 This command allows you to add/remove notes to/from objects, without
 changing the objects themselves.
 
+By default, notes are saved to and read from `refs/notes/commits`, but
+this default can be overridden.  See the OPTIONS, CONFIGURATION, and
+ENVIRONMENT sections below.  If this ref does not exist, it will be
+quietly created when it is first needed to store a note.
+
 A typical use of notes is to extend a commit message without having
 to change the commit itself. Such commit notes can be shown by `git log`
 along with the original commit message. To discern these notes from the
@@ -30,8 +35,6 @@ message stored in the commit object, the notes are indented like the
 message, after an unindented line saying "Notes (<refname>):" (or
 "Notes:" for `refs/notes/commits`).
 
-This command always manipulates the notes specified in "core.notesRef"
-(see linkgit:git-config[1]), which can be overridden by GIT_NOTES_REF.
 To change which notes are shown by 'git-log', see the
 "notes.displayRef" configuration.
 
@@ -122,8 +125,8 @@ OPTIONS
 	the user can further edit the note message.
 
 --ref <ref>::
-	Manipulate the notes tree in <ref>.  This overrides both
-	GIT_NOTES_REF and the "core.notesRef" configuration.  The ref
+	Manipulate the notes tree in <ref>.  This overrides
+	'GIT_NOTES_REF' and the "core.notesRef" configuration.  The ref
 	is taken to be in `refs/notes/` if it is not qualified.
 
 
@@ -187,13 +190,10 @@ CONFIGURATION
 -------------
 
 core.notesRef::
-	When showing commit messages, also show notes which are stored in
-	the given ref.  The ref must be fully qualified.  If the given
-	ref does not exist, it is not an error but means that no
-	notes should be printed.
-+
-This setting defaults to "refs/notes/commits", and it can be overridden by
-the 'GIT_NOTES_REF' environment variable.  See linkgit:git-notes[1].
+	Notes ref to read and manipulate instead of
+	`refs/notes/commits`.  Must be an unabbreviated ref name.
+	This setting can be overridden through the environment and
+	command line.
 
 notes.displayRef::
 	The (fully qualified) refname from which to show notes when
@@ -242,6 +242,15 @@ This setting can be overridden with the `GIT_NOTES_REWRITE_REF`
 environment variable, which must be a colon separated list of refs or
 globs.
 
+
+ENVIRONMENT
+-----------
+
+'GIT_NOTES_REF'::
+	Which ref to manipulate notes from, instead of `refs/notes/commits`.
+	This overrides the `core.notesRef` setting.
+
+
 Author
 ------
 Written by Johannes Schindelin <johannes.schindelin@gmx.de> and
-- 
1.7.1

[PATCH 5/8] Documentation/log: add a CONFIGURATION section

[Jonathan Nieder]

Add a configuration section summarizing variables that affect the
log family of commands.

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

diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index fb184ba..d7f6a9c 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -132,6 +132,48 @@ Discussion
 
 include::i18n.txt[]
 
+Configuration
+-------------
+
+See linkgit:git-config[1] for core variables and linkgit:git-diff[1]
+for settings related to diff generation.
+
+format.pretty::
+	Default for the `--format` option.  (See "PRETTY FORMATS" above.)
+	Defaults to "medium".
+
+i18n.logOutputEncoding::
+	Encoding to use when displaying logs.  (See "Discussion", above.)
+	Defaults to the value of `i18n.commitEncoding` if set, UTF-8
+	otherwise.
+
+log.date::
+	Default format for human-readable dates.  (Compare the
+	`--date` option.)  Defaults to "default", which means to write
+	dates like `Sat May 8 19:35:34 2010 -0500`.
+
+log.showroot::
+	If `false`, 'git log' and related commands will not treat the
+	initial commit as a big creation event.  Any root commits in
+	`git log -p` output would be shown without a diff attached.
+	The default is `true`.
+
+mailmap.file::
+	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-standard-notes` option,
+overridden by the 'GIT_NOTES_DISPLAY_REF' environment variable,
+and supplemented by the `--show-notes` option.
 
 Author
 ------
-- 
1.7.1

[PATCH 6/8] Documentation/notes: simplify treatment of default display refs

[Jonathan Nieder]

The main description of display refs for notes should be in
git-log.1, where there is a chance to give a leisurely description
of all the ways they can be set, what they are used for, and so
on.  The description in git-notes.1 is only meant to be a quick
reminder of how notes are used.

So simplify it.

Also add an entry for GIT_NOTES_DISPLAY_REF to the environment
section.

Cc: Thomas Rast <trast@student.ethz.ch>
Cc: Johan Herland <johan@herland.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-notes.txt |   36 +++++++++++++++++++-----------------
 1 files changed, 19 insertions(+), 17 deletions(-)

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 28ac862..7856b28 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -35,8 +35,8 @@ message stored in the commit object, the notes are indented like the
 message, after an unindented line saying "Notes (<refname>):" (or
 "Notes:" for `refs/notes/commits`).
 
-To change which notes are shown by 'git-log', see the
-"notes.displayRef" configuration.
+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
@@ -196,21 +196,13 @@ core.notesRef::
 	command line.
 
 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.
-+
-This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`
-environment variable, which must be a colon separated list of refs or
-globs.
-+
-The effective value of "core.notesRef" (possibly overridden by
-GIT_NOTES_REF) is also implicitly added to the list of refs to be
-displayed.
+	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
@@ -250,6 +242,16 @@ ENVIRONMENT
 	Which ref to manipulate notes from, instead of `refs/notes/commits`.
 	This overrides the `core.notesRef` setting.
 
+'GIT_NOTES_DISPLAY_REF'::
+	Colon-delimited list of refs or globs indicating which refs,
+	in addition to the default from `core.notesRef` or
+	'GIT_NOTES_REF', to read notes from when showing commit
+	messages.
+	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.
+
 
 Author
 ------
-- 
1.7.1

[PATCH 7/8] Documentation/notes: clean up description of rewriting configuration

[Jonathan Nieder]

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>
---
 Documentation/git-notes.txt |   47 ++++++++++++++++++++++++++----------------
 1 files changed, 29 insertions(+), 18 deletions(-)

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 7856b28..d868535 100644
--- 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
 ------
-- 
1.7.1

[PATCH 8/8] Documentation/notes: nitpicks

[Jonathan Nieder]

Spell out “or” in the NAME line and simplify the leading sentence
in the DESCRIPTION.

Some other language cleanups, too.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
As before, except the “default setting” nitpick moved to an earlier
patch.

That’s the end of the series.  Thanks for your help.

Good night,
Jonathan

 Documentation/git-notes.txt |   12 ++++++------
 1 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index d868535..de63ef0 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -3,7 +3,7 @@ git-notes(1)
 
 NAME
 ----
-git-notes - Add/inspect object notes
+git-notes - Add or inspect object notes
 
 SYNOPSIS
 --------
@@ -20,17 +20,17 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-This command allows you to add/remove notes to/from objects, without
-changing the objects themselves.
+Adds, removes, or reads notes attached to objects, without touching
+the objects themselves.
 
 By default, notes are saved to and read from `refs/notes/commits`, but
 this default can be overridden.  See the OPTIONS, CONFIGURATION, and
 ENVIRONMENT sections below.  If this ref does not exist, it will be
 quietly created when it is first needed to store a note.
 
-A typical use of notes is to extend a commit message without having
-to change the commit itself. Such commit notes can be shown by `git log`
-along with the original commit message. To discern these notes from the
+A typical use of notes is to supplement a commit message without
+changing the commit itself. Notes can be shown by 'git log' along with
+the original commit message. To distinguish these notes from the
 message stored in the commit object, the notes are indented like the
 message, after an unindented line saying "Notes (<refname>):" (or
 "Notes:" for `refs/notes/commits`).
-- 
1.7.1

Re: [PATCH 1/8] Documentation/notes: document format of notes trees

[Jeff King]

On Sat, May 08, 2010 at 10:19:35PM -0500, Jonathan Nieder wrote:

> How well does ‘git notes’ handle notes trees without a commit
> currently?  I remembered some rumor about a commitless mode in which
> the only history is the reflog, but I am not sure how much of that is
> implemented yet and I did not check.
> 
> If it was only groundless rumor (read: I made it up), then the last
> paragraph of the discussion should be removed.

My original textconv caching implementation used commitless notes. The
new version uses commits, but keeps the history truncated. As far as I
know, you can manipulate the latter with git-notes, but I haven't tried
much (adding a new note should make a history graph with length 2, which
will then get re-truncated the next time we add something to the cache
automatically). But certainly "list", "show", and "prune" should work,
which are the ones I would expect to be useful for such a cache.

> +It is also permitted for a notes ref to point directly to a tree
> +object, in which case the history of the notes can be read with
> +`git log -p -g <refname>`.

You would also use this to see the history of cache notes. They have
commits, but the only ancestry is in the reflog. So perhaps:

  Some notes refs may be "history-less", either because they point
  directly to a tree instead of a commit, or because their commits are
  truncated (the notes generated by textconv caching are an example of
  the latter). To see the local history of these refs, view the reflog
  with `git log -g <refname>`.

-Peff

Re: [PATCH 5/8] Documentation/log: add a CONFIGURATION section

[Jeff King]

On Sat, May 08, 2010 at 10:30:41PM -0500, Jonathan Nieder wrote:

> Add a configuration section summarizing variables that affect the
> log family of commands.

I think this is an improvement, but given this patch and the earlier
cut-and-paste of notes config into git-notes.txt, what do you think of
my proposal here:

  http://article.gmane.org/gmane.comp.version-control.git/145139
  [skip down to /You didn't mention configuration variables/]

I haven't actually started work on it yet, but it would simplify what
you're doing here.

-Peff

Re: [PATCH 6/8] Documentation/notes: simplify treatment of default display refs

[Jeff King]

On Sat, May 08, 2010 at 10:32:24PM -0500, Jonathan Nieder wrote:

> @@ -196,21 +196,13 @@ core.notesRef::
>  	command line.
>  
>  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.
> -+
> -This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`
> -environment variable, which must be a colon separated list of refs or
> -globs.
> -+
> -The effective value of "core.notesRef" (possibly overridden by
> -GIT_NOTES_REF) is also implicitly added to the list of refs to be
> -displayed.
> +	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].

Hmm. Both this and 4/8 rewrite bits of the configuration copied from
config.txt in an earlier patch. Do any changes need to be propagated
back to config.txt (and no, I didn't read and think carefully, so the
answer may be "no, they are now diverging intentionally")?

-Peff

Re: [PATCH 6/8] Documentation/notes: simplify treatment of default display refs

[Jonathan Nieder]

Jeff King wrote:

> Hmm. Both this and 4/8 rewrite bits of the configuration copied from
> config.txt in an earlier patch. Do any changes need to be propagated
> back to config.txt (and no, I didn't read and think carefully, so the
> answer may be "no, they are now diverging intentionally")?

Thanks for bringing this up.  I think some of the changes ultimately
ought to be propagated back to config.txt.  I copied the text anyway
because as long as the differences are in short-term memory, I find it
easier to manipulate two similar files than one file with ifdefs in
it; so it seemed like a reasonable strategy to let these diverge for a
few weeks and then merge them with ifdefs again.

Some divergence is needed imho so that the text can say things like
“see the Options section earlier in this page”.

Longer term, I suspect I would like a gitconfig.5 page that functioned
something like the main commands list, which could avoid some
duplication.  But this is something to be considered carefully: right
now it is very easy to start with knowing there is some configuration
for what you want to change (conflict hunk format, say) and find it by
searching the descriptions in git-config.1; if we split that file up,
that won’t be so easy.

  CONFIGURATION SECTIONS

  We separate the configuration into <...>.

  Core settings

      [core] (see "Core configuration", below)
          <some blurb about core commands here...>

      [user]
          Default identity to attribute new commits to.

      [url "baseaddress"] (see git-remote(1))
          Short names to use for a long, frequently-used URL.

      [alias] (see "Aliases")
          User-defined git commands that alias other git commands
          with options.

      [gc] (see git-gc(1))
          Automatic repository repacking settings.

      [http] (see git-remote-http(1))
          Tweaking HTTP transport behavior.

      [i18n] (see git-commit(1))
          Commit log encoding and display encoding.

      [notes]
      [notes "rewrite"] (see git-notes(1))
          Display and propagation of commit notes.

      [rerere] (see git-rerere(1))
          Whether to save successful merge resolutions for later
          reuse.

  Output format

      [advice] (see "Advice Options")
          Whether to display optional help messages that may
          dwarf regular output.

      [color] (see "Colored output")
          Which commands should use colored output.

      [color "gitcommand"] (see "Colored output")
          What colors to use for a particular sort of output.  The
          relevant command name is generally the most prominent git
          command which produces that output.

      [format] (see git-log(1))
	  How to display commit metadata by default.  This section is
          shared with git-format-patch(1) configuration.

      [pager] (see "Paginated output")
          Which commands should paginate their output.

  Repository setup

      [branch "branchname"] (see git-branch(1))
          Where `git pull` should pull from for each local branch.

      [remote "reponame"] (see git-remote(1))
          URL and branches for a named remote repository.

      [remotes] (see git-remote(1))
          User-defined collections of remote repositories that are
          often fetched from or pushed to together.

  Helper programs

      [web] (see git-help(1))
          Web browser to use for 'git help --web' and 'git instaweb'.

      [merge "mergedriver"] (see gitattributes(5))
          Low-level format-specific helper for merging files.

      [browser "webbrowser"] (see git-web-browse(1))
          How to invoke a given web browser.

      [man "manpager"] (see git-help(1))
          How to invoke a given man pager.

      [difftool "diffvisualizer"] (see git-difftool(1))
          How to invoke a given diff frontend.

      [mergetool "mergeresolver"] (see git-mergetool(1))
          How to invoke a given interactive 3-way merge helper.

      [guitool "guihelper"] (see git-gui(1))
          How git gui should invoke this helper when selected from
          the "Tools" menu.

  Default behavior of commands

      [add]		git-add(1)
      [am]		git-am(1)
      [apply]		git-apply(1)
      [branch]		git-branch(1)
      [clean]		git-clean(1)
      [commit]		git-commit(1)
      [diff]		git-diff(1)
      [difftool]	git-difftool(1)
      [fetch]		git-fetch-pack(1), git-fetch(1), git-pull(1)
      [format]		git-format-patch(1), git-log(1)
      [gc]		git-gc(1)
      [gitcvs]		git-cvsserver(1)
      [gui]		git-gui(1)
      [help]		git-help(1), git --help
      [imap]		git-imap-send(1)
      [init]		git-init(1)
      [instaweb]	git-instaweb(1)
      [interactive]	git-add--interactive(1), git add -i
      [log]		git-log(1), git-show(1), git-whatchanged(1)
      [mailmap]		git-shortlog(1)
      [man]		git-help(1)
      [merge]		git-merge(1), git-mergetool(1)
      [mergetool]	git-mergetool(1)
      [notes]		git-notes(1)
      [pack]		git-gc(1), git-repack(1)
      [pull]		git-pull(1)
      [push]		git-push(1)
      [receive]		git-receive-pack(1)
      [repack]		git-repack(1)
      [sendemail]	git-send-email(1)
      [sendemail "profile"]
			git-send-email(1)
      [showbranch]	git-show-branch(1)
      [status]		git-status(1)
      [tar]		git-archive(1)
      [transfer]	git-fetch-pack(1), git-receive-pack(1)

Re: [PATCH 6/8] Documentation/notes: simplify treatment of default display refs

[Jeff King]

On Sun, May 09, 2010 at 03:43:25AM -0500, Jonathan Nieder wrote:

> Thanks for bringing this up.  I think some of the changes ultimately
> ought to be propagated back to config.txt.  I copied the text anyway
> because as long as the differences are in short-term memory, I find it
> easier to manipulate two similar files than one file with ifdefs in
> it; so it seemed like a reasonable strategy to let these diverge for a
> few weeks and then merge them with ifdefs again.

Hrm. If that merge actually happens while things are still in short-term
memory. ;)

> Some divergence is needed imho so that the text can say things like
> “see the Options section earlier in this page”.

Yeah, understandable. And I also don't want to get into a rat's nest of
ifdefs in the documentation. Which is why I was pushing to move straight
into something more elegant. :)

> Longer term, I suspect I would like a gitconfig.5 page that functioned
> something like the main commands list, which could avoid some
> duplication.  But this is something to be considered carefully: right
> now it is very easy to start with knowing there is some configuration
> for what you want to change (conflict hunk format, say) and find it by
> searching the descriptions in git-config.1; if we split that file up,
> that won’t be so easy.

Yeah, I do worry about people being able to search effectively. But to
some degree, sensible naming of the options helps with that. Searching
for "conflict" even in just a list of options should come up with
"merge.conflictstyle", and I had always intended for such a gitconfig.5
to have a full list.

>   CONFIGURATION SECTIONS
>   [...]

Your breakdown looks like a sensible thing to have at the start of
gitconfig.5. It looks like you were planning on putting some generic
concepts like "alias" and "core" into that page (at the end of the
overview list), and then referring to individual command pages for their
respective sections. That sounds reasonable to me.

-Peff

Re: [PATCH v2 0/8] filling out the notes man page

[Johan Herland]

On Sunday 09 May 2010, Jonathan Nieder wrote:
> Many thanks for the feedback from last round[1].  I tried to take your
> comments to heart and carry them out as well as I could.  I hope you
> like the result.  Doubtless some of the new text I added is unclear,
> so as usual, your comments are welcome.

Thank you very much for this effort. All patches (modulo the things you're 
working out with Peff) are

Acked-By: Johan Herland <johan@herland.net>


Thanks!

...Johan

-- 
Johan Herland, <johan@herland.net>
www.herland.net

Re: [PATCH 4/8] Documentation/notes: simplify treatment of default notes ref

[Thomas Rast]

Jonathan Nieder wrote:
> @@ -187,13 +190,10 @@ CONFIGURATION
>  -------------
>  
>  core.notesRef::
> -	When showing commit messages, also show notes which are stored in
> -	the given ref.  The ref must be fully qualified.  If the given
> -	ref does not exist, it is not an error but means that no
> -	notes should be printed.
> -+
> -This setting defaults to "refs/notes/commits", and it can be overridden by
> -the 'GIT_NOTES_REF' environment variable.  See linkgit:git-notes[1].
> +	Notes ref to read and manipulate instead of
> +	`refs/notes/commits`.  Must be an unabbreviated ref name.
> +	This setting can be overridden through the environment and
> +	command line.

In the end result, this makes core.notesRef the only configuration
variable which does not have its environment sibling named explicitly
in the config section.  Would you mind putting GIT_NOTES_REF back in
the sentence for consistency with the other variables?

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: [PATCH v2 0/8] filling out the notes man page

[Thomas Rast]

Johan Herland wrote:
> On Sunday 09 May 2010, Jonathan Nieder wrote:
> > Many thanks for the feedback from last round[1].  I tried to take your
> > comments to heart and carry them out as well as I could.  I hope you
> > like the result.  Doubtless some of the new text I added is unclear,
> > so as usual, your comments are welcome.
> 
> Thank you very much for this effort. All patches (modulo the things you're 
> working out with Peff) are
> 
> Acked-By: Johan Herland <johan@herland.net>

A big "thanks" from me, too.  I admit I read the end result instead of
the series to save myself some confusion.  It's a big improvement over
the current docs.

Acked-by: Thomas Rast <trast@student.ethz.ch>

(I think some config variable unification is a good goal, but I
wouldn't let that hold back this series.)

-- 
Thomas Rast
trast@{inf,student}.ethz.ch

Re: [PATCH 4/8] Documentation/notes: simplify treatment of default notes ref

[Jonathan Nieder]

Thomas Rast wrote:

> this makes core.notesRef the only configuration
> variable which does not have its environment sibling named explicitly
> in the config section.  Would you mind putting GIT_NOTES_REF back in
> the sentence for consistency with the other variables?

No problem.  You mentioned something similar before; sorry about
missing it.

Thanks,
Jonathan

Re: [PATCH 6/8] Documentation/notes: simplify treatment of default display refs

[Jonathan Nieder]

Jeff King wrote:

> Searching
> for "conflict" even in just a list of options should come up with
> "merge.conflictstyle", and I had always intended for such a gitconfig.5
> to have a full list.

Makes sense.  So the breakdown of that page might be

  Synopsis
  Description
    Syntax
  Configuration items
    Sections
    Index
  Core configuration
  Identity
  Suppressing advice
  Command aliases
  Colored output
  Paginated output
  Examples
  See also

with the index listing all configuration items, with a short phrase
describing each.

To keep this maintainable, I would like to have a single source file
with a short and long description for each configuration item.  Then
a script would process it into an index and snippets for the relevant
command pages.

I’m anxious to get started.  Thanks for the pointers.
Jonathan

Re: [PATCH 6/8] Documentation/notes: simplify treatment of default display refs

[Jeff King]

On Wed, May 12, 2010 at 05:50:02AM -0500, Jonathan Nieder wrote:

> > Searching
> > for "conflict" even in just a list of options should come up with
> > "merge.conflictstyle", and I had always intended for such a gitconfig.5
> > to have a full list.
> 
> Makes sense.  So the breakdown of that page might be
> 
>   Synopsis
>   Description
>     Syntax
>   Configuration items
>     Sections
>     Index
>   Core configuration
>   Identity
>   Suppressing advice
>   Command aliases
>   Colored output
>   Paginated output
>   Examples
>   See also

Yes, I think that is sane. One other option would be to put a few things
like "identity" into git(1) (where it would presumably be part of an
overall identity section covering the concepts, config options, and
environment variables).

> To keep this maintainable, I would like to have a single source file
> with a short and long description for each configuration item.  Then
> a script would process it into an index and snippets for the relevant
> command pages.

My plan was to actually include the config's long description in the
relevant manpage (so it will be close to point of use, and you can see
the context while editing), and then pull the information out of each
page for the index. Adding a short description would probably be
simplest as a specially formatted comment. E.g., in git-add.txt:

   add.ignore-errors::
   // @CONFIG: ignore errors on 'git-add'
           Continue adding files when some files cannot be added due to
           indexing errors. Equivalent to using '--ignore-errors'.

and then process it with something like:

  perl -ne '
    m{^// @CONFIG: (.*)} && print "$last - $1\n"; $last = $_
  ' git-*.txt >config-index.txt

So it's sort of literate programming for documentation. :) The comment
thing is obviously a hack, but it should work well in practice. You
might be able to do some semantic markup with special attributes in
asciidoc.

> I’m anxious to get started.  Thanks for the pointers.

I'm happy you're working on this. Thanks.

-Peff

[PATCH v3] Documentation/notes: fill out the man page a little

[Jonathan Nieder]

Add some basic information to the ‘git notes’ page, mostly by moving
over information from git-config.1.  In particular, clarify that the
GIT_NOTES_REWRITE_REFS environment variable overrides both
‘[notes "rewrite"] <command>’ and ‘[notes] rewriteRef’.

Also add a Configuration section to git-log.1 for the ‘git notes’
page to refer to.

Later it would be nice to merge some changes back to git-config.1,
but one thing at a time.

Based on advice from Johan, Thomas, and Jeff.

Acked-by: Johan Herland <johan@herland.net>
Acked-by: Thomas Rast <trast@student.ethz.ch>
Cc: Jeff King <peff@peff.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
This patch is meant to replace the jn/notes-doc branch in pu.
Interdiff from last round:

  diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
  index de63ef0..1d8eef1 100644
  --- a/Documentation/git-notes.txt
  +++ b/Documentation/git-notes.txt
  @@ -149,9 +149,12 @@ which operation triggered the update, and the commit authorship is
   determined according to the usual rules (see linkgit:git-commit[1]).
   These details may change in the future.
   
  -It is also permitted for a notes ref to point directly to a tree
  -object, in which case the history of the notes can be read with
  -`git log -p -g <refname>`.
  +Some notes refs may be "history-less", either because they point
  +directly to a tree instead of a commit, or because their commits are
  +truncated; the notes generated by textconv caching
  +(see linkgit:gitattributes[5]) are an example of the latter.
  +To see the local history of these refs, view the reflog with
  +`git log -g <refname>`.
   
   
   EXAMPLES
  @@ -191,8 +194,8 @@ CONFIGURATION
   core.notesRef::
   	Notes ref to read and manipulate instead of
   	`refs/notes/commits`.  Must be an unabbreviated ref name.
  -	This setting can be overridden through the environment and
  -	command line.
  +	This setting can be overridden by the 'GIT_NOTES_REF'
  +	environment variable or the `--ref` option.
   
   notes.displayRef::
   	Which ref (or refs, if a glob or specified more than once), in

Thomas Rast wrote:

> I admit I read the end result instead of
> the series to save myself some confusion.

There’s a good reason to combine patches if I’ve ever heard one.
Thanks for noticing.

Jonathan

 Documentation/config.txt    |   16 +---
 Documentation/git-log.txt   |   42 ++++++++++
 Documentation/git-notes.txt |  180 +++++++++++++++++++++++++++++++++++++------
 t/t3307-notes-man.sh        |   38 +++++++++
 4 files changed, 241 insertions(+), 35 deletions(-)
 create mode 100755 t/t3307-notes-man.sh

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 8f86050..cc4bc20 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -518,18 +518,12 @@ check that makes sure that existing object files will not get overwritten.
 
 core.notesRef::
 	When showing commit messages, also show notes which are stored in
-	the given ref.  This ref is expected to contain files named
-	after the full SHA-1 of the commit they annotate.  The ref
-	must be fully qualified.
+	the given ref.  The ref must be fully qualified.  If the given
+	ref does not exist, it is not an error but means that no
+	notes should be printed.
 +
-If such a file exists in the given ref, the referenced blob is read, and
-appended to the commit message, separated by a "Notes (<refname>):"
-line (shortened to "Notes:" in the case of "refs/notes/commits").  If the
-given ref itself does not exist, it is not an error, but means that no
-notes should be printed.
-+
-This setting defaults to "refs/notes/commits", and can be overridden by
-the `GIT_NOTES_REF` environment variable.
+This setting defaults to "refs/notes/commits", and it can be overridden by
+the 'GIT_NOTES_REF' environment variable.  See linkgit:git-notes[1].
 
 core.sparseCheckout::
 	Enable "sparse checkout" feature. See section "Sparse checkout" in
diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt
index fb184ba..d7f6a9c 100644
--- a/Documentation/git-log.txt
+++ b/Documentation/git-log.txt
@@ -132,6 +132,48 @@ Discussion
 
 include::i18n.txt[]
 
+Configuration
+-------------
+
+See linkgit:git-config[1] for core variables and linkgit:git-diff[1]
+for settings related to diff generation.
+
+format.pretty::
+	Default for the `--format` option.  (See "PRETTY FORMATS" above.)
+	Defaults to "medium".
+
+i18n.logOutputEncoding::
+	Encoding to use when displaying logs.  (See "Discussion", above.)
+	Defaults to the value of `i18n.commitEncoding` if set, UTF-8
+	otherwise.
+
+log.date::
+	Default format for human-readable dates.  (Compare the
+	`--date` option.)  Defaults to "default", which means to write
+	dates like `Sat May 8 19:35:34 2010 -0500`.
+
+log.showroot::
+	If `false`, 'git log' and related commands will not treat the
+	initial commit as a big creation event.  Any root commits in
+	`git log -p` output would be shown without a diff attached.
+	The default is `true`.
+
+mailmap.file::
+	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-standard-notes` option,
+overridden by the 'GIT_NOTES_DISPLAY_REF' environment variable,
+and supplemented by the `--show-notes` option.
 
 Author
 ------
diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 4e5113b..1d8eef1 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -3,7 +3,7 @@ git-notes(1)
 
 NAME
 ----
-git-notes - Add/inspect object notes
+git-notes - Add or inspect object notes
 
 SYNOPSIS
 --------
@@ -20,24 +20,26 @@ SYNOPSIS
 
 DESCRIPTION
 -----------
-This command allows you to add/remove notes to/from objects, without
-changing the objects themselves.
+Adds, removes, or reads notes attached to objects, without touching
+the objects themselves.
 
-A typical use of notes is to extend a commit message without having
-to change the commit itself. Such commit notes can be shown by `git log`
-along with the original commit message. To discern these notes from the
+By default, notes are saved to and read from `refs/notes/commits`, but
+this default can be overridden.  See the OPTIONS, CONFIGURATION, and
+ENVIRONMENT sections below.  If this ref does not exist, it will be
+quietly created when it is first needed to store a note.
+
+A typical use of notes is to supplement a commit message without
+changing the commit itself. Notes can be shown by 'git log' along with
+the original commit message. To distinguish these notes from the
 message stored in the commit object, the notes are indented like the
 message, after an unindented line saying "Notes (<refname>):" (or
-"Notes:" for the default setting).
+"Notes:" for `refs/notes/commits`).
 
-This command always manipulates the notes specified in "core.notesRef"
-(see linkgit:git-config[1]), which can be overridden by GIT_NOTES_REF.
-To change which notes are shown by 'git-log', see the
-"notes.displayRef" configuration.
+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
@@ -101,15 +103,20 @@ OPTIONS
 	Use the given note message (instead of prompting).
 	If multiple `-m` options are given, their values
 	are concatenated as separate paragraphs.
+	Lines starting with `#` and empty lines other than a
+	single line between paragraphs will be stripped out.
 
 -F <file>::
 --file=<file>::
 	Take the note message from the given file.  Use '-' to
 	read the note message from the standard input.
+	Lines starting with `#` and empty lines other than a
+	single line between paragraphs will be stripped out.
 
 -C <object>::
 --reuse-message=<object>::
-	Reuse the note message from the given note object.
+	Take the note message from the given blob object (for
+	example, another note).
 
 -c <object>::
 --reedit-message=<object>::
@@ -117,22 +124,147 @@ OPTIONS
 	the user can further edit the note message.
 
 --ref <ref>::
-	Manipulate the notes tree in <ref>.  This overrides both
-	GIT_NOTES_REF and the "core.notesRef" configuration.  The ref
+	Manipulate the notes tree in <ref>.  This overrides
+	'GIT_NOTES_REF' and the "core.notesRef" configuration.  The ref
 	is taken to be in `refs/notes/` if it is not qualified.
 
 
-NOTES
------
+DISCUSSION
+----------
+
+Commit notes are blobs containing extra information about an object
+(usually information to supplement a commit's message).  These blobs
+are taken from notes refs.  A notes ref is usually a branch which
+contains "files" whose paths are the object names for the objects
+they describe, with some directory separators included for performance
+reasons footnote:[Permitted pathnames have the form
+'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory
+names of two hexadecimal digits each followed by a filename with the
+rest of the object ID.].
 
 Every notes change creates a new commit at the specified notes ref.
 You can therefore inspect the history of the notes by invoking, e.g.,
-`git log -p notes/commits`.
+`git log -p notes/commits`.  Currently the commit message only records
+which operation triggered the update, and the commit authorship is
+determined according to the usual rules (see linkgit:git-commit[1]).
+These details may change in the future.
 
-Currently the commit message only records which operation triggered
-the update, and the commit authorship is determined according to the
-usual rules (see linkgit:git-commit[1]).  These details may change in
-the future.
+Some notes refs may be "history-less", either because they point
+directly to a tree instead of a commit, or because their commits are
+truncated; the notes generated by textconv caching
+(see linkgit:gitattributes[5]) are an example of the latter.
+To see the local history of these refs, view the reflog with
+`git log -g <refname>`.
+
+
+EXAMPLES
+--------
+
+You can use notes to add annotations with information that was not
+available at the time a commit was written.
+
+------------
+$ git notes add -m 'Tested-by: Johannes Sixt <j6t@kdbg.org>' 72a144e2
+$ git show -s 72a144e
+[...]
+    Signed-off-by: Junio C Hamano <gitster@pobox.com>
+
+Notes:
+    Tested-by: Johannes Sixt <j6t@kdbg.org>
+------------
+
+In principle, a note is a regular Git blob, and any kind of
+(non-)format is accepted.  You can binary-safely create notes from
+arbitrary files using 'git hash-object':
+
+------------
+$ cc *.c
+$ blob=$(git hash-object -w a.out)
+$ git notes --ref=built add -C "$blob" HEAD
+------------
+
+Of course, it doesn't make much sense to display non-text-format notes
+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
+-------------
+
+core.notesRef::
+	Notes ref to read and manipulate instead of
+	`refs/notes/commits`.  Must be an unabbreviated ref name.
+	This setting can be overridden by the 'GIT_NOTES_REF'
+	environment variable or the `--ref` option.
+
+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.
+
+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`, 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.  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.
+
+
+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'::
+	Colon-delimited list of refs or globs indicating which refs,
+	in addition to the default from `core.notesRef` or
+	'GIT_NOTES_REF', to read notes from when showing commit
+	messages.
+	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`, 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
diff --git a/t/t3307-notes-man.sh b/t/t3307-notes-man.sh
new file mode 100755
index 0000000..3269f2e
--- /dev/null
+++ b/t/t3307-notes-man.sh
@@ -0,0 +1,38 @@
+#!/bin/sh
+
+test_description='Examples from the git-notes man page
+
+Make sure the manual is not full of lies.'
+
+. ./test-lib.sh
+
+test_expect_success 'setup' '
+	test_commit A &&
+	test_commit B &&
+	test_commit C
+'
+
+test_expect_success 'example 1: notes to add an Acked-by line' '
+	cat <<-\EOF >expect &&
+	    B
+
+	Notes:
+	    Acked-by: A C Ker <acker@example.com>
+	EOF
+	git notes add -m "Acked-by: A C Ker <acker@example.com>" B &&
+	git show -s B^{commit} >log &&
+	tail -n 4 log >actual &&
+	test_cmp expect actual
+'
+
+test_expect_success 'example 2: binary notes' '
+	cp "$TEST_DIRECTORY"/test4012.png .
+	git checkout B &&
+	blob=$(git hash-object -w test4012.png) &&
+	git notes --ref=logo add -C "$blob" &&
+	git notes --ref=logo copy B C &&
+	git notes --ref=logo show C >actual &&
+	test_cmp test4012.png actual
+'
+
+test_done
-- 
1.7.1