{"thread":{"id":"23689","subject":"[PATCH 0/4] Documentation/notes: fill out the man page a little","startedAt":"2010-05-03T23:36:05Z","lastAt":"2010-05-05T03:23:10Z","messageCount":11,"participants":["Jonathan Nieder","Thomas Rast","Johan Herland","Jeff King"],"isPatch":true,"patchVersion":1,"patchTotal":4},"messages":[{"id":"140862","messageId":"20100503233604.GA27451@progeny.tock","threadId":"23689","inReplyTo":null,"subject":"[PATCH 0/4] Documentation/notes: fill out the man page a little","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-03T23:36:05Z","receivedAt":"2010-05-03T23:36:05Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"I decided it’s time I learn to use notes. Here’s a by-product.\n\nThoughts?\nJonathan Nieder (4):\n Documentation/notes: describe effect of environment and configuration\n Documentation/notes: adjust description to use configuration section\n Documentation/notes: describe content of notes\n Documentation/notes: nitpicks\n\n Documentation/git-notes.txt | 114 +++++++++++++++++++++++++++++++++++++------\n 1 files changed, 99 insertions(+), 15 deletions(-)\n"},{"id":"140863","messageId":"20100503234140.GA27483@progeny.tock","threadId":"23689","inReplyTo":"20100503233604.GA27451@progeny.tock","subject":"[PATCH 1/4] Documentation/notes: describe effect of environment and configuration","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-03T23:41:40Z","receivedAt":"2010-05-03T23:41:40Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Based on the description from Documentation/config.txt.\n\nFor now, this does not share text with Documentation/config.txt\nbecause that makes it easier to think about how to describe the\nenvironment variables.\n\nCc: Thomas Rast \nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-notes.txt | 82 +++++++++++++++++++++++++++++++++++++++++++\n 1 files changed, 82 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 4e5113b..b26598e 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -135,6 +135,88 @@ usual rules (see linkgit:git-commit[1]). These details may change in\n the future.\n \n \n+CONFIGURATION\n+-------------\n+\n+core.notesRef::\n+\tBy default, 'git notes' and other commands read and manipulate\n+\tthe notes referred to by `refs/notes/commits`. This\n+\tconfiguration item allows one to specify an alternative\n+\tdefault ref (to be overridden by environment variables or\n+\tcommand-line options).\n+\n+notes.displayRef::\n+\tWhich refs, in addition to the default set by `core.notesRef`\n+\tor 'GIT_NOTES_REF', for 'git log' to read notes from when\n+\tshowing commit messages. Can be a (fully qualified) ref name\n+\tor glob. You may also specify this configuration variable\n+\tseveral times.\n++\n+This setting can be overridden with the 'GIT_NOTES_DISPLAY_REF'\n+environment variable.\n+\n+notes.rewrite.::\n+\tWhen rewriting commits with (currently `amend` or\n+\t`rebase`), if this variable is `false`, git will not copy\n+\tnotes from the original to the rewritten commit. Defaults to\n+\t`true`. See also \"`notes.rewriteRef`\" below.\n++\n+This setting can be overridden by the 'GIT_NOTES_REWRITE_REF'\n+environment variable.\n+\n+notes.rewriteMode::\n+\tWhen copying notes during a rewrite, what to do if the target\n+\tcommit already has a note. Must be one of `overwrite`,\n+\t`concatenate`, or `ignore`. Defaults to `concatenate`.\n++\n+This setting can be overridden with the `GIT_NOTES_REWRITE_MODE`\n+environment variable.\n+\n+notes.rewriteRef::\n+\tWhen copying notes during a rewrite, specifies the (fully\n+\tqualified) ref whose notes should be copied. May be a glob,\n+\tin which case notes in all matching refs will be copied. You\n+\tmay also specify this configuration several times.\n++\n+Does not have a default value. Configure this variable to enable note\n+rewriting.\n++\n+Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable.\n+\n+See linkgit:git-config[1] for details.\n+\n+ENVIRONMENT\n+-----------\n+\n+'GIT_NOTES_REF'::\n+\tWhich ref to manipulate notes from, instead of `refs/notes/commits`.\n+\tThis overrides the `core.notesRef` setting.\n+\n+'GIT_NOTES_DISPLAY_REF'::\n+\tWhich refs, in addition to the default from `core.notesRef` or\n+\t'GIT_NOTES_REF', to read notes from when showing commit\n+\tmessages.\n+\tMust be a colon-delimited list of refs or globs.\n+\tThis overrides the `notes.displayRef` setting.\n++\n+A warning will be issued for refs that do not exist, but a glob that\n+does not match any refs is silently ignored.\n+\n+'GIT_NOTES_REWRITE_MODE'::\n+\tWhen copying notes during a rewrite, what to do if the target\n+\tcommit already has a note.\n+\tMust be one of `overwrite`, `concatenate`, or `ignore`.\n+\tThis overrides the `core.rewriteMode` setting.\n+\n+'GIT_NOTES_REWRITE_REF'::\n+\tWhen rewriting commits, which notes to copy from the original\n+\tto the rewritten commit. Must be a colon-delimited list of\n+\trefs or globs.\n++\n+If not set in the environment, the list of notes to copy will depend\n+on the `notes.rewrite.` and `notes.rewriteRef` settings.\n+\n+\n Author\n ------\n Written by Johannes Schindelin and\n-- \n1.7.1\n"},{"id":"140865","messageId":"20100503234209.GB27483@progeny.tock","threadId":"23689","inReplyTo":"20100503233604.GA27451@progeny.tock","subject":"[PATCH 2/4] Documentation/notes: adjust description to use configuration section","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-03T23:42:09Z","receivedAt":"2010-05-03T23:42:09Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Introduce the default notes ref early on to give the reader a frame of\nreference for understanding the rest of the description.\n\nCc: Johan Herland \nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-notes.txt | 14 ++++++--------\n 1 files changed, 6 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex b26598e..0594776 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -23,6 +23,10 @@ DESCRIPTION\n This command allows you to add/remove notes to/from objects, without\n changing the objects themselves.\n \n+By default, notes are saved to and read from `refs/notes/commits`, but\n+this default can be overridden. See the CONFIGURATION and ENVIRONMENT\n+sections below.\n+\n A typical use of notes is to extend a commit message without having\n to change the commit itself. Such commit notes can be shown by `git log`\n along with the original commit message. To discern these notes from the\n@@ -30,14 +34,8 @@ message stored in the commit object, the notes are indented like the\n message, after an unindented line saying \"Notes ():\" (or\n \"Notes:\" for the default setting).\n \n-This command always manipulates the notes specified in \"core.notesRef\"\n-(see linkgit:git-config[1]), which can be overridden by GIT_NOTES_REF.\n-To change which notes are shown by 'git-log', see the\n-\"notes.displayRef\" configuration.\n-\n-See the description of \"notes.rewrite.\" in\n-linkgit:git-config[1] for a way of carrying your notes across commands\n-that rewrite commits.\n+See the \"notes.rewrite.\" configuration for a way of carrying\n+notes across commands that rewrite commits.\n \n \n SUBCOMMANDS\n-- \n1.7.1\n"},{"id":"140864","messageId":"20100503234229.GC27483@progeny.tock","threadId":"23689","inReplyTo":"20100503233604.GA27451@progeny.tock","subject":"[PATCH 3/4] Documentation/notes: describe content of notes","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-03T23:42:29Z","receivedAt":"2010-05-03T23:42:29Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Signed-off-by: Jonathan Nieder \n---\n Documentation/git-notes.txt | 4 ++++\n 1 files changed, 4 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 0594776..273264b 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -27,6 +27,10 @@ By default, notes are saved to and read from `refs/notes/commits`, but\n this default can be overridden. See the CONFIGURATION and ENVIRONMENT\n sections below.\n \n+Notes can contain any sequence of non-null bytes. Since they are\n+sanitized with linkgit:git-stripspace[1], empty lines other than a\n+single line separating paragraphs are not significant.\n+\n A typical use of notes is to extend a commit message without having\n to change the commit itself. Such commit notes can be shown by `git log`\n along with the original commit message. To discern these notes from the\n-- \n1.7.1\n"},{"id":"140867","messageId":"20100503234720.GD27483@progeny.tock","threadId":"23689","inReplyTo":"20100503233604.GA27451@progeny.tock","subject":"[PATCH 4/4] Documentation/notes: nitpicks","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-03T23:47:20Z","receivedAt":"2010-05-03T23:47:20Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Spell out “or” in the NAME line and simplify the leading sentence\nin the DESCRIPTION.\n\nSome other language cleanups, too.\n\nSigned-off-by: Jonathan Nieder \n---\nThat’s the end of the series. Nothing dramatic, but I thought this\nbasic information could help. Thanks for looking it over.\n\nWhile I have your attention: the original man page said\n\n To disable commit notes, you have to set the config variable\n core.notesRef to the empty string. Alternatively, you can set it\n to a different ref, something like \"refs/notes/bugzilla\". This setting\n can be overridden by the environment variable \"GIT_NOTES_REF\".\n\nwhich sounds helpful to me, both as an example and as a way to help\npeople who do not want to use the feature. Any idea where we could\nadd it back?\n\n Documentation/git-notes.txt | 16 ++++++++--------\n 1 files changed, 8 insertions(+), 8 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 273264b..b953575 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -3,7 +3,7 @@ git-notes(1)\n \n NAME\n ----\n-git-notes - Add/inspect object notes\n+git-notes - Add or inspect object notes\n \n SYNOPSIS\n --------\n@@ -20,8 +20,8 @@ SYNOPSIS\n \n DESCRIPTION\n -----------\n-This command allows you to add/remove notes to/from objects, without\n-changing the objects themselves.\n+Adds, removes, or reads notes attached to objects, without touching\n+the objects themselves.\n \n By default, notes are saved to and read from `refs/notes/commits`, but\n this default can be overridden. See the CONFIGURATION and ENVIRONMENT\n@@ -31,14 +31,14 @@ Notes can contain any sequence of non-null bytes. Since they are\n sanitized with linkgit:git-stripspace[1], empty lines other than a\n single line separating paragraphs are not significant.\n \n-A typical use of notes is to extend a commit message without having\n-to change the commit itself. Such commit notes can be shown by `git log`\n-along with the original commit message. To discern these notes from the\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 the default setting).\n+\"Notes:\" for the main notes ref).\n \n-See the \"notes.rewrite.\" configuration for a way of carrying\n+See the \"notes.rewrite.\" configuration for a way to carry\n notes across commands that rewrite commits.\n \n \n-- \n1.7.1\n"},{"id":"140891","messageId":"201005040909.43247.trast@student.ethz.ch","threadId":"23689","inReplyTo":"20100503234720.GD27483@progeny.tock","subject":"Re: [PATCH 4/4] Documentation/notes: nitpicks","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-05-04T07:09:42Z","receivedAt":"2010-05-04T07:09:42Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Jonathan Nieder wrote:\n> -A typical use of notes is to extend a commit message without having\n> -to change the commit itself. Such commit notes can be shown by `git log`\n> -along with the original commit message. To discern these notes from the\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 the default setting).\n> +\"Notes:\" for the main notes ref).\n\nNitpick on your nitpick: we do not call refs/notes/commits the \"main\"\nnotes ref anywhere, and you don't seem to introduce this terminology.\n\nThe user might infer that \"main\" means core.notesRef, but the omission\nof () is actually hardcoded to only happen for\nrefs/notes/commits, so that's not correct.\n\n\n[I'll review the other patches after the lecture.]\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"140893","messageId":"20100504072317.GA8410@progeny.tock","threadId":"23689","inReplyTo":"201005040909.43247.trast@student.ethz.ch","subject":"Re: [PATCH 4/4] Documentation/notes: nitpicks","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-04T07:23:17Z","receivedAt":"2010-05-04T07:23:17Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Thomas Rast wrote:\n> Jonathan Nieder wrote:\n\n>> -A typical use of notes is to extend a commit message without having\n>> -to change the commit itself. Such commit notes can be shown by `git log`\n>> -along with the original commit message. To discern these notes from the\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 the default setting).\n>> +\"Notes:\" for the main notes ref).\n[...]\n> The user might infer that \"main\" means core.notesRef, but the omission\n> of () is actually hardcoded to only happen for\n> refs/notes/commits, so that's not correct.\n\nOh! I had no inkling.\n\nI guess the simplest way to document this is to just say it:\n\n\t ... unindented line saying \"Notes ():' (or\n\t\"Notes:\" for refs/notes/commits).\n\nThanks for the explanation.\n\nCheers,\nJonathan\n"},{"id":"140897","messageId":"201005041124.26533.trast@student.ethz.ch","threadId":"23689","inReplyTo":"20100503234140.GA27483@progeny.tock","subject":"Re: [PATCH 1/4] Documentation/notes: describe effect of environment and configuration","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-05-04T09:24:26Z","receivedAt":"2010-05-04T09:24:26Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Jonathan Nieder wrote:\n> +core.notesRef::\n> +\tBy default, 'git notes' and other commands read and manipulate\n> +\tthe notes referred to by `refs/notes/commits`. This\n> +\tconfiguration item allows one to specify an alternative\n> +\tdefault ref (to be overridden by environment variables or\n> +\tcommand-line options).\n> +\n> +notes.displayRef::\n> +\tWhich refs, in addition to the default set by `core.notesRef`\n> +\tor 'GIT_NOTES_REF', for 'git log' to read notes from when\n> +\tshowing commit messages. Can be a (fully qualified) ref name\n> +\tor glob. You may also specify this configuration variable\n> +\tseveral times.\n> ++\n> +This setting can be overridden with the 'GIT_NOTES_DISPLAY_REF'\n> +environment variable.\n\nI noticed you copied the rest of the description, but not these,\nverbatim. If the intention was to separate the specification of the\nnotes format exposed in git-config(1),\n\n [...] This ref is expected to contain files named after the full\n SHA-1 of the commit they annotate. The ref must be fully\n qualified.\n\n If such a file exists in the given ref, the referenced blob is\n read, and appended to the commit message, separated by a \"Notes\n ():\" line (shortened to \"Notes:\" in the case of\n \"refs/notes/commits\"). If the given ref itself does not exist, it\n is not an error, but means that no notes should be printed.\n\nfrom the description of the option. I agree to the idea, but maybe we\nshould also do the same in git-config(1). For example, it could be\nadded to the NOTES section of git-notes(1) that already describes some\nimplementation details.\n\nYou also describe the warning semantics only for\nGIT_NOTES_DISPLAY_REF, not for notes.displayRef. I see the config\noptions as the main feature, and the variable as a mere convenience\n(but others may disagree) so I would put the full semantics into the\nconfig descriptions.\n\nOtherwise, ack.\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"140898","messageId":"201005041128.47879.trast@student.ethz.ch","threadId":"23689","inReplyTo":"20100503234229.GC27483@progeny.tock","subject":"Re: [PATCH 3/4] Documentation/notes: describe content of notes","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-05-04T09:28:47Z","receivedAt":"2010-05-04T09:28:47Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Jonathan Nieder wrote:\n> +Notes can contain any sequence of non-null bytes. Since they are\n> +sanitized with linkgit:git-stripspace[1], empty lines other than a\n> +single line separating paragraphs are not significant.\n\nIt even goes slightly further: create_note() calls stripspace() with\nthe skip_comments option enabled, so comment lines are also removed.\n('git notes add' actually puts `git show --stat` in a big comment\nblock...)\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"140900","messageId":"201005041155.02192.johan@herland.net","threadId":"23689","inReplyTo":"20100503234229.GC27483@progeny.tock","subject":"Re: [PATCH 3/4] Documentation/notes: describe content of notes","fromName":"Johan Herland","fromEmail":"johan@herland.net","sentAt":"2010-05-04T09:55:01Z","receivedAt":"2010-05-04T09:55:01Z","isPatch":true,"sender":{"key":"johan@herland.net","avatar":"https://avatars.githubusercontent.com/u/547031?v=4"},"body":"On Tuesday 04 May 2010, Jonathan Nieder wrote:\n> Signed-off-by: Jonathan Nieder \n> ---\n> Documentation/git-notes.txt | 4 ++++\n> 1 files changed, 4 insertions(+), 0 deletions(-)\n> \n> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\n> index 0594776..273264b 100644\n> --- a/Documentation/git-notes.txt\n> +++ b/Documentation/git-notes.txt\n> @@ -27,6 +27,10 @@ By default, notes are saved to and read from\n> `refs/notes/commits`, but this default can be overridden. See the\n> CONFIGURATION and ENVIRONMENT sections below.\n> \n> +Notes can contain any sequence of non-null bytes. Since they are\n> +sanitized with linkgit:git-stripspace[1], empty lines other than a\n> +single line separating paragraphs are not significant.\n\nIn principle, a note is a regular Git (blob) object, and can contain NUL \nbytes - indeed any kind of (non-)format is accepted.\n\nHowever, the stripspace/text-based formatting kicks in when specifying the \nnotes content with -m or -F, or when an editor is used to edit the notes.\n\nSo as long as you stick to the following subcommands, notes should be \ncompletely binary-safe:\n\n- git notes [list []]\n- git notes add [-f] -C \n- git notes copy [-f] \n- git notes show []\n- git notes remove []\n- git notes prune\n\nIn other words, you can (binary-safely) create notes from files with the \nfollowing construct:\n\n git notes add -C $(git hash-object -w ) \n\nOf course, it doesn't make much sense displaying non-text-format notes with \n'git log', so if you use such notes you'll probably need to write some \nspecial-purpose tools for doing anything useful with them.\n\nOtherwise, your other 3 patches seem fine to me (modulo Thomas Rast's \ncomments) and you can consider them\nAcked-by: Johan Herland \n\n\nHave fun! :)\n\n...Johan\n\n-- \nJohan Herland, \nwww.herland.net\n"},{"id":"140957","messageId":"20100505032310.GA8779@coredump.intra.peff.net","threadId":"23689","inReplyTo":"201005041155.02192.johan@herland.net","subject":"Re: [PATCH 3/4] Documentation/notes: describe content of notes","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-05-05T03:23:10Z","receivedAt":"2010-05-05T03:23:10Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, May 04, 2010 at 11:55:01AM +0200, Johan Herland wrote:\n\n> On Tuesday 04 May 2010, Jonathan Nieder wrote:\n> > Signed-off-by: Jonathan Nieder \n> > ---\n> > Documentation/git-notes.txt | 4 ++++\n> > 1 files changed, 4 insertions(+), 0 deletions(-)\n> > \n> > diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\n> > index 0594776..273264b 100644\n> > --- a/Documentation/git-notes.txt\n> > +++ b/Documentation/git-notes.txt\n> > @@ -27,6 +27,10 @@ By default, notes are saved to and read from\n> > `refs/notes/commits`, but this default can be overridden. See the\n> > CONFIGURATION and ENVIRONMENT sections below.\n> > \n> > +Notes can contain any sequence of non-null bytes. Since they are\n> > +sanitized with linkgit:git-stripspace[1], empty lines other than a\n> > +single line separating paragraphs are not significant.\n> \n> In principle, a note is a regular Git (blob) object, and can contain NUL \n> bytes - indeed any kind of (non-)format is accepted.\n> \n> However, the stripspace/text-based formatting kicks in when specifying the \n> notes content with -m or -F, or when an editor is used to edit the notes.\n\nThe textconv-cache notes contain whatever the textconv filter produces,\nso they are a likely way of getting non-standard characters. In\npractice, though, you will probably not see NULL, because the point was\nto generate a _text_ version.\n\n-Peff\n"}]}