Re: [PATCH] docs: clarify that refs/notes/ do not keep the attached objects alive

[Martin von Zweigbergk <martinvonz@google.com>]

On Wed, Feb 10, 2021 at 2:35 PM Junio C Hamano <gitster@pobox.com> wrote:
>
> Martin von Zweigbergk <martinvonz@google.com> writes:
>
> >  ... In particular, it will keep not only
> > +objects referenced by the index, remote-tracking branches, reflogs
> > +(which may reference commits in branches that were later amended or
> > +rewound), and anything else in the refs/* namespace. Notes saved by
> > +'git notes' under refs/notes/ will be kept, but the objects (typically
> > +commits) they are attached to will not be.
>
> The notes will not contribute in keeping the objects they are
> attached to.  As long as the objects have some paths from refs and
> reflog entries (reachability anchors), they will be kept.  These
> two are facts.
>
> But I am afraid that the new phrasing can be misread as saying that
> an object, if it has notes attached to it, will not be kept, period.
>
> Knowing Git, we can tell immediately that it would be a nonsense
> behaviour, but still, I think that is how it can be read, so I
> suspect that the new text would invite a misunderstanding in the
> opposite direction.
>
>     ... and anything else in the refs/* namespace.  Note that a note
>     attached to an object does not contribute in keeping the object
>     alive.
>
> would be less misinterpretation-inducing, perhaps.

Good point. You dropped the bit about the notes (texts) being kept
alive. I don't know if you did that intentionally are not. I initially
thought that we should keep that bit, but it's probably not actually
very useful information. Users probably don't have large amounts of
information stored in notes, so they probably don't care whether notes
text is kept, especially since there's no good way of pruning the
notes. So I took your proposed sentence, but I added a parenthesis to
clarify that we're talking about notes from 'git notes'.

>
> We could go further to explain by adding something like that
> immediately after "keeping the object alive" above, e.g.
>
>     ---when an object becomes unreachable (e.g. a branch gets
>     rewound, a commit gets rewritten) and eventually gets pruned, a
>     note attached to the object will become dangling (use "git notes
>     prune" to remove them).
>
> but I am not sure if that is necessary.  Pruning notes attached to
> objects that are pruned may be relevant in the context of discussing
> "git gc", I guess.

Yes, seems only tangentially related, so I'll leave it out.

I'll send a v2 in a moment.