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

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

[Jonathan Nieder]

I decided it’s time I learn to use notes.  Here’s a by-product.

Thoughts?
Jonathan Nieder (4):
  Documentation/notes: describe effect of environment and configuration
  Documentation/notes: adjust description to use configuration section
  Documentation/notes: describe content of notes
  Documentation/notes: nitpicks

 Documentation/git-notes.txt |  114 +++++++++++++++++++++++++++++++++++++------
 1 files changed, 99 insertions(+), 15 deletions(-)

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

[Jonathan Nieder]

Based on the description from Documentation/config.txt.

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

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

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 4e5113b..b26598e 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -135,6 +135,88 @@ usual rules (see linkgit:git-commit[1]).  These details may change in
 the future.
 
 
+CONFIGURATION
+-------------
+
+core.notesRef::
+	By default, 'git notes' and other commands read and manipulate
+	the notes referred to by `refs/notes/commits`.  This
+	configuration item allows one to specify an alternative
+	default ref (to be overridden by environment variables or
+	command-line options).
+
+notes.displayRef::
+	Which refs, in addition to the default set by `core.notesRef`
+	or 'GIT_NOTES_REF', for 'git log' to read notes from when
+	showing commit messages.  Can be a (fully qualified) ref name
+	or glob.  You may also specify this configuration variable
+	several times.
++
+This setting can be overridden with the 'GIT_NOTES_DISPLAY_REF'
+environment variable.
+
+notes.rewrite.<command>::
+	When rewriting commits with <command> (currently `amend` or
+	`rebase`), if this variable is `false`, git will not copy
+	notes from the original to the rewritten commit.  Defaults to
+	`true`.  See also "`notes.rewriteRef`" below.
++
+This setting can be overridden by the 'GIT_NOTES_REWRITE_REF'
+environment variable.
+
+notes.rewriteMode::
+	When copying notes during a rewrite, what to do if the target
+	commit already has a note.  Must be one of `overwrite`,
+	`concatenate`, or `ignore`.  Defaults to `concatenate`.
++
+This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`
+environment variable.
+
+notes.rewriteRef::
+	When copying notes during a rewrite, specifies the (fully
+	qualified) ref whose notes should be copied.  May be a glob,
+	in which case notes in all matching refs will be copied.  You
+	may also specify this configuration several times.
++
+Does not have a default value.  Configure this variable to enable note
+rewriting.
++
+Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable.
+
+See linkgit:git-config[1] for details.
+
+ENVIRONMENT
+-----------
+
+'GIT_NOTES_REF'::
+	Which ref to manipulate notes from, instead of `refs/notes/commits`.
+	This overrides the `core.notesRef` setting.
+
+'GIT_NOTES_DISPLAY_REF'::
+	Which refs, in addition to the default from `core.notesRef` or
+	'GIT_NOTES_REF', to read notes from when showing commit
+	messages.
+	Must be a colon-delimited list of refs or globs.
+	This overrides the `notes.displayRef` setting.
++
+A warning will be issued for refs that do not exist, but a glob that
+does not match any refs is silently ignored.
+
+'GIT_NOTES_REWRITE_MODE'::
+	When copying notes during a rewrite, what to do if the target
+	commit already has a note.
+	Must be one of `overwrite`, `concatenate`, or `ignore`.
+	This overrides the `core.rewriteMode` setting.
+
+'GIT_NOTES_REWRITE_REF'::
+	When rewriting commits, which notes to copy from the original
+	to the rewritten commit.  Must be a colon-delimited list of
+	refs or globs.
++
+If not set in the environment, the list of notes to copy will depend
+on the `notes.rewrite.<command>` and `notes.rewriteRef` settings.
+
+
 Author
 ------
 Written by Johannes Schindelin <johannes.schindelin@gmx.de> and
-- 
1.7.1

[PATCH 2/4] Documentation/notes: adjust description to use configuration section

[Jonathan Nieder]

Introduce the default notes ref early on to give the reader a frame of
reference for understanding the rest of the description.

Cc: Johan Herland <johan@herland.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-notes.txt |   14 ++++++--------
 1 files changed, 6 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index b26598e..0594776 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -23,6 +23,10 @@ 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 CONFIGURATION and ENVIRONMENT
+sections below.
+
 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,14 +34,8 @@ 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).
 
-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.
-
-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 of carrying
+notes across commands that rewrite commits.
 
 
 SUBCOMMANDS
-- 
1.7.1

[PATCH 3/4] Documentation/notes: describe content of notes

[Jonathan Nieder]

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

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 0594776..273264b 100644
--- a/Documentation/git-notes.txt
+++ b/Documentation/git-notes.txt
@@ -27,6 +27,10 @@ By default, notes are saved to and read from `refs/notes/commits`, but
 this default can be overridden.  See the CONFIGURATION and ENVIRONMENT
 sections below.
 
+Notes can contain any sequence of non-null bytes.  Since they are
+sanitized with linkgit:git-stripspace[1], empty lines other than a
+single line separating paragraphs are not significant.
+
 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
-- 
1.7.1

[PATCH 4/4] 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>
---
That’s the end of the series.  Nothing dramatic, but I thought this
basic information could help.  Thanks for looking it over.

While I have your attention: the original man page said

  To disable commit notes, you have to set the config variable
  core.notesRef to the empty string.  Alternatively, you can set it
  to a different ref, something like "refs/notes/bugzilla".  This setting
  can be overridden by the environment variable "GIT_NOTES_REF".

which sounds helpful to me, both as an example and as a way to help
people who do not want to use the feature.  Any idea where we could
add it back?

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

diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
index 273264b..b953575 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,8 +20,8 @@ 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 CONFIGURATION and ENVIRONMENT
@@ -31,14 +31,14 @@ Notes can contain any sequence of non-null bytes.  Since they are
 sanitized with linkgit:git-stripspace[1], empty lines other than a
 single line separating paragraphs are not significant.
 
-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 the default setting).
+"Notes:" for the main notes ref).
 
-See the "notes.rewrite.<command>" configuration for a way of carrying
+See the "notes.rewrite.<command>" configuration for a way to carry
 notes across commands that rewrite commits.
 
 
-- 
1.7.1

Re: [PATCH 4/4] Documentation/notes: nitpicks

[Thomas Rast]

Jonathan Nieder wrote:
> -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 the default setting).
> +"Notes:" for the main notes ref).

Nitpick on your nitpick: we do not call refs/notes/commits the "main"
notes ref anywhere, and you don't seem to introduce this terminology.

The user might infer that "main" means core.notesRef, but the omission
of (<refname>) is actually hardcoded to only happen for
refs/notes/commits, so that's not correct.


[I'll review the other patches after the lecture.]

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

Re: [PATCH 4/4] Documentation/notes: nitpicks

[Jonathan Nieder]

Thomas Rast wrote:
> Jonathan Nieder wrote:

>> -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 the default setting).
>> +"Notes:" for the main notes ref).
[...]
> The user might infer that "main" means core.notesRef, but the omission
> of (<refname>) is actually hardcoded to only happen for
> refs/notes/commits, so that's not correct.

Oh!  I had no inkling.

I guess the simplest way to document this is to just say it:

	           ... unindented line saying "Notes (<refname>):' (or
	"Notes:" for refs/notes/commits).

Thanks for the explanation.

Cheers,
Jonathan

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

[Thomas Rast]

Jonathan Nieder wrote:
> +core.notesRef::
> +	By default, 'git notes' and other commands read and manipulate
> +	the notes referred to by `refs/notes/commits`.  This
> +	configuration item allows one to specify an alternative
> +	default ref (to be overridden by environment variables or
> +	command-line options).
> +
> +notes.displayRef::
> +	Which refs, in addition to the default set by `core.notesRef`
> +	or 'GIT_NOTES_REF', for 'git log' to read notes from when
> +	showing commit messages.  Can be a (fully qualified) ref name
> +	or glob.  You may also specify this configuration variable
> +	several times.
> ++
> +This setting can be overridden with the 'GIT_NOTES_DISPLAY_REF'
> +environment variable.

I noticed you copied the rest of the description, but not these,
verbatim.  If the intention was to separate the specification of the
notes format exposed in git-config(1),

      [...] This ref is expected to contain files named after the full
      SHA-1 of the commit they annotate. The ref must be fully
      qualified.

      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.

from the description of the option.  I agree to the idea, but maybe we
should also do the same in git-config(1).  For example, it could be
added to the NOTES section of git-notes(1) that already describes some
implementation details.

You also describe the warning semantics only for
GIT_NOTES_DISPLAY_REF, not for notes.displayRef.  I see the config
options as the main feature, and the variable as a mere convenience
(but others may disagree) so I would put the full semantics into the
config descriptions.

Otherwise, ack.

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

Re: [PATCH 3/4] Documentation/notes: describe content of notes

[Thomas Rast]

Jonathan Nieder wrote:
> +Notes can contain any sequence of non-null bytes.  Since they are
> +sanitized with linkgit:git-stripspace[1], empty lines other than a
> +single line separating paragraphs are not significant.

It even goes slightly further: create_note() calls stripspace() with
the skip_comments option enabled, so comment lines are also removed.
('git notes add' actually puts `git show --stat` in a big comment
block...)

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

Re: [PATCH 3/4] Documentation/notes: describe content of notes

[Johan Herland]

On Tuesday 04 May 2010, Jonathan Nieder wrote:
> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
> ---
>  Documentation/git-notes.txt |    4 ++++
>  1 files changed, 4 insertions(+), 0 deletions(-)
> 
> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
> index 0594776..273264b 100644
> --- a/Documentation/git-notes.txt
> +++ b/Documentation/git-notes.txt
> @@ -27,6 +27,10 @@ By default, notes are saved to and read from
> `refs/notes/commits`, but this default can be overridden.  See the
> CONFIGURATION and ENVIRONMENT sections below.
> 
> +Notes can contain any sequence of non-null bytes.  Since they are
> +sanitized with linkgit:git-stripspace[1], empty lines other than a
> +single line separating paragraphs are not significant.

In principle, a note is a regular Git (blob) object, and can contain NUL 
bytes - indeed any kind of (non-)format is accepted.

However, the 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.

So as long as you stick to the following subcommands, notes should be 
completely binary-safe:

- git notes [list [<object>]]
- git notes add [-f] -C <note-object> <object>
- git notes copy [-f] <from-object> <to-object>
- git notes show [<object>]
- git notes remove [<object>]
- git notes prune

In other words, you can (binary-safely) create notes from files with the 
following construct:

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

Of course, it doesn't make much sense displaying non-text-format notes with 
'git log', so if you use such notes you'll probably need to write some 
special-purpose tools for doing anything useful with them.

Otherwise, your other 3 patches seem fine to me (modulo Thomas Rast's 
comments) and you can consider them
Acked-by: Johan Herland <johan@herland.net>


Have fun! :)

...Johan

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

Re: [PATCH 3/4] Documentation/notes: describe content of notes

[Jeff King]

On Tue, May 04, 2010 at 11:55:01AM +0200, Johan Herland wrote:

> On Tuesday 04 May 2010, Jonathan Nieder wrote:
> > Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
> > ---
> >  Documentation/git-notes.txt |    4 ++++
> >  1 files changed, 4 insertions(+), 0 deletions(-)
> > 
> > diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
> > index 0594776..273264b 100644
> > --- a/Documentation/git-notes.txt
> > +++ b/Documentation/git-notes.txt
> > @@ -27,6 +27,10 @@ By default, notes are saved to and read from
> > `refs/notes/commits`, but this default can be overridden.  See the
> > CONFIGURATION and ENVIRONMENT sections below.
> > 
> > +Notes can contain any sequence of non-null bytes.  Since they are
> > +sanitized with linkgit:git-stripspace[1], empty lines other than a
> > +single line separating paragraphs are not significant.
> 
> In principle, a note is a regular Git (blob) object, and can contain NUL 
> bytes - indeed any kind of (non-)format is accepted.
> 
> However, the 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.

The textconv-cache notes contain whatever the textconv filter produces,
so they are a likely way of getting non-standard characters. In
practice, though, you will probably not see NULL, because the point was
to generate a _text_ version.

-Peff