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

From: Thomas Rast <trast@student.ethz.ch>
Date: May 4, 2010, 09:24 UTC
Message-ID: <201005041124.26533.trast@student.ethz.ch>
In-Reply-To: <20100503234140.GA27483@progeny.tock>

Jonathan Nieder wrote:

Show 16 quoted lines

> +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