threads / patch / 23752

v2, 8 partsfilling out the notes man page

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

## tl;dr

21 messages between May 9, 2010 and May 12, 2010. Diffs are folded; open one to read it.

replies: 20people: 4as markdown or json

Jonathan Nieder· May 9, 2010, 03:13 UTC · lore
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
Jonathan Nieder· May 9, 2010, 03:19 UTC · re: Jonathan Nieder · lore

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

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(-)
Show changes to 2 files +26 −19

Documentation/config.txt, Documentation/git-notes.txt

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
Jeff King· May 9, 2010, 06:52 UTC · re: Jonathan Nieder · lore

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

On Sat, May 08, 2010 at 10:19:35PM -0500, Jonathan Nieder wrote:
Show 7 quoted lines
> 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
Jonathan Nieder· May 9, 2010, 03:21 UTC · re: Jonathan Nieder · lore

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

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
Show changes to 2 files +75 −1

Documentation/git-notes.txt, 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
Jonathan Nieder· May 9, 2010, 03:21 UTC · re: Jonathan Nieder · lore

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

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(-)
Show changes to Documentation/git-notes.txt +59 −0
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
Jonathan Nieder· May 9, 2010, 03:23 UTC · re: Jonathan Nieder · lore

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

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(-)
Show changes to Documentation/git-notes.txt +20 −11
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
Thomas Rast· May 12, 2010, 07:46 UTC · re: Jonathan Nieder · lore

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

Jonathan Nieder wrote:
Show 15 quoted lines
> @@ -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
Jonathan Nieder· May 12, 2010, 10:28 UTC · re: Thomas Rast · lore

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

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

Jonathan Nieder· May 9, 2010, 03:30 UTC · re: Jonathan Nieder · lore

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

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(-)
Show changes to Documentation/git-log.txt +42 −0
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
Jeff King· May 9, 2010, 06:57 UTC · re: Jonathan Nieder · lore

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

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
Jonathan Nieder· May 9, 2010, 03:32 UTC · re: Jonathan Nieder · lore

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

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(-)
Show changes to Documentation/git-notes.txt +19 −17
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
Jeff King· May 9, 2010, 07:00 UTC · re: Jonathan Nieder · lore

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

On Sat, May 08, 2010 at 10:32:24PM -0500, Jonathan Nieder wrote:
Show 26 quoted lines
> @@ -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
Jonathan Nieder· May 9, 2010, 08:43 UTC · re: Jeff King · lore

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

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)
Jeff King· May 10, 2010, 06:06 UTC · re: Jonathan Nieder · lore

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

On Sun, May 09, 2010 at 03:43:25AM -0500, Jonathan Nieder wrote:
Show 6 quoted lines
> 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. :)

Show 7 quoted lines
> 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
Jonathan Nieder· May 12, 2010, 10:50 UTC · re: Jeff King · lore

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

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

Jeff King· May 12, 2010, 11:23 UTC · re: Jonathan Nieder · lore

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

On Wed, May 12, 2010 at 05:50:02AM -0500, Jonathan Nieder wrote:
Show 21 quoted lines
> > 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
Jonathan Nieder· May 9, 2010, 03:33 UTC · re: Jonathan Nieder · lore

[PATCH 7/8] 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>
---
 Documentation/git-notes.txt |   47 ++++++++++++++++++++++++++----------------
 1 files changed, 29 insertions(+), 18 deletions(-)
Show changes to Documentation/git-notes.txt +29 −18
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
Jonathan Nieder· May 9, 2010, 03:37 UTC · re: Jonathan Nieder · lore

[PATCH 8/8] Documentation/notes: nitpicks

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(-)
Show changes to Documentation/git-notes.txt +6 −6
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
Johan Herland· May 10, 2010, 23:27 UTC · re: Jonathan Nieder · lore

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

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
Thomas Rast· May 12, 2010, 07:48 UTC · re: Johan Herland · lore

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

Johan Herland wrote:
Show 10 quoted lines
> 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
Jonathan Nieder· May 12, 2010, 12:57 UTC · re: Thomas Rast · lore

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

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
Show changes to 4 files +241 −34

Documentation/config.txt, Documentation/git-log.txt, Documentation/git-notes.txt, 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

← back to recent threads