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

[Junio C Hamano <gitster@pobox.com>]

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.

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.

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