Re: [PATCH v2 5/9] notes docs: de-duplicate configuration sections

From: Matheus Tavares <matheus.bernardino@usp.br>
To: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Cc: git@vger.kernel.org, Junio C Hamano <gitster@pobox.com>
Subject: Re: [PATCH v2 5/9] notes docs: de-duplicate configuration sections
Date: Sat, 30 Jul 2022 17:02:34 -0300	[thread overview]
Message-ID: <CAHd-oW7s6Hu24uTjCW9ROBbJkA5+7TCu32a4L_BXVLhcvw5kSw@mail.gmail.com> (raw)
In-Reply-To: <patch-v2-5.9-1b6c8c75df7-20220729T081959Z-avarab@gmail.com>

On Fri, Jul 29, 2022 at 5:26 AM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
> diff --git a/Documentation/config/notes.txt b/Documentation/config/notes.txt
> index aeef56d49ae..c7c4811734b 100644
> --- a/Documentation/config/notes.txt
> +++ b/Documentation/config/notes.txt
> [...]
>  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.
> +       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 with the `GIT_NOTES_DISPLAY_REF`
>  environment variable, which must be a colon separated list of refs or
>  globs.
>  +
> +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-notes` option to the 'git
> +log' family of commands, or by the `--notes=<ref>` option accepted by
> +those commands.
> ++
>  The effective value of "core.notesRef" (possibly overridden by
>  GIT_NOTES_REF) is also implicitly added to the list of refs to be
>  displayed.

This change is a bit complex since it agglutinates the definition of
notes.displayRef from three different places with different wordings
each. Perhaps it would be helpful to acknowledge it in the commit
message and/or justify the chosen parts?

> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt
> index 0a4200674c4..68d547e2474 100644
> --- a/Documentation/git-notes.txt
> +++ b/Documentation/git-notes.txt
> @@ -44,7 +44,7 @@ using the `--notes` option. Such notes are added as a patch commentary
>  after a three dash separator line.
>
>  To change which notes are shown by 'git log', see the
> -"notes.displayRef" configuration in linkgit:git-log[1].
> +"notes.displayRef" configuration in linkgit:git-config[1].

Since notes.displayRef now comes from config/notes.txt which will be
included here, I think we could replace this reference to
git-config(1) with "in the CONFIGURATION section below".