{"thread":{"id":"55136","subject":"[PATCH] docs: clarify that refs/notes/ do not keep the attached objects alive","startedAt":"2021-02-11T00:01:44Z","lastAt":"2021-02-11T07:44:44Z","messageCount":10,"participants":["Martin von Zweigbergk","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"416683","messageId":"e7fde2369495f32c7aa88c7b6b74ebee1a1bed24.1613000292.git.martinvonz@google.com","threadId":"55136","inReplyTo":null,"subject":"[PATCH] docs: clarify that refs/notes/ do not keep the attached objects alive","fromName":"Martin von Zweigbergk","fromEmail":"martinvonz@google.com","sentAt":"2021-02-11T00:00:21Z","receivedAt":"2021-02-11T00:01:44Z","isPatch":true,"sender":{"key":"martinvonz@google.com","avatar":"https://avatars.githubusercontent.com/u/891642?v=4"},"body":"`git help gc` contains this snippet:\n\n \"[...] it will keep [..] objects referenced by the index,\n remote-tracking branches, notes saved by git notes under refs/notes/\"\n\nI had interpreted that as saying that the objects that notes were\nattached to are kept, but that is not the case. Let's clarify the\ndocumentation by moving out the part about git notes to a separate\nsentence.\n---\n Documentation/git-gc.txt | 14 ++++++++------\n 1 file changed, 8 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt\nindex 0c114ad1ca..52824269a8 100644\n--- a/Documentation/git-gc.txt\n+++ b/Documentation/git-gc.txt\n@@ -117,12 +117,14 @@ NOTES\n 'git gc' tries very hard not to delete objects that are referenced\n anywhere in your repository. In particular, it will keep not only\n objects referenced by your current set of branches and tags, but also\n-objects referenced by the index, remote-tracking branches, notes saved\n-by 'git notes' under refs/notes/, reflogs (which may reference commits\n-in branches that were later amended or rewound), and anything else in\n-the refs/* namespace. If you are expecting some objects to be deleted\n-and they aren't, check all of those locations and decide whether it\n-makes sense in your case to remove those references.\n+objects referenced by the index, remote-tracking branches, reflogs\n+(which may reference commits in branches that were later amended or\n+rewound), and anything else in the refs/* namespace. Notes saved by\n+'git notes' under refs/notes/ will be kept, but the objects (typically\n+commits) they are attached to will not be. If you are expecting some\n+objects to be deleted and they aren't, check all of those locations\n+and decide whether it makes sense in your case to remove those\n+references.\n \n On the other hand, when 'git gc' runs concurrently with another process,\n there is a risk of it deleting an object that the other process is using\n-- \n2.30.0.478.g8a0d178c01-goog\n\n"},{"id":"416685","messageId":"xmqqo8grzbjv.fsf@gitster.c.googlers.com","threadId":"55136","inReplyTo":"e7fde2369495f32c7aa88c7b6b74ebee1a1bed24.1613000292.git.martinvonz@google.com","subject":"Re: [PATCH] docs: clarify that refs/notes/ do not keep the attached objects alive","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-02-11T00:35:16Z","receivedAt":"2021-02-11T00:36:20Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin von Zweigbergk writes:\n\n> ... In particular, it will keep not only\n> +objects referenced by the index, remote-tracking branches, reflogs\n> +(which may reference commits in branches that were later amended or\n> +rewound), and anything else in the refs/* namespace. Notes saved by\n> +'git notes' under refs/notes/ will be kept, but the objects (typically\n> +commits) they are attached to will not be.\n\nThe notes will not contribute in keeping the objects they are\nattached to. As long as the objects have some paths from refs and\nreflog entries (reachability anchors), they will be kept. These\ntwo are facts.\n\nBut I am afraid that the new phrasing can be misread as saying that\nan object, if it has notes attached to it, will not be kept, period.\n\nKnowing Git, we can tell immediately that it would be a nonsense\nbehaviour, but still, I think that is how it can be read, so I\nsuspect that the new text would invite a misunderstanding in the\nopposite direction.\n\n ... and anything else in the refs/* namespace. Note that a note\n attached to an object does not contribute in keeping the object\n alive.\n\nwould be less misinterpretation-inducing, perhaps.\n\nWe could go further to explain by adding something like that\nimmediately after \"keeping the object alive\" above, e.g.\n\n ---when an object becomes unreachable (e.g. a branch gets\n rewound, a commit gets rewritten) and eventually gets pruned, a\n note attached to the object will become dangling (use \"git notes\n prune\" to remove them).\n\nbut I am not sure if that is necessary. Pruning notes attached to\nobjects that are pruned may be relevant in the context of discussing\n\"git gc\", I guess.\n\n> +If you are expecting some\n> +objects to be deleted and they aren't, check all of those locations\n> +and decide whether it makes sense in your case to remove those\n> +references.\n> \n> On the other hand, when 'git gc' runs concurrently with another process,\n> there is a risk of it deleting an object that the other process is using\n\nThanks.\n"},{"id":"416713","messageId":"CAESOdVDgpe9yacMxKLO_AjAnadcSjrik_NdwhW-4vDELf+UxPw@mail.gmail.com","threadId":"55136","inReplyTo":"xmqqo8grzbjv.fsf@gitster.c.googlers.com","subject":"Re: [PATCH] docs: clarify that refs/notes/ do not keep the attached objects alive","fromName":"Martin von Zweigbergk","fromEmail":"martinvonz@google.com","sentAt":"2021-02-11T07:14:15Z","receivedAt":"2021-02-11T07:15:16Z","isPatch":true,"sender":{"key":"martinvonz@google.com","avatar":"https://avatars.githubusercontent.com/u/891642?v=4"},"body":"On Wed, Feb 10, 2021 at 2:35 PM Junio C Hamano wrote:\n>\n> Martin von Zweigbergk writes:\n>\n> > ... In particular, it will keep not only\n> > +objects referenced by the index, remote-tracking branches, reflogs\n> > +(which may reference commits in branches that were later amended or\n> > +rewound), and anything else in the refs/* namespace. Notes saved by\n> > +'git notes' under refs/notes/ will be kept, but the objects (typically\n> > +commits) they are attached to will not be.\n>\n> The notes will not contribute in keeping the objects they are\n> attached to. As long as the objects have some paths from refs and\n> reflog entries (reachability anchors), they will be kept. These\n> two are facts.\n>\n> But I am afraid that the new phrasing can be misread as saying that\n> an object, if it has notes attached to it, will not be kept, period.\n>\n> Knowing Git, we can tell immediately that it would be a nonsense\n> behaviour, but still, I think that is how it can be read, so I\n> suspect that the new text would invite a misunderstanding in the\n> opposite direction.\n>\n> ... and anything else in the refs/* namespace. Note that a note\n> attached to an object does not contribute in keeping the object\n> alive.\n>\n> would be less misinterpretation-inducing, perhaps.\n\nGood point. You dropped the bit about the notes (texts) being kept\nalive. I don't know if you did that intentionally are not. I initially\nthought that we should keep that bit, but it's probably not actually\nvery useful information. Users probably don't have large amounts of\ninformation stored in notes, so they probably don't care whether notes\ntext is kept, especially since there's no good way of pruning the\nnotes. So I took your proposed sentence, but I added a parenthesis to\nclarify that we're talking about notes from 'git notes'.\n\n>\n> We could go further to explain by adding something like that\n> immediately after \"keeping the object alive\" above, e.g.\n>\n> ---when an object becomes unreachable (e.g. a branch gets\n> rewound, a commit gets rewritten) and eventually gets pruned, a\n> note attached to the object will become dangling (use \"git notes\n> prune\" to remove them).\n>\n> but I am not sure if that is necessary. Pruning notes attached to\n> objects that are pruned may be relevant in the context of discussing\n> \"git gc\", I guess.\n\nYes, seems only tangentially related, so I'll leave it out.\n\nI'll send a v2 in a moment.\n"},{"id":"416714","messageId":"0bdc333b25aca1de82fea3a1f290fe30ee3ebf51.1613027889.git.martinvonz@google.com","threadId":"55136","inReplyTo":"e7fde2369495f32c7aa88c7b6b74ebee1a1bed24.1613000292.git.martinvonz@google.com","subject":"[PATCH v2] docs: clarify that refs/notes/ do not keep the attached objects alive","fromName":"Martin von Zweigbergk","fromEmail":"martinvonz@google.com","sentAt":"2021-02-11T07:18:45Z","receivedAt":"2021-02-11T07:19:52Z","isPatch":true,"sender":{"key":"martinvonz@google.com","avatar":"https://avatars.githubusercontent.com/u/891642?v=4"},"body":"`git help gc` contains this snippet:\n\n \"[...] it will keep [..] objects referenced by the index,\n remote-tracking branches, notes saved by git notes under refs/notes/\"\n\nI had interpreted that as saying that the objects that notes were\nattached to are kept, but that is not the case. Let's clarify the\ndocumentation by moving out the part about git notes to a separate\nsentence.\n\nSigned-off-by: Martin von Zweigbergk \n---\n Documentation/git-gc.txt | 14 ++++++++------\n 1 file changed, 8 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt\nindex 0c114ad1ca..52824269a8 100644\n--- a/Documentation/git-gc.txt\n+++ b/Documentation/git-gc.txt\n@@ -117,12 +117,14 @@ NOTES\n 'git gc' tries very hard not to delete objects that are referenced\n anywhere in your repository. In particular, it will keep not only\n objects referenced by your current set of branches and tags, but also\n-objects referenced by the index, remote-tracking branches, notes saved\n-by 'git notes' under refs/notes/, reflogs (which may reference commits\n-in branches that were later amended or rewound), and anything else in\n-the refs/* namespace. If you are expecting some objects to be deleted\n-and they aren't, check all of those locations and decide whether it\n-makes sense in your case to remove those references.\n+objects referenced by the index, remote-tracking branches, reflogs\n+(which may reference commits in branches that were later amended or\n+rewound), and anything else in the refs/* namespace. Notes saved by\n+'git notes' under refs/notes/ will be kept, but the objects (typically\n+commits) they are attached to will not be. If you are expecting some\n+objects to be deleted and they aren't, check all of those locations\n+and decide whether it makes sense in your case to remove those\n+references.\n \n On the other hand, when 'git gc' runs concurrently with another process,\n there is a risk of it deleting an object that the other process is using\n-- \n2.30.1.379.ge7fde23694\n\n"},{"id":"416716","messageId":"xmqqeehnysbv.fsf@gitster.c.googlers.com","threadId":"55136","inReplyTo":"CAESOdVDgpe9yacMxKLO_AjAnadcSjrik_NdwhW-4vDELf+UxPw@mail.gmail.com","subject":"Re: [PATCH] docs: clarify that refs/notes/ do not keep the attached objects alive","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-02-11T07:30:28Z","receivedAt":"2021-02-11T07:31:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin von Zweigbergk writes:\n\n> Good point. You dropped the bit about the notes (texts) being kept\n> alive. I don't know if you did that intentionally are not.\n\nYes, I did it on purpose, because it is just one of the things that\ncan be reached from refs/, but we shouldn't write our document for\nthose like me, who know what notes and other things in Git are.\n\n> I initially\n> thought that we should keep that bit, but it's probably not actually\n> very useful information. Users probably don't have large amounts of\n> information stored in notes, so they probably don't care whether notes\n> text is kept, especially since there's no good way of pruning the\n> notes.\n\nI am not sure if I agree with any part of the above. End-user data\nis precious no matter the volume, and we keep notes by making them\nreachable from refs in the refs/notes/ hierarchy.\n\nI am not sure what qualifies, in your eyes, \"good\" way, but \"git\nnotes prune\" is a good way to remove notes that are attached to\nobjects that have already been pruned away.\n\n"},{"id":"416717","messageId":"xmqq7dnfys5l.fsf@gitster.c.googlers.com","threadId":"55136","inReplyTo":"0bdc333b25aca1de82fea3a1f290fe30ee3ebf51.1613027889.git.martinvonz@google.com","subject":"Re: [PATCH v2] docs: clarify that refs/notes/ do not keep the attached objects alive","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-02-11T07:34:14Z","receivedAt":"2021-02-11T07:35:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin von Zweigbergk writes:\n\n> `git help gc` contains this snippet:\n>\n> \"[...] it will keep [..] objects referenced by the index,\n> remote-tracking branches, notes saved by git notes under refs/notes/\"\n>\n> I had interpreted that as saying that the objects that notes were\n> attached to are kept, but that is not the case. Let's clarify the\n> documentation by moving out the part about git notes to a separate\n> sentence.\n>\n> Signed-off-by: Martin von Zweigbergk \n> ---\n\nThis looks the same as the one in\n\n\nwhich was v1, except that this one has your sign-off. Sent a wrong\nversion?\n\n> Documentation/git-gc.txt | 14 ++++++++------\n> 1 file changed, 8 insertions(+), 6 deletions(-)\n>\n> diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt\n> index 0c114ad1ca..52824269a8 100644\n> --- a/Documentation/git-gc.txt\n> +++ b/Documentation/git-gc.txt\n> @@ -117,12 +117,14 @@ NOTES\n> 'git gc' tries very hard not to delete objects that are referenced\n> anywhere in your repository. In particular, it will keep not only\n> objects referenced by your current set of branches and tags, but also\n> -objects referenced by the index, remote-tracking branches, notes saved\n> -by 'git notes' under refs/notes/, reflogs (which may reference commits\n> -in branches that were later amended or rewound), and anything else in\n> -the refs/* namespace. If you are expecting some objects to be deleted\n> -and they aren't, check all of those locations and decide whether it\n> -makes sense in your case to remove those references.\n> +objects referenced by the index, remote-tracking branches, reflogs\n> +(which may reference commits in branches that were later amended or\n> +rewound), and anything else in the refs/* namespace. Notes saved by\n> +'git notes' under refs/notes/ will be kept, but the objects (typically\n> +commits) they are attached to will not be. If you are expecting some\n> +objects to be deleted and they aren't, check all of those locations\n> +and decide whether it makes sense in your case to remove those\n> +references.\n> \n> On the other hand, when 'git gc' runs concurrently with another process,\n> there is a risk of it deleting an object that the other process is using\n"},{"id":"416718","messageId":"CAESOdVB7i9UJpsB91sedGKPiCxkc0XgC+T5SLP4qF==kaqhJtg@mail.gmail.com","threadId":"55136","inReplyTo":"xmqq7dnfys5l.fsf@gitster.c.googlers.com","subject":"Re: [PATCH v2] docs: clarify that refs/notes/ do not keep the attached objects alive","fromName":"Martin von Zweigbergk","fromEmail":"martinvonz@google.com","sentAt":"2021-02-11T07:36:33Z","receivedAt":"2021-02-11T07:37:54Z","isPatch":true,"sender":{"key":"martinvonz@google.com","avatar":"https://avatars.githubusercontent.com/u/891642?v=4"},"body":"On Wed, Feb 10, 2021 at 9:34 PM Junio C Hamano wrote:\n>\n> Martin von Zweigbergk writes:\n>\n> > `git help gc` contains this snippet:\n> >\n> > \"[...] it will keep [..] objects referenced by the index,\n> > remote-tracking branches, notes saved by git notes under refs/notes/\"\n> >\n> > I had interpreted that as saying that the objects that notes were\n> > attached to are kept, but that is not the case. Let's clarify the\n> > documentation by moving out the part about git notes to a separate\n> > sentence.\n> >\n> > Signed-off-by: Martin von Zweigbergk \n> > ---\n>\n> This looks the same as the one in\n> \n>\n> which was v1, except that this one has your sign-off. Sent a wrong\n> version?\n\nYes, sorry. I forgot the `-a` to `git commit --amend` (have been using\nMercurial for the last 5 years now). I'll send a v3.\n"},{"id":"416720","messageId":"CAESOdVCYceVgF4B0f--yjheS+FijX-GJWUYjfgz1tRrL7kU+yA@mail.gmail.com","threadId":"55136","inReplyTo":"xmqqeehnysbv.fsf@gitster.c.googlers.com","subject":"Re: [PATCH] docs: clarify that refs/notes/ do not keep the attached objects alive","fromName":"Martin von Zweigbergk","fromEmail":"martinvonz@google.com","sentAt":"2021-02-11T07:38:27Z","receivedAt":"2021-02-11T07:39:39Z","isPatch":true,"sender":{"key":"martinvonz@google.com","avatar":"https://avatars.githubusercontent.com/u/891642?v=4"},"body":"On Wed, Feb 10, 2021 at 9:30 PM Junio C Hamano wrote:\n>\n> Martin von Zweigbergk writes:\n>\n> > Good point. You dropped the bit about the notes (texts) being kept\n> > alive. I don't know if you did that intentionally are not.\n>\n> Yes, I did it on purpose, because it is just one of the things that\n> can be reached from refs/, but we shouldn't write our document for\n> those like me, who know what notes and other things in Git are.\n>\n> > I initially\n> > thought that we should keep that bit, but it's probably not actually\n> > very useful information. Users probably don't have large amounts of\n> > information stored in notes, so they probably don't care whether notes\n> > text is kept, especially since there's no good way of pruning the\n> > notes.\n>\n> I am not sure if I agree with any part of the above. End-user data\n> is precious no matter the volume, and we keep notes by making them\n> reachable from refs in the refs/notes/ hierarchy.\n\nSorry, I forgot to qualify that whole paragraph with something like\n\"Regarding notes attached to unreachable commits: \". Users will\nobviously not want to lose notes about reachable commits and they\nwon't. So the only remaining concern in my mind was whether they might\ncare about it because they *want* to save the space that the note\nused. Makes more sense then?\n\n> I am not sure what qualifies, in your eyes, \"good\" way, but \"git\n> notes prune\" is a good way to remove notes that are attached to\n> objects that have already been pruned away.\n\nMy paragraph above probably clarifies (that I was thinking about\nsaving the space used by notes, which I don't think `git notes prune`\nhelps with).\n"},{"id":"416721","messageId":"6cb0a3d0ab333984c35dd1026b80a2dc800d4520.1613029124.git.martinvonz@google.com","threadId":"55136","inReplyTo":"e7fde2369495f32c7aa88c7b6b74ebee1a1bed24.1613000292.git.martinvonz@google.com","subject":"[PATCH v3] docs: clarify that refs/notes/ do not keep the attached objects alive","fromName":"Martin von Zweigbergk","fromEmail":"martinvonz@google.com","sentAt":"2021-02-11T07:39:14Z","receivedAt":"2021-02-11T07:40:11Z","isPatch":true,"sender":{"key":"martinvonz@google.com","avatar":"https://avatars.githubusercontent.com/u/891642?v=4"},"body":"`git help gc` contains this snippet:\n\n \"[...] it will keep [..] objects referenced by the index,\n remote-tracking branches, notes saved by git notes under refs/notes/\"\n\nI had interpreted that as saying that the objects that notes were\nattached to are kept, but that is not the case. Let's clarify the\ndocumentation by moving out the part about git notes to a separate\nsentence.\n\nSigned-off-by: Martin von Zweigbergk \n---\n Documentation/git-gc.txt | 14 ++++++++------\n 1 file changed, 8 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt\nindex 0c114ad1ca..853967dea0 100644\n--- a/Documentation/git-gc.txt\n+++ b/Documentation/git-gc.txt\n@@ -117,12 +117,14 @@ NOTES\n 'git gc' tries very hard not to delete objects that are referenced\n anywhere in your repository. In particular, it will keep not only\n objects referenced by your current set of branches and tags, but also\n-objects referenced by the index, remote-tracking branches, notes saved\n-by 'git notes' under refs/notes/, reflogs (which may reference commits\n-in branches that were later amended or rewound), and anything else in\n-the refs/* namespace. If you are expecting some objects to be deleted\n-and they aren't, check all of those locations and decide whether it\n-makes sense in your case to remove those references.\n+objects referenced by the index, remote-tracking branches, reflogs\n+(which may reference commits in branches that were later amended or\n+rewound), and anything else in the refs/* namespace. Note that a note\n+(of the kind created by 'git notes') attached to an object does not\n+contribute in keeping the object alive. If you are expecting some\n+objects to be deleted and they aren't, check all of those locations\n+and decide whether it makes sense in your case to remove those\n+references.\n \n On the other hand, when 'git gc' runs concurrently with another process,\n there is a risk of it deleting an object that the other process is using\n-- \n2.30.1.379.ge7fde23694\n\n"},{"id":"416722","messageId":"xmqqy2fvxd5f.fsf@gitster.c.googlers.com","threadId":"55136","inReplyTo":"6cb0a3d0ab333984c35dd1026b80a2dc800d4520.1613029124.git.martinvonz@google.com","subject":"Re: [PATCH v3] docs: clarify that refs/notes/ do not keep the attached objects alive","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-02-11T07:43:40Z","receivedAt":"2021-02-11T07:44:44Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Martin von Zweigbergk writes:\n\n> `git help gc` contains this snippet:\n>\n> \"[...] it will keep [..] objects referenced by the index,\n> remote-tracking branches, notes saved by git notes under refs/notes/\"\n>\n> I had interpreted that as saying that the objects that notes were\n> attached to are kept, but that is not the case. Let's clarify the\n> documentation by moving out the part about git notes to a separate\n> sentence.\n>\n> Signed-off-by: Martin von Zweigbergk \n> ---\n> Documentation/git-gc.txt | 14 ++++++++------\n> 1 file changed, 8 insertions(+), 6 deletions(-)\n\nThanks. Will replace and queue.\n\n\n> diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt\n> index 0c114ad1ca..853967dea0 100644\n> --- a/Documentation/git-gc.txt\n> +++ b/Documentation/git-gc.txt\n> @@ -117,12 +117,14 @@ NOTES\n> 'git gc' tries very hard not to delete objects that are referenced\n> anywhere in your repository. In particular, it will keep not only\n> objects referenced by your current set of branches and tags, but also\n> -objects referenced by the index, remote-tracking branches, notes saved\n> -by 'git notes' under refs/notes/, reflogs (which may reference commits\n> -in branches that were later amended or rewound), and anything else in\n> -the refs/* namespace. If you are expecting some objects to be deleted\n> -and they aren't, check all of those locations and decide whether it\n> -makes sense in your case to remove those references.\n> +objects referenced by the index, remote-tracking branches, reflogs\n> +(which may reference commits in branches that were later amended or\n> +rewound), and anything else in the refs/* namespace. Note that a note\n> +(of the kind created by 'git notes') attached to an object does not\n> +contribute in keeping the object alive. If you are expecting some\n> +objects to be deleted and they aren't, check all of those locations\n> +and decide whether it makes sense in your case to remove those\n> +references.\n> \n> On the other hand, when 'git gc' runs concurrently with another process,\n> there is a risk of it deleting an object that the other process is using\n"}]}