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

[Thomas Rast <trast@student.ethz.ch>]

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