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

On Wed, Feb 10, 2021 at 2:35 PM Junio C Hamano [off-list ref] wrote:

Martin von Zweigbergk [off-list ref] writes:

quoted

 ... 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.