{"thread":{"id":"41897","subject":"[PATCH] doc: clarify that notes can be attached to any type of stored object","startedAt":"2016-04-01T10:09:10Z","lastAt":"2016-04-04T18:04:26Z","messageCount":8,"participants":["Sebastian Schuberth","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"282438","messageId":"56FE48C6.9050306@gmail.com","threadId":"41897","inReplyTo":null,"subject":"[PATCH] doc: clarify that notes can be attached to any type of stored object","fromName":"Sebastian Schuberth","fromEmail":"sschuberth@gmail.com","sentAt":"2016-04-01T10:09:10Z","receivedAt":"2016-04-01T10:09:10Z","isPatch":true,"sender":{"key":"sschuberth@gmail.com","avatar":"https://avatars.githubusercontent.com/u/349154?v=4"},"body":"Signed-off-by: Sebastian Schuberth \n---\n Documentation/git-notes.txt | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 8de3499..5375d98 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -234,8 +234,9 @@ which operation triggered the update, and the commit authorship is\n determined according to the usual rules (see linkgit:git-commit[1]).\n These details may change in the future.\n \n-It is also permitted for a notes ref to point directly to a tree\n-object, in which case the history of the notes can be read with\n+It is also permitted for a notes ref to point to any other object in\n+the object store besides commit objects, that is annotated tags, blobs\n+or trees. For the latter, the history of the notes can be read with\n `git log -p -g `.\n \n \n-- \n2.8.0.windows.1\n"},{"id":"282468","messageId":"xmqqy48xjqg5.fsf@gitster.mtv.corp.google.com","threadId":"41897","inReplyTo":"56FE48C6.9050306@gmail.com","subject":"Re: [PATCH] doc: clarify that notes can be attached to any type of stored object","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-04-01T15:31:38Z","receivedAt":"2016-04-01T15:31:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sebastian Schuberth writes:\n\n> Signed-off-by: Sebastian Schuberth \n> ---\n> Documentation/git-notes.txt | 5 +++--\n> 1 file changed, 3 insertions(+), 2 deletions(-)\n>\n> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\n> index 8de3499..5375d98 100644\n> --- a/Documentation/git-notes.txt\n> +++ b/Documentation/git-notes.txt\n> @@ -234,8 +234,9 @@ which operation triggered the update, and the commit authorship is\n> determined according to the usual rules (see linkgit:git-commit[1]).\n> These details may change in the future.\n> \n> -It is also permitted for a notes ref to point directly to a tree\n> -object, in which case the history of the notes can be read with\n> +It is also permitted for a notes ref to point to any other object in\n> +the object store besides commit objects, that is annotated tags, blobs\n> +or trees. For the latter, the history of the notes can be read with\n> `git log -p -g `.\n\nI do not think this is correct place to patch. The original is not\ntalking about what objects can have notes attached at all. What it\nexplains is this.\n\n aka refs/notes/ (where typically is\n \"commit\") is usually a commit, whose tree is a notes-shaped\n tree. The (normal) history you get by following the parent link\n of the commit represents how the entire set of notes evolved.\n However, it is OK for the to point directly to a tree,\n which is a notes-shaped one, without an enclosing commit. You\n would lose the normal way to learn how the entire set of notes\n evolved, but you could do \"git log -p -g \", i.e. by\n following its reflog, to pretend as if the history is recorded.\n\nThere is no way a blob can be pointed by there and expect\nit to work sensibly at all.\n"},{"id":"282481","messageId":"xmqq8u0xjmxh.fsf@gitster.mtv.corp.google.com","threadId":"41897","inReplyTo":"xmqqy48xjqg5.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] doc: clarify that notes can be attached to any type of stored object","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-04-01T16:47:38Z","receivedAt":"2016-04-01T16:47:38Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> Sebastian Schuberth writes:\n>\n>> Signed-off-by: Sebastian Schuberth \n>> ---\n>> Documentation/git-notes.txt | 5 +++--\n>> 1 file changed, 3 insertions(+), 2 deletions(-)\n>>\n> I do not think this is correct place to patch.\n\nSo,... where is the right place?\n\nLet's disect what we have in the DESCRIPTION section.\n\n DESCRIPTION\n -----------\n Adds, removes, or reads notes attached to objects, without touching\n the objects themselves.\n\nThis says \"notes attached to objects\" and \"the objects themselves\".\nThey do not limit the target of attaching a note to \"commits\".\nSo this may be the place to add \" Note that notes can be attached\nto any kind of objects, not limited to commits\" or something, if\nwe really wanted to.\n\n By default, notes are saved to and read from `refs/notes/commits`, but\n this default can be overridden. See the OPTIONS, CONFIGURATION, and\n ENVIRONMENT sections below. If this ref does not exist, it will be\n quietly created when it is first needed to store a note.\n\n A typical use of notes is to supplement a commit message without\n changing the commit itself. Notes can be shown by 'git log' along with\n the original commit message. To distinguish these notes from the\n message stored in the commit object, the notes are indented like the\n message, after an unindented line saying \"Notes ():\" (or\n \"Notes:\" for `refs/notes/commits`).\n\n Notes can also be added to patches prepared with `git format-patch` by\n using the `--notes` option. Such notes are added as a patch commentary\n after a three dash separator line.\n\nThis paragraph _might_ be confusing to new readers. The \"added to\"\nsounds as if you are attaching a note to a non-object which is a\npatch. But this \"add\" is about \"inserting the contents of the note\nattached to the commit being formatted\" and corresponds to \"can be\nshown by\" in the previous paragraph. We may want to avoid the verb\n\"add\" when talking about the use of data stored in an existing note\nto somewhere else like this.\n\n To change which notes are shown by 'git log', see the\n \"notes.displayRef\" configuration in linkgit:git-log[1].\n\n See the \"notes.rewrite.\" configuration for a way to carry\n notes across commands that rewrite commits.\n\n\n\n SUBCOMMANDS\n -----------\n\n list::\n List the notes object for a given object. If no object is\n given, show a list of all note objects and the objects they\n annotate (in the format \" \").\n This is the default subcommand if no subcommand is given.\n\n add::\n Add notes for a given object (defaults to HEAD). Abort if the\n\nAnd this \"Add notes for \" should probably be reworded to \"Attach\nnotes to\" to match the first sentence in the description.\n\n object already has notes (use `-f` to overwrite existing notes).\n However, if you're using `add` interactively (using an editor\n to supply the notes contents), then - instead of aborting -\n the existing notes will be opened in the editor (like the `edit`\n subcommand).\n"},{"id":"282606","messageId":"CAHGBnuPkPqJprOxR4zBuWitXqXt9XtpnjGPQWEv+-pYovh1b+A@mail.gmail.com","threadId":"41897","inReplyTo":"xmqqy48xjqg5.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] doc: clarify that notes can be attached to any type of stored object","fromName":"Sebastian Schuberth","fromEmail":"sschuberth@gmail.com","sentAt":"2016-04-04T08:10:38Z","receivedAt":"2016-04-04T08:10:38Z","isPatch":true,"sender":{"key":"sschuberth@gmail.com","avatar":"https://avatars.githubusercontent.com/u/349154?v=4"},"body":"On Fri, Apr 1, 2016 at 5:31 PM, Junio C Hamano wrote:\n\n> Sebastian Schuberth writes:\n>\n>> Signed-off-by: Sebastian Schuberth \n>> ---\n>> Documentation/git-notes.txt | 5 +++--\n>> 1 file changed, 3 insertions(+), 2 deletions(-)\n>>\n>> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\n>> index 8de3499..5375d98 100644\n>> --- a/Documentation/git-notes.txt\n>> +++ b/Documentation/git-notes.txt\n>> @@ -234,8 +234,9 @@ which operation triggered the update, and the commit authorship is\n>> determined according to the usual rules (see linkgit:git-commit[1]).\n>> These details may change in the future.\n>>\n>> -It is also permitted for a notes ref to point directly to a tree\n>> -object, in which case the history of the notes can be read with\n>> +It is also permitted for a notes ref to point to any other object in\n>> +the object store besides commit objects, that is annotated tags, blobs\n>> +or trees. For the latter, the history of the notes can be read with\n>> `git log -p -g `.\n>\n> I do not think this is correct place to patch. The original is not\n> talking about what objects can have notes attached at all. What it\n> explains is this.\n\nThanks for the explanation, I was indeed misreading this. I'll try to\nclarify this section then, too. In order to do so, I think we should\nmention how to actually create a that directly points to a\ntree instead of a commit for the history of notes. Would you have an\nexample how to do that?\n\n-- \nSebastian Schuberth\n"},{"id":"282608","messageId":"CAHGBnuP71qpOoNAAwXE-nbPbVyK56Up0YpmhhjC5430VwW73kQ@mail.gmail.com","threadId":"41897","inReplyTo":"xmqq8u0xjmxh.fsf@gitster.mtv.corp.google.com","subject":"Re: [PATCH] doc: clarify that notes can be attached to any type of stored object","fromName":"Sebastian Schuberth","fromEmail":"sschuberth@gmail.com","sentAt":"2016-04-04T08:33:56Z","receivedAt":"2016-04-04T08:33:56Z","isPatch":true,"sender":{"key":"sschuberth@gmail.com","avatar":"https://avatars.githubusercontent.com/u/349154?v=4"},"body":"On Fri, Apr 1, 2016 at 6:47 PM, Junio C Hamano wrote:\n\n> DESCRIPTION\n> -----------\n> Adds, removes, or reads notes attached to objects, without touching\n> the objects themselves.\n>\n> This says \"notes attached to objects\" and \"the objects themselves\".\n> They do not limit the target of attaching a note to \"commits\".\n> So this may be the place to add \" Note that notes can be attached\n> to any kind of objects, not limited to commits\" or something, if\n> we really wanted to.\n\nDone, I'll send a patch shortly. But I wanted to list the supported\nobject types explicitly, in particular as many guide in the net are\nunclear that only annotated tags are object, and lightweight ones are\nnot.\n\n> Notes can also be added to patches prepared with `git format-patch` by\n> using the `--notes` option. Such notes are added as a patch commentary\n> after a three dash separator line.\n>\n> This paragraph _might_ be confusing to new readers. The \"added to\"\n> sounds as if you are attaching a note to a non-object which is a\n> patch. But this \"add\" is about \"inserting the contents of the note\n> attached to the commit being formatted\" and corresponds to \"can be\n> shown by\" in the previous paragraph. We may want to avoid the verb\n> \"add\" when talking about the use of data stored in an existing note\n> to somewhere else like this.\n\nDone.\n\n> add::\n> Add notes for a given object (defaults to HEAD). Abort if the\n>\n> And this \"Add notes for \" should probably be reworded to \"Attach\n> notes to\" to match the first sentence in the description.\n\nAfter a bit of thinking, I don't believe we should do this. All\nsubcommand docs start with the verb the subcommand is named after. In\nthat sense making the \"add\" docs start with \"Attach\" would be\ninconsistent and probably raise the question why the subcommand is not\ncalled \"attach\" after all. Also, in the description it says \"Adds,\nremoves, or reads notes attached to objects\", so it includes \"[...]\nremoves [...] notes attached to objects\", and if you read it like this\nthe word \"attach\" is not specific to the \"add\" subcommand. So I left\nthis as-is in my patch.\n\n-- \nSebastian Schuberth\n"},{"id":"282609","messageId":"570227DA.6040808@gmail.com","threadId":"41897","inReplyTo":"CAHGBnuP71qpOoNAAwXE-nbPbVyK56Up0YpmhhjC5430VwW73kQ@mail.gmail.com","subject":"[PATCH] doc: Clarify which objects notes can be attached to","fromName":"Sebastian Schuberth","fromEmail":"sschuberth@gmail.com","sentAt":"2016-04-04T08:37:46Z","receivedAt":"2016-04-04T08:37:46Z","isPatch":true,"sender":{"key":"sschuberth@gmail.com","avatar":"https://avatars.githubusercontent.com/u/349154?v=4"},"body":"Explicitly name the supported object types, and ensure patches cannot be\nmisinterpreted as non-objects that can have notes attached.\n\nSigned-off-by: Sebastian Schuberth \n---\n Documentation/git-notes.txt | 9 +++++----\n 1 file changed, 5 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 8de3499..101e6ba 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -25,7 +25,8 @@ SYNOPSIS\n DESCRIPTION\n -----------\n Adds, removes, or reads notes attached to objects, without touching\n-the objects themselves.\n+the objects themselves. Supported objects are commits, blobs, trees\n+and annotated tags.\n \n By default, notes are saved to and read from `refs/notes/commits`, but\n this default can be overridden. See the OPTIONS, CONFIGURATION, and\n@@ -39,9 +40,9 @@ message stored in the commit object, the notes are indented like the\n message, after an unindented line saying \"Notes ():\" (or\n \"Notes:\" for `refs/notes/commits`).\n \n-Notes can also be added to patches prepared with `git format-patch` by\n-using the `--notes` option. Such notes are added as a patch commentary\n-after a three dash separator line.\n+Notes contents can also be included in patches prepared with\n+`git format-patch` by using the `--notes` option. Such notes are added\n+as a patch commentary after a three dash separator line.\n \n To change which notes are shown by 'git log', see the\n \"notes.displayRef\" configuration in linkgit:git-log[1].\n-- \n2.8.0.windows.1\n"},{"id":"282618","messageId":"xmqqy48t5nvo.fsf@gitster.mtv.corp.google.com","threadId":"41897","inReplyTo":"CAHGBnuP71qpOoNAAwXE-nbPbVyK56Up0YpmhhjC5430VwW73kQ@mail.gmail.com","subject":"Re: [PATCH] doc: clarify that notes can be attached to any type of stored object","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-04-04T16:39:55Z","receivedAt":"2016-04-04T16:39:55Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sebastian Schuberth writes:\n\n> Done, I'll send a patch shortly. But I wanted to list the supported\n> object types explicitly, in particular as many guide in the net are\n> unclear that only annotated tags are object, and lightweight ones are\n> not.\n\nI'd really hate to see an explicit list of what object types there\nare, as it is one more place we'd need to update if we ever add new\nobject types (and we are unlikely to do so anytime soon, which makes\nit even more likely that we would forget there is this explicit list\nwe'd need to update).\n\n- Adds, removes, or reads notes attached to objects, without touching\n- the objects themselves.\n+ Adds, removes, or reads notes attached to any object (not limited\n+ to commit objects), without touching the objects themselves.\n\nshould be sufficient, no?\n"},{"id":"282635","messageId":"xmqqzit945ed.fsf@gitster.mtv.corp.google.com","threadId":"41897","inReplyTo":"CAHGBnuPkPqJprOxR4zBuWitXqXt9XtpnjGPQWEv+-pYovh1b+A@mail.gmail.com","subject":"Re: [PATCH] doc: clarify that notes can be attached to any type of stored object","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2016-04-04T18:04:26Z","receivedAt":"2016-04-04T18:04:26Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Sebastian Schuberth writes:\n\n>>> -It is also permitted for a notes ref to point directly to a tree\n>>> -object, in which case the history of the notes can be read with\n>>> +It is also permitted for a notes ref to point to any other object in\n>>> +the object store besides commit objects, that is annotated tags, blobs\n>>> +or trees. For the latter, the history of the notes can be read with\n>>> `git log -p -g `.\n>>\n>> I do not think this is correct place to patch. The original is not\n>> talking about what objects can have notes attached at all. What it\n>> explains is this.\n>\n> Thanks for the explanation, I was indeed misreading this. I'll try to\n> clarify this section then, too. In order to do so, I think we should\n> mention how to actually create a that directly points to a\n> tree instead of a commit for the history of notes. Would you have an\n> example how to do that?\n\nInteresting. This came from 9eb3f816 (Documentation/notes: document\nformat of notes trees, 2010-05-08):\n\n Documentation/notes: document format of notes trees\n\n Separate the specification of the notes format exposed in\n git-config.1 from the description of the option; or in other\n words, move the explanation for what to expect to find at\n refs/notes/commits from git-config.1 to git-notes.1.\n\n Suggested-by: Thomas Rast \n Signed-off-by: Jonathan Nieder \n Signed-off-by: Junio C Hamano \n\nbut I do not find a corresponding sentence that says a notes ref can\npoint at a tree in the text before the patch.\n\nI highly suspect that \"git notes add\" and other Porcelain level\ncommands that manipulate an existing notes tree would be unhappy if\na notes ref is not a commit, as it is clear from the paragraph\nbefore the one under discussion, i.e.\n\n Every notes change creates a new commit at the specified notes ref.\n You can therefore inspect the history of the notes by invoking, e.g.,\n `git log -p notes/commits`. Currently the commit message only records\n which operation triggered the update, and the commit authorship is\n determined according to the usual rules (see linkgit:git-commit[1]).\n These details may change in the future.\n\nthat in order to create a \"new\" commit, setting the current one as\nits parent, would require that the current one to be a commit and\nnot a bare tree. \"git notes list\" and others that merely read from\nthe notes tree would probably work.\n"}]}