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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 11, 2021, 00:35 UTC
Message-ID: <xmqqo8grzbjv.fsf@gitster.c.googlers.com>
In-Reply-To: <e7fde2369495f32c7aa88c7b6b74ebee1a1bed24.1613000292.git.martinvonz@google.com>

Martin von Zweigbergk <martinvonz@google.com> writes:

Show 6 quoted lines

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

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.

Show 7 quoted lines

> +If you are expecting some
> +objects to be deleted and they aren't, check all of those locations
> +and decide whether it makes sense in your case to remove those
> +references.
>  
>  On the other hand, when 'git gc' runs concurrently with another process,
>  there is a risk of it deleting an object that the other process is using

Thanks.