Re: [PATCH] doc: clarify that notes can be attached to any type of stored object

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 1, 2016, 16:47 UTC
Message-ID: <xmqq8u0xjmxh.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <xmqqy48xjqg5.fsf@gitster.mtv.corp.google.com>

Junio C Hamano <gitster@pobox.com> writes:

Show 8 quoted lines

> Sebastian Schuberth <sschuberth@gmail.com> writes:
>
>> Signed-off-by: Sebastian Schuberth <sschuberth@gmail.com>
>> ---
>>  Documentation/git-notes.txt | 5 +++--
>>  1 file changed, 3 insertions(+), 2 deletions(-)
>>
> I do not think this is correct place to patch.

So,... where is the right place?

Let's disect what we have in the DESCRIPTION section.

    DESCRIPTION
    -----------
    Adds, removes, or reads notes attached to objects, without touching
    the objects themselves.

This says "notes attached to objects" and "the objects themselves". They do not limit the target of attaching a note to "commits". So this may be the place to add " Note that notes can be attached to any kind of objects, not limited to commits" or something, if we really wanted to.

    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 `refs/notes/commits`).

    Notes can also be added to patches prepared with `git format-patch` by
    using the `--notes` option. Such notes are added as a patch commentary
    after a three dash separator line.

This paragraph _might_ be confusing to new readers. The "added to" sounds as if you are attaching a note to a non-object which is a patch. But this "add" is about "inserting the contents of the note attached to the commit being formatted" and corresponds to "can be shown by" in the previous paragraph. We may want to avoid the verb "add" when talking about the use of data stored in an existing note to somewhere else like this.

    To change which notes are shown by 'git log', see the
    "notes.displayRef" configuration in linkgit:git-log[1].

    See the "notes.rewrite.<command>" configuration for a way to carry
    notes across commands that rewrite commits.

    SUBCOMMANDS
    -----------

    list::
            List the notes object for a given object. If no object is
            given, show a list of all note objects and the objects they
            annotate (in the format "<note object> <annotated object>").
            This is the default subcommand if no subcommand is given.

    add::
            Add notes for a given object (defaults to HEAD). Abort if the

And this "Add notes for " should probably be reworded to "Attach notes to" to match the first sentence in the description.

            object already has notes (use `-f` to overwrite existing notes).
            However, if you're using `add` interactively (using an editor
            to supply the notes contents), then - instead of aborting -
            the existing notes will be opened in the editor (like the `edit`
            subcommand).