patchdocs: clarify that refs/notes/ do not keep the attached objects alive

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

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

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

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

>
> Martin von Zweigbergk <martinvonz@google.com> writes:
>
> > Good point. You dropped the bit about the notes (texts) being kept
> > alive. I don't know if you did that intentionally are not.
>
> Yes, I did it on purpose, because it is just one of the things that
> can be reached from refs/, but we shouldn't write our document for
> those like me, who know what notes and other things in Git are.
>
> > 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.
>
> I am not sure if I agree with any part of the above.  End-user data
> is precious no matter the volume, and we keep notes by making them
> reachable from refs in the refs/notes/ hierarchy.

> `git help gc` contains this snippet:
>
>   "[...] it will keep [..] objects referenced by the index,
>   remote-tracking branches, notes saved by git notes under refs/notes/"
>
> I had interpreted that as saying that the objects that notes were
> attached to are kept, but that is not the case. Let's clarify the
> documentation by moving out the part about git notes to a separate
> sentence.
>
> Signed-off-by: Martin von Zweigbergk <martinvonz@google.com>
> ---

>  Documentation/git-gc.txt | 14 ++++++++------
>  1 file changed, 8 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt
> index 0c114ad1ca..52824269a8 100644
> --- a/Documentation/git-gc.txt
> +++ b/Documentation/git-gc.txt
> @@ -117,12 +117,14 @@ NOTES
>  'git gc' tries very hard not to delete objects that are referenced
>  anywhere in your repository. In particular, it will keep not only
>  objects referenced by your current set of branches and tags, but also
> -objects referenced by the index, remote-tracking branches, notes saved
> -by 'git notes' under refs/notes/, reflogs (which may reference commits
> -in branches that were later amended or rewound), and anything else in
> -the refs/* namespace.  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.
> +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. 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

>
> Martin von Zweigbergk <martinvonz@google.com> writes:
>
> > `git help gc` contains this snippet:
> >
> >   "[...] it will keep [..] objects referenced by the index,
> >   remote-tracking branches, notes saved by git notes under refs/notes/"
> >
> > I had interpreted that as saying that the objects that notes were
> > attached to are kept, but that is not the case. Let's clarify the
> > documentation by moving out the part about git notes to a separate
> > sentence.
> >
> > Signed-off-by: Martin von Zweigbergk <martinvonz@google.com>
> > ---
>
> This looks the same as the one in
> <e7fde2369495f32c7aa88c7b6b74ebee1a1bed24.1613000292.git.martinvonz@google.com>
>
> which was v1, except that this one has your sign-off.  Sent a wrong
> version?

> `git help gc` contains this snippet:
>
>   "[...] it will keep [..] objects referenced by the index,
>   remote-tracking branches, notes saved by git notes under refs/notes/"
>
> I had interpreted that as saying that the objects that notes were
> attached to are kept, but that is not the case. Let's clarify the
> documentation by moving out the part about git notes to a separate
> sentence.
>
> Signed-off-by: Martin von Zweigbergk <martinvonz@google.com>
> ---
>  Documentation/git-gc.txt | 14 ++++++++------
>  1 file changed, 8 insertions(+), 6 deletions(-)

> diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt
> index 0c114ad1ca..853967dea0 100644
> --- a/Documentation/git-gc.txt
> +++ b/Documentation/git-gc.txt
> @@ -117,12 +117,14 @@ NOTES
>  'git gc' tries very hard not to delete objects that are referenced
>  anywhere in your repository. In particular, it will keep not only
>  objects referenced by your current set of branches and tags, but also
> -objects referenced by the index, remote-tracking branches, notes saved
> -by 'git notes' under refs/notes/, reflogs (which may reference commits
> -in branches that were later amended or rewound), and anything else in
> -the refs/* namespace.  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.
> +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. Note that a note
> +(of the kind created by 'git notes') attached to an object does not
> +contribute in keeping the object alive. 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