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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 4, 2016, 18:04 UTC
Message-ID: <xmqqzit945ed.fsf@gitster.mtv.corp.google.com>
In-Reply-To: <CAHGBnuPkPqJprOxR4zBuWitXqXt9XtpnjGPQWEv+-pYovh1b+A@mail.gmail.com>

Sebastian Schuberth <sschuberth@gmail.com> writes:

Show 16 quoted lines

>>> -It is also permitted for a notes ref to point directly to a tree
>>> -object, in which case the history of the notes can be read with
>>> +It is also permitted for a notes ref to point to any other object in
>>> +the object store besides commit objects, that is annotated tags, blobs
>>> +or trees. For the latter, the history of the notes can be read with
>>>  `git log -p -g <refname>`.
>>
>> I do not think this is correct place to patch.  The original is not
>> talking about what objects can have notes attached at all.  What it
>> explains is this.
>
> Thanks for the explanation, I was indeed misreading this. I'll try to
> clarify this section then, too. In order to do so, I think we should
> mention how to actually create a <refname> that directly points to a
> tree instead of a commit for the history of notes. Would you have an
> example how to do that?

Interesting. This came from 9eb3f816 (Documentation/notes: document format of notes trees, 2010-05-08):

    Documentation/notes: document format of notes trees

    Separate the specification of the notes format exposed in
    git-config.1 from the description of the option; or in other
    words, move the explanation for what to expect to find at
    refs/notes/commits from git-config.1 to git-notes.1.

    Suggested-by: Thomas Rast <trast@student.ethz.ch>
    Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
    Signed-off-by: Junio C Hamano <gitster@pobox.com>

but I do not find a corresponding sentence that says a notes ref can point at a tree in the text before the patch.

I highly suspect that "git notes add" and other Porcelain level commands that manipulate an existing notes tree would be unhappy if a notes ref is not a commit, as it is clear from the paragraph before the one under discussion, i.e.

    Every notes change creates a new commit at the specified notes ref.
    You can therefore inspect the history of the notes by invoking, e.g.,
    `git log -p notes/commits`.  Currently the commit message only records
    which operation triggered the update, and the commit authorship is
    determined according to the usual rules (see linkgit:git-commit[1]).
    These details may change in the future.

that in order to create a "new" commit, setting the current one as its parent, would require that the current one to be a commit and not a bare tree. "git notes list" and others that merely read from the notes tree would probably work.