{"thread":{"id":"23752","subject":"[PATCH v2 0/8] filling out the notes man page","startedAt":"2010-05-09T03:13:57Z","lastAt":"2010-05-12T12:57:06Z","messageCount":21,"participants":["Jonathan Nieder","Jeff King","Johan Herland","Thomas Rast"],"isPatch":true,"patchVersion":2,"patchTotal":8},"messages":[{"id":"141279","messageId":"20100509031357.GA7926@progeny.tock","threadId":"23752","inReplyTo":null,"subject":"[PATCH v2 0/8] filling out the notes man page","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-09T03:13:57Z","receivedAt":"2010-05-09T03:13:57Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Hi,\n\nMany thanks for the feedback from last round[1]. I tried to take your\ncomments to heart and carry them out as well as I could. I hope you\nlike the result. Doubtless some of the new text I added is unclear,\nso as usual, your comments are welcome.\n\nThe first two patches sum up the low-level basics that a reader should\nknow. For the format of trees, I renamed the NOTES section to\nDISCUSSION and added a paragraph or two (and a footnote, triggering a\nbug in docbook-xsl; more on that later); for the format of notes\nblobs, I added an example to illustrate Johan’s trick for arbitrary\nbinary notes. Thanks for the tip.\n\nThe next five patches aim to make the treatment of configuration a\nlittle more systematic. git-notes.1 gains Configuration and\nEnvironment sections and git-log.1 gains a Configuration section (but\nnot Environment, because I am lazy).\n\nOf course, there is a lot still to document. It is not obvious to me\nyet what relationship notes will have to other commands, such as\nformat-patch.\n\nThanks,\nJonathan Nieder (8):\n Documentation/notes: document format of notes trees\n Documentation/notes: describe content of notes blobs\n Documentation/notes: add configuration section\n Documentation/notes: simplify treatment of default notes ref\n Documentation/log: add a CONFIGURATION section\n Documentation/notes: simplify treatment of default display refs\n Documentation/notes: clean up description of rewriting configuration\n Documentation/notes: nitpicks\n\n Documentation/config.txt | 16 +---\n Documentation/git-log.txt | 42 ++++++++++\n Documentation/git-notes.txt | 177 +++++++++++++++++++++++++++++++++++++------\n t/t3307-notes-man.sh | 38 +++++++++\n 4 files changed, 238 insertions(+), 35 deletions(-)\n create mode 100755 t/t3307-notes-man.sh\n\n[1] http://thread.gmane.org/gmane.comp.version-control.git/146269\n"},{"id":"141280","messageId":"20100509031935.GA7958@progeny.tock","threadId":"23752","inReplyTo":"20100509031357.GA7926@progeny.tock","subject":"[PATCH 1/8] Documentation/notes: document format of notes trees","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-09T03:19:35Z","receivedAt":"2010-05-09T03:19:35Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Separate the specification of the notes format exposed in\ngit-config.1 from the description of the option; or in other\nwords, move the explanation for what to expect to find at\nrefs/notes/commits from git-config.1 to git-notes.1.\n\nSuggested-by: Thomas Rast \nSigned-off-by: Jonathan Nieder \n---\nHow well does ‘git notes’ handle notes trees without a commit\ncurrently? I remembered some rumor about a commitless mode in which\nthe only history is the reflog, but I am not sure how much of that is\nimplemented yet and I did not check.\n\nIf it was only groundless rumor (read: I made it up), then the last\nparagraph of the discussion should be removed.\n\n Documentation/config.txt | 16 +++++-----------\n Documentation/git-notes.txt | 30 +++++++++++++++++++++---------\n 2 files changed, 26 insertions(+), 20 deletions(-)\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 8f86050..cc4bc20 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -518,18 +518,12 @@ check that makes sure that existing object files will not get overwritten.\n \n core.notesRef::\n \tWhen showing commit messages, also show notes which are stored in\n-\tthe given ref. This ref is expected to contain files named\n-\tafter the full SHA-1 of the commit they annotate. The ref\n-\tmust be fully qualified.\n+\tthe given ref. The ref must be fully qualified. If the given\n+\tref does not exist, it is not an error but means that no\n+\tnotes should be printed.\n +\n-If such a file exists in the given ref, the referenced blob is read, and\n-appended to the commit message, separated by a \"Notes ():\"\n-line (shortened to \"Notes:\" in the case of \"refs/notes/commits\"). If the\n-given ref itself does not exist, it is not an error, but means that no\n-notes should be printed.\n-+\n-This setting defaults to \"refs/notes/commits\", and can be overridden by\n-the `GIT_NOTES_REF` environment variable.\n+This setting defaults to \"refs/notes/commits\", and it can be overridden by\n+the 'GIT_NOTES_REF' environment variable. See linkgit:git-notes[1].\n \n core.sparseCheckout::\n \tEnable \"sparse checkout\" feature. See section \"Sparse checkout\" in\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 4e5113b..af12c3c 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -28,7 +28,7 @@ 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 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 `refs/notes/commits`).\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@@ -122,17 +122,29 @@ OPTIONS\n \tis taken to be in `refs/notes/` if it is not qualified.\n \n \n-NOTES\n------\n+DISCUSSION\n+----------\n+\n+Commit notes are blobs containing extra information about an object\n+(usually information to supplement a commit's message). These blobs\n+are taken from notes refs. A notes ref is usually a branch which\n+contains \"files\" whose paths are the object names for the objects\n+they describe, with some directory separators included for performance\n+reasons footnote:[Permitted pathnames have the form\n+'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory\n+names of two hexadecimal digits each followed by a filename with the\n+rest of the object ID.].\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`.\n-\n-Currently the commit message only records which operation triggered\n-the update, and the commit authorship is determined according to the\n-usual rules (see linkgit:git-commit[1]). These details may change in\n-the future.\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+\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+`git log -p -g `.\n \n \n Author\n-- \n1.7.1\n"},{"id":"141281","messageId":"20100509032134.GB7958@progeny.tock","threadId":"23752","inReplyTo":"20100509031357.GA7926@progeny.tock","subject":"[PATCH 2/8] Documentation/notes: describe content of notes blobs","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-09T03:21:34Z","receivedAt":"2010-05-09T03:21:34Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"stripspace/text-based formatting kicks in when specifying the notes\ncontent with -m or -F, or when an editor is used to edit the notes.\nTo binary-safely create notes from files, the following construct is\nrequired:\n\n git notes add -C $(git hash-object -w ) \n\nExplain this trick (thanks, Johan!) in the manual. Add an ordinary\nexample, too, to keep this esoteric one company.\n\nCc: Johan Herland \nCc: Thomas Rast \nCc: Jeff King \nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-notes.txt | 38 +++++++++++++++++++++++++++++++++++++-\n t/t3307-notes-man.sh | 38 ++++++++++++++++++++++++++++++++++++++\n 2 files changed, 75 insertions(+), 1 deletions(-)\n create mode 100755 t/t3307-notes-man.sh\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex af12c3c..97b9d81 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -101,15 +101,20 @@ OPTIONS\n \tUse the given note message (instead of prompting).\n \tIf multiple `-m` options are given, their values\n \tare concatenated as separate paragraphs.\n+\tLines starting with `#` and empty lines other than a\n+\tsingle line between paragraphs will be stripped out.\n \n -F ::\n --file=::\n \tTake the note message from the given file. Use '-' to\n \tread the note message from the standard input.\n+\tLines starting with `#` and empty lines other than a\n+\tsingle line between paragraphs will be stripped out.\n \n -C ::\n --reuse-message=::\n-\tReuse the note message from the given note object.\n+\tTake the note message from the given blob object (for\n+\texample, another note).\n \n -c ::\n --reedit-message=::\n@@ -147,6 +152,37 @@ object, in which case the history of the notes can be read with\n `git log -p -g `.\n \n \n+EXAMPLES\n+--------\n+\n+You can use notes to add annotations with information that was not\n+available at the time a commit was written.\n+\n+------------\n+$ git notes add -m 'Tested-by: Johannes Sixt ' 72a144e2\n+$ git show -s 72a144e\n+[...]\n+ Signed-off-by: Junio C Hamano \n+\n+Notes:\n+ Tested-by: Johannes Sixt \n+------------\n+\n+In principle, a note is a regular Git blob, and any kind of\n+(non-)format is accepted. You can binary-safely create notes from\n+arbitrary files using 'git hash-object':\n+\n+------------\n+$ cc *.c\n+$ blob=$(git hash-object -w a.out)\n+$ git notes --ref=built add -C \"$blob\" HEAD\n+------------\n+\n+Of course, it doesn't make much sense to display non-text-format notes\n+with 'git log', so if you use such notes, you'll probably need to write\n+some special-purpose tools to do something useful with them.\n+\n+\n Author\n ------\n Written by Johannes Schindelin and\ndiff --git a/t/t3307-notes-man.sh b/t/t3307-notes-man.sh\nnew file mode 100755\nindex 0000000..3269f2e\n--- /dev/null\n+++ b/t/t3307-notes-man.sh\n@@ -0,0 +1,38 @@\n+#!/bin/sh\n+\n+test_description='Examples from the git-notes man page\n+\n+Make sure the manual is not full of lies.'\n+\n+. ./test-lib.sh\n+\n+test_expect_success 'setup' '\n+\ttest_commit A &&\n+\ttest_commit B &&\n+\ttest_commit C\n+'\n+\n+test_expect_success 'example 1: notes to add an Acked-by line' '\n+\tcat <<-\\EOF >expect &&\n+\t B\n+\n+\tNotes:\n+\t Acked-by: A C Ker \n+\tEOF\n+\tgit notes add -m \"Acked-by: A C Ker \" B &&\n+\tgit show -s B^{commit} >log &&\n+\ttail -n 4 log >actual &&\n+\ttest_cmp expect actual\n+'\n+\n+test_expect_success 'example 2: binary notes' '\n+\tcp \"$TEST_DIRECTORY\"/test4012.png .\n+\tgit checkout B &&\n+\tblob=$(git hash-object -w test4012.png) &&\n+\tgit notes --ref=logo add -C \"$blob\" &&\n+\tgit notes --ref=logo copy B C &&\n+\tgit notes --ref=logo show C >actual &&\n+\ttest_cmp test4012.png actual\n+'\n+\n+test_done\n-- \n1.7.1\n"},{"id":"141282","messageId":"20100509032159.GC7958@progeny.tock","threadId":"23752","inReplyTo":"20100509031357.GA7926@progeny.tock","subject":"[PATCH 3/8] Documentation/notes: add configuration section","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-09T03:21:59Z","receivedAt":"2010-05-09T03:21:59Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Copy the descriptions of configuration variables from git-config.1.\nOnce the descriptions have been ironed out, it would be nice to\nrefactor them to share text, but for now it is simplest to experiment\nwith separate copies.\n\nSigned-off-by: Jonathan Nieder \n---\nThis is straight copy and paste.\n\n Documentation/git-notes.txt | 59 +++++++++++++++++++++++++++++++++++++++++++\n 1 files changed, 59 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 97b9d81..f561457 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -183,6 +183,65 @@ with 'git log', so if you use such notes, you'll probably need to write\n some special-purpose tools to do something useful with them.\n \n \n+CONFIGURATION\n+-------------\n+\n+core.notesRef::\n+\tWhen showing commit messages, also show notes which are stored in\n+\tthe given ref. The ref must be fully qualified. If the given\n+\tref does not exist, it is not an error but means that no\n+\tnotes should be printed.\n++\n+This setting defaults to \"refs/notes/commits\", and it can be overridden by\n+the 'GIT_NOTES_REF' environment variable. See linkgit:git-notes[1].\n+\n+notes.displayRef::\n+\tThe (fully qualified) refname from which to show notes when\n+\tshowing commit messages. The value of this variable can be set\n+\tto a glob, in which case notes from all matching refs will be\n+\tshown. You may also specify this configuration variable\n+\tseveral times. A warning will be issued for refs that do not\n+\texist, but a glob that does not match any refs is silently\n+\tignored.\n++\n+This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`\n+environment variable, which must be a colon separated list of refs or\n+globs.\n++\n+The effective value of \"core.notesRef\" (possibly overridden by\n+GIT_NOTES_REF) is also implicitly added to the list of refs to be\n+displayed.\n+\n+notes.rewrite.::\n+\tWhen rewriting commits with (currently `amend` or\n+\t`rebase`) and this variable is set to `true`, git\n+\tautomatically copies your notes from the original to the\n+\trewritten commit. Defaults to `true`, but see\n+\t\"notes.rewriteRef\" below.\n+\n+notes.rewriteMode::\n+\tWhen copying notes during a rewrite (see the\n+\t\"notes.rewrite.\" option), determines what to do if\n+\tthe target commit already has a note. Must be one of\n+\t`overwrite`, `concatenate`, or `ignore`. Defaults to\n+\t`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. The ref may be a\n+\tglob, in which case notes in all matching refs will be copied.\n+\tYou may also specify this configuration several times.\n++\n+Does not have a default value; you must configure this variable to\n+enable note rewriting.\n++\n+This setting can be overridden with the `GIT_NOTES_REWRITE_REF`\n+environment variable, which must be a colon separated list of refs or\n+globs.\n+\n Author\n ------\n Written by Johannes Schindelin and\n-- \n1.7.1\n"},{"id":"141283","messageId":"20100509032358.GD7958@progeny.tock","threadId":"23752","inReplyTo":"20100509031357.GA7926@progeny.tock","subject":"[PATCH 4/8] Documentation/notes: simplify treatment of default notes ref","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-09T03:23:58Z","receivedAt":"2010-05-09T03:23:58Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Separate the documentation of the semantics, command-line option,\nconfiguration item, and environment variable for the default notes\nref. The documentation is easier to digest in bite-sized pieces.\n\nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-notes.txt | 31 ++++++++++++++++++++-----------\n 1 files changed, 20 insertions(+), 11 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex f561457..28ac862 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -23,6 +23,11 @@ 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 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 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,8 +35,6 @@ 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-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@@ -122,8 +125,8 @@ OPTIONS\n \tthe user can further edit the note message.\n \n --ref ::\n-\tManipulate the notes tree in . This overrides both\n-\tGIT_NOTES_REF and the \"core.notesRef\" configuration. The ref\n+\tManipulate the notes tree in . This overrides\n+\t'GIT_NOTES_REF' and the \"core.notesRef\" configuration. The ref\n \tis taken to be in `refs/notes/` if it is not qualified.\n \n \n@@ -187,13 +190,10 @@ CONFIGURATION\n -------------\n \n core.notesRef::\n-\tWhen showing commit messages, also show notes which are stored in\n-\tthe given ref. The ref must be fully qualified. If the given\n-\tref does not exist, it is not an error but means that no\n-\tnotes should be printed.\n-+\n-This setting defaults to \"refs/notes/commits\", and it can be overridden by\n-the 'GIT_NOTES_REF' environment variable. See linkgit:git-notes[1].\n+\tNotes ref to read and manipulate instead of\n+\t`refs/notes/commits`. Must be an unabbreviated ref name.\n+\tThis setting can be overridden through the environment and\n+\tcommand line.\n \n notes.displayRef::\n \tThe (fully qualified) refname from which to show notes when\n@@ -242,6 +242,15 @@ This setting can be overridden with the `GIT_NOTES_REWRITE_REF`\n environment variable, which must be a colon separated list of refs or\n globs.\n \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+\n Author\n ------\n Written by Johannes Schindelin and\n-- \n1.7.1\n"},{"id":"141284","messageId":"20100509033040.GE7958@progeny.tock","threadId":"23752","inReplyTo":"20100509031357.GA7926@progeny.tock","subject":"[PATCH 5/8] Documentation/log: add a CONFIGURATION section","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-09T03:30:41Z","receivedAt":"2010-05-09T03:30:41Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Add a configuration section summarizing variables that affect the\nlog family of commands.\n\nCc: Thomas Rast \nCc: Jakub Narebski \nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-log.txt | 42 ++++++++++++++++++++++++++++++++++++++++++\n 1 files changed, 42 insertions(+), 0 deletions(-)\n\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex fb184ba..d7f6a9c 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -132,6 +132,48 @@ Discussion\n \n include::i18n.txt[]\n \n+Configuration\n+-------------\n+\n+See linkgit:git-config[1] for core variables and linkgit:git-diff[1]\n+for settings related to diff generation.\n+\n+format.pretty::\n+\tDefault for the `--format` option. (See \"PRETTY FORMATS\" above.)\n+\tDefaults to \"medium\".\n+\n+i18n.logOutputEncoding::\n+\tEncoding to use when displaying logs. (See \"Discussion\", above.)\n+\tDefaults to the value of `i18n.commitEncoding` if set, UTF-8\n+\totherwise.\n+\n+log.date::\n+\tDefault format for human-readable dates. (Compare the\n+\t`--date` option.) Defaults to \"default\", which means to write\n+\tdates like `Sat May 8 19:35:34 2010 -0500`.\n+\n+log.showroot::\n+\tIf `false`, 'git log' and related commands will not treat the\n+\tinitial commit as a big creation event. Any root commits in\n+\t`git log -p` output would be shown without a diff attached.\n+\tThe default is `true`.\n+\n+mailmap.file::\n+\tSee linkgit:git-shortlog[1].\n+\n+notes.displayRef::\n+\tWhich refs, in addition to the default set by `core.notesRef`\n+\tor 'GIT_NOTES_REF', to read notes from when showing commit\n+\tmessages with the 'log' family of commands. See\n+\tlinkgit:git-notes[1].\n++\n+May be an unabbreviated ref name or a glob and may be specified\n+multiple times. A warning will be issued for refs that do not exist,\n+but a glob that does not match any refs is silently ignored.\n++\n+This setting can be disabled by the `--no-standard-notes` option,\n+overridden by the 'GIT_NOTES_DISPLAY_REF' environment variable,\n+and supplemented by the `--show-notes` option.\n \n Author\n ------\n-- \n1.7.1\n"},{"id":"141285","messageId":"20100509033223.GF7958@progeny.tock","threadId":"23752","inReplyTo":"20100509031357.GA7926@progeny.tock","subject":"[PATCH 6/8] Documentation/notes: simplify treatment of default display refs","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-09T03:32:24Z","receivedAt":"2010-05-09T03:32:24Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"The main description of display refs for notes should be in\ngit-log.1, where there is a chance to give a leisurely description\nof all the ways they can be set, what they are used for, and so\non. The description in git-notes.1 is only meant to be a quick\nreminder of how notes are used.\n\nSo simplify it.\n\nAlso add an entry for GIT_NOTES_DISPLAY_REF to the environment\nsection.\n\nCc: Thomas Rast \nCc: Johan Herland \nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-notes.txt | 36 +++++++++++++++++++-----------------\n 1 files changed, 19 insertions(+), 17 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 28ac862..7856b28 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -35,8 +35,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 `refs/notes/commits`).\n \n-To change which notes are shown by 'git-log', see the\n-\"notes.displayRef\" configuration.\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 description of \"notes.rewrite.\" in\n linkgit:git-config[1] for a way of carrying your notes across commands\n@@ -196,21 +196,13 @@ core.notesRef::\n \tcommand line.\n \n notes.displayRef::\n-\tThe (fully qualified) refname from which to show notes when\n-\tshowing commit messages. The value of this variable can be set\n-\tto a glob, in which case notes from all matching refs will be\n-\tshown. You may also specify this configuration variable\n-\tseveral times. A warning will be issued for refs that do not\n-\texist, but a glob that does not match any refs is silently\n-\tignored.\n-+\n-This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`\n-environment variable, which must be a colon separated list of refs or\n-globs.\n-+\n-The effective value of \"core.notesRef\" (possibly overridden by\n-GIT_NOTES_REF) is also implicitly added to the list of refs to be\n-displayed.\n+\tWhich ref (or refs, if a glob or specified more than once), in\n+\taddition to the default set by `core.notesRef` or\n+\t'GIT_NOTES_REF', to read notes from when showing commit\n+\tmessages with the 'git log' family of commands.\n+\tThis setting can be overridden on the command line or by the\n+\t'GIT_NOTES_DISPLAY_REF' environment variable.\n+\tSee linkgit:git-log[1].\n \n notes.rewrite.::\n \tWhen rewriting commits with (currently `amend` or\n@@ -250,6 +242,16 @@ ENVIRONMENT\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+\tColon-delimited list of refs or globs indicating which refs,\n+\tin addition to the default from `core.notesRef` or\n+\t'GIT_NOTES_REF', to read notes from when showing commit\n+\tmessages.\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 \n Author\n ------\n-- \n1.7.1\n"},{"id":"141286","messageId":"20100509033327.GG7958@progeny.tock","threadId":"23752","inReplyTo":"20100509031357.GA7926@progeny.tock","subject":"[PATCH 7/8] Documentation/notes: clean up description of rewriting configuration","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-09T03:33:28Z","receivedAt":"2010-05-09T03:33:28Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Clarify that the GIT_NOTES_REWRITE_REFS environment variable\noverrides both ‘[notes \"rewrite\"] ’ and ‘[notes] rewriteRef’.\n\nAdd explanations of GIT_NOTES_REWRITE_MODE and GIT_NOTES_REWRITE_REFS\nto the ENVIRONMENT section.\n\nCc: Leif Arne Storset \nSigned-off-by: Jonathan Nieder \n---\n Documentation/git-notes.txt | 47 ++++++++++++++++++++++++++----------------\n 1 files changed, 29 insertions(+), 18 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 7856b28..d868535 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -38,9 +38,8 @@ message, after an unindented line saying \"Notes ():\" (or\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 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 to carry\n+notes across commands that rewrite commits.\n \n \n SUBCOMMANDS\n@@ -206,33 +205,31 @@ notes.displayRef::\n \n notes.rewrite.::\n \tWhen rewriting commits with (currently `amend` or\n-\t`rebase`) and this variable is set to `true`, git\n-\tautomatically copies your notes from the original to the\n-\trewritten commit. Defaults to `true`, but see\n-\t\"notes.rewriteRef\" below.\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 (see the\n-\t\"notes.rewrite.\" option), determines what to do if\n-\tthe target commit already has a note. Must be one of\n-\t`overwrite`, `concatenate`, or `ignore`. Defaults to\n-\t`concatenate`.\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`, and `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. The ref may be a\n-\tglob, in which case notes in all matching refs will be copied.\n-\tYou may also specify this configuration several times.\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; you must configure this variable to\n enable note rewriting.\n +\n-This setting can be overridden with the `GIT_NOTES_REWRITE_REF`\n-environment variable, which must be a colon separated list of refs or\n-globs.\n+Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable.\n \n \n ENVIRONMENT\n@@ -252,6 +249,20 @@ ENVIRONMENT\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`, and `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 depends\n+on the `notes.rewrite.` and `notes.rewriteRef` settings.\n+\n \n Author\n ------\n-- \n1.7.1\n"},{"id":"141287","messageId":"20100509033721.GH7958@progeny.tock","threadId":"23752","inReplyTo":"20100509031357.GA7926@progeny.tock","subject":"[PATCH 8/8] Documentation/notes: nitpicks","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-09T03:37:21Z","receivedAt":"2010-05-09T03:37:21Z","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---\nAs before, except the “default setting” nitpick moved to an earlier\npatch.\n\nThat’s the end of the series. Thanks for your help.\n\nGood night,\nJonathan\n\n Documentation/git-notes.txt | 12 ++++++------\n 1 files changed, 6 insertions(+), 6 deletions(-)\n\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex d868535..de63ef0 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,17 +20,17 @@ 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 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 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 `refs/notes/commits`).\n-- \n1.7.1\n"},{"id":"141291","messageId":"20100509065220.GA23717@sigill.intra.peff.net","threadId":"23752","inReplyTo":"20100509031935.GA7958@progeny.tock","subject":"Re: [PATCH 1/8] Documentation/notes: document format of notes trees","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-05-09T06:52:20Z","receivedAt":"2010-05-09T06:52:20Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, May 08, 2010 at 10:19:35PM -0500, Jonathan Nieder wrote:\n\n> How well does ‘git notes’ handle notes trees without a commit\n> currently? I remembered some rumor about a commitless mode in which\n> the only history is the reflog, but I am not sure how much of that is\n> implemented yet and I did not check.\n> \n> If it was only groundless rumor (read: I made it up), then the last\n> paragraph of the discussion should be removed.\n\nMy original textconv caching implementation used commitless notes. The\nnew version uses commits, but keeps the history truncated. As far as I\nknow, you can manipulate the latter with git-notes, but I haven't tried\nmuch (adding a new note should make a history graph with length 2, which\nwill then get re-truncated the next time we add something to the cache\nautomatically). But certainly \"list\", \"show\", and \"prune\" should work,\nwhich are the ones I would expect to be useful for such a cache.\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> +`git log -p -g `.\n\nYou would also use this to see the history of cache notes. They have\ncommits, but the only ancestry is in the reflog. So perhaps:\n\n Some notes refs may be \"history-less\", either because they point\n directly to a tree instead of a commit, or because their commits are\n truncated (the notes generated by textconv caching are an example of\n the latter). To see the local history of these refs, view the reflog\n with `git log -g `.\n\n-Peff\n"},{"id":"141292","messageId":"20100509065709.GB23717@sigill.intra.peff.net","threadId":"23752","inReplyTo":"20100509033040.GE7958@progeny.tock","subject":"Re: [PATCH 5/8] Documentation/log: add a CONFIGURATION section","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-05-09T06:57:10Z","receivedAt":"2010-05-09T06:57:10Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, May 08, 2010 at 10:30:41PM -0500, Jonathan Nieder wrote:\n\n> Add a configuration section summarizing variables that affect the\n> log family of commands.\n\nI think this is an improvement, but given this patch and the earlier\ncut-and-paste of notes config into git-notes.txt, what do you think of\nmy proposal here:\n\n http://article.gmane.org/gmane.comp.version-control.git/145139\n [skip down to /You didn't mention configuration variables/]\n\nI haven't actually started work on it yet, but it would simplify what\nyou're doing here.\n\n-Peff\n"},{"id":"141293","messageId":"20100509070022.GC23717@sigill.intra.peff.net","threadId":"23752","inReplyTo":"20100509033223.GF7958@progeny.tock","subject":"Re: [PATCH 6/8] Documentation/notes: simplify treatment of default display refs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-05-09T07:00:22Z","receivedAt":"2010-05-09T07:00:22Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sat, May 08, 2010 at 10:32:24PM -0500, Jonathan Nieder wrote:\n\n> @@ -196,21 +196,13 @@ core.notesRef::\n> \tcommand line.\n> \n> notes.displayRef::\n> -\tThe (fully qualified) refname from which to show notes when\n> -\tshowing commit messages. The value of this variable can be set\n> -\tto a glob, in which case notes from all matching refs will be\n> -\tshown. You may also specify this configuration variable\n> -\tseveral times. A warning will be issued for refs that do not\n> -\texist, but a glob that does not match any refs is silently\n> -\tignored.\n> -+\n> -This setting can be overridden with the `GIT_NOTES_DISPLAY_REF`\n> -environment variable, which must be a colon separated list of refs or\n> -globs.\n> -+\n> -The effective value of \"core.notesRef\" (possibly overridden by\n> -GIT_NOTES_REF) is also implicitly added to the list of refs to be\n> -displayed.\n> +\tWhich ref (or refs, if a glob or specified more than once), in\n> +\taddition to the default set by `core.notesRef` or\n> +\t'GIT_NOTES_REF', to read notes from when showing commit\n> +\tmessages with the 'git log' family of commands.\n> +\tThis setting can be overridden on the command line or by the\n> +\t'GIT_NOTES_DISPLAY_REF' environment variable.\n> +\tSee linkgit:git-log[1].\n\nHmm. Both this and 4/8 rewrite bits of the configuration copied from\nconfig.txt in an earlier patch. Do any changes need to be propagated\nback to config.txt (and no, I didn't read and think carefully, so the\nanswer may be \"no, they are now diverging intentionally\")?\n\n-Peff\n"},{"id":"141302","messageId":"20100509084325.GA9801@progeny.tock","threadId":"23752","inReplyTo":"20100509070022.GC23717@sigill.intra.peff.net","subject":"Re: [PATCH 6/8] Documentation/notes: simplify treatment of default display refs","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-09T08:43:25Z","receivedAt":"2010-05-09T08:43:25Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Jeff King wrote:\n\n> Hmm. Both this and 4/8 rewrite bits of the configuration copied from\n> config.txt in an earlier patch. Do any changes need to be propagated\n> back to config.txt (and no, I didn't read and think carefully, so the\n> answer may be \"no, they are now diverging intentionally\")?\n\nThanks for bringing this up. I think some of the changes ultimately\nought to be propagated back to config.txt. I copied the text anyway\nbecause as long as the differences are in short-term memory, I find it\neasier to manipulate two similar files than one file with ifdefs in\nit; so it seemed like a reasonable strategy to let these diverge for a\nfew weeks and then merge them with ifdefs again.\n\nSome divergence is needed imho so that the text can say things like\n“see the Options section earlier in this page”.\n\nLonger term, I suspect I would like a gitconfig.5 page that functioned\nsomething like the main commands list, which could avoid some\nduplication. But this is something to be considered carefully: right\nnow it is very easy to start with knowing there is some configuration\nfor what you want to change (conflict hunk format, say) and find it by\nsearching the descriptions in git-config.1; if we split that file up,\nthat won’t be so easy.\n\n CONFIGURATION SECTIONS\n\n We separate the configuration into <...>.\n\n Core settings\n\n [core] (see \"Core configuration\", below)\n \n\n [user]\n Default identity to attribute new commits to.\n\n [url \"baseaddress\"] (see git-remote(1))\n Short names to use for a long, frequently-used URL.\n\n [alias] (see \"Aliases\")\n User-defined git commands that alias other git commands\n with options.\n\n [gc] (see git-gc(1))\n Automatic repository repacking settings.\n\n [http] (see git-remote-http(1))\n Tweaking HTTP transport behavior.\n\n [i18n] (see git-commit(1))\n Commit log encoding and display encoding.\n\n [notes]\n [notes \"rewrite\"] (see git-notes(1))\n Display and propagation of commit notes.\n\n [rerere] (see git-rerere(1))\n Whether to save successful merge resolutions for later\n reuse.\n\n Output format\n\n [advice] (see \"Advice Options\")\n Whether to display optional help messages that may\n dwarf regular output.\n\n [color] (see \"Colored output\")\n Which commands should use colored output.\n\n [color \"gitcommand\"] (see \"Colored output\")\n What colors to use for a particular sort of output. The\n relevant command name is generally the most prominent git\n command which produces that output.\n\n [format] (see git-log(1))\n\t How to display commit metadata by default. This section is\n shared with git-format-patch(1) configuration.\n\n [pager] (see \"Paginated output\")\n Which commands should paginate their output.\n\n Repository setup\n\n [branch \"branchname\"] (see git-branch(1))\n Where `git pull` should pull from for each local branch.\n\n [remote \"reponame\"] (see git-remote(1))\n URL and branches for a named remote repository.\n\n [remotes] (see git-remote(1))\n User-defined collections of remote repositories that are\n often fetched from or pushed to together.\n\n Helper programs\n\n [web] (see git-help(1))\n Web browser to use for 'git help --web' and 'git instaweb'.\n\n [merge \"mergedriver\"] (see gitattributes(5))\n Low-level format-specific helper for merging files.\n\n [browser \"webbrowser\"] (see git-web-browse(1))\n How to invoke a given web browser.\n\n [man \"manpager\"] (see git-help(1))\n How to invoke a given man pager.\n\n [difftool \"diffvisualizer\"] (see git-difftool(1))\n How to invoke a given diff frontend.\n\n [mergetool \"mergeresolver\"] (see git-mergetool(1))\n How to invoke a given interactive 3-way merge helper.\n\n [guitool \"guihelper\"] (see git-gui(1))\n How git gui should invoke this helper when selected from\n the \"Tools\" menu.\n\n Default behavior of commands\n\n [add]\t\tgit-add(1)\n [am]\t\tgit-am(1)\n [apply]\t\tgit-apply(1)\n [branch]\t\tgit-branch(1)\n [clean]\t\tgit-clean(1)\n [commit]\t\tgit-commit(1)\n [diff]\t\tgit-diff(1)\n [difftool]\tgit-difftool(1)\n [fetch]\t\tgit-fetch-pack(1), git-fetch(1), git-pull(1)\n [format]\t\tgit-format-patch(1), git-log(1)\n [gc]\t\tgit-gc(1)\n [gitcvs]\t\tgit-cvsserver(1)\n [gui]\t\tgit-gui(1)\n [help]\t\tgit-help(1), git --help\n [imap]\t\tgit-imap-send(1)\n [init]\t\tgit-init(1)\n [instaweb]\tgit-instaweb(1)\n [interactive]\tgit-add--interactive(1), git add -i\n [log]\t\tgit-log(1), git-show(1), git-whatchanged(1)\n [mailmap]\t\tgit-shortlog(1)\n [man]\t\tgit-help(1)\n [merge]\t\tgit-merge(1), git-mergetool(1)\n [mergetool]\tgit-mergetool(1)\n [notes]\t\tgit-notes(1)\n [pack]\t\tgit-gc(1), git-repack(1)\n [pull]\t\tgit-pull(1)\n [push]\t\tgit-push(1)\n [receive]\t\tgit-receive-pack(1)\n [repack]\t\tgit-repack(1)\n [sendemail]\tgit-send-email(1)\n [sendemail \"profile\"]\n\t\t\tgit-send-email(1)\n [showbranch]\tgit-show-branch(1)\n [status]\t\tgit-status(1)\n [tar]\t\tgit-archive(1)\n [transfer]\tgit-fetch-pack(1), git-receive-pack(1)\n"},{"id":"141347","messageId":"20100510060630.GC13340@coredump.intra.peff.net","threadId":"23752","inReplyTo":"20100509084325.GA9801@progeny.tock","subject":"Re: [PATCH 6/8] Documentation/notes: simplify treatment of default display refs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-05-10T06:06:30Z","receivedAt":"2010-05-10T06:06:30Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Sun, May 09, 2010 at 03:43:25AM -0500, Jonathan Nieder wrote:\n\n> Thanks for bringing this up. I think some of the changes ultimately\n> ought to be propagated back to config.txt. I copied the text anyway\n> because as long as the differences are in short-term memory, I find it\n> easier to manipulate two similar files than one file with ifdefs in\n> it; so it seemed like a reasonable strategy to let these diverge for a\n> few weeks and then merge them with ifdefs again.\n\nHrm. If that merge actually happens while things are still in short-term\nmemory. ;)\n\n> Some divergence is needed imho so that the text can say things like\n> “see the Options section earlier in this page”.\n\nYeah, understandable. And I also don't want to get into a rat's nest of\nifdefs in the documentation. Which is why I was pushing to move straight\ninto something more elegant. :)\n\n> Longer term, I suspect I would like a gitconfig.5 page that functioned\n> something like the main commands list, which could avoid some\n> duplication. But this is something to be considered carefully: right\n> now it is very easy to start with knowing there is some configuration\n> for what you want to change (conflict hunk format, say) and find it by\n> searching the descriptions in git-config.1; if we split that file up,\n> that won’t be so easy.\n\nYeah, I do worry about people being able to search effectively. But to\nsome degree, sensible naming of the options helps with that. Searching\nfor \"conflict\" even in just a list of options should come up with\n\"merge.conflictstyle\", and I had always intended for such a gitconfig.5\nto have a full list.\n\n> CONFIGURATION SECTIONS\n> [...]\n\nYour breakdown looks like a sensible thing to have at the start of\ngitconfig.5. It looks like you were planning on putting some generic\nconcepts like \"alias\" and \"core\" into that page (at the end of the\noverview list), and then referring to individual command pages for their\nrespective sections. That sounds reasonable to me.\n\n-Peff\n"},{"id":"141446","messageId":"201005110127.43916.johan@herland.net","threadId":"23752","inReplyTo":"20100509031357.GA7926@progeny.tock","subject":"Re: [PATCH v2 0/8] filling out the notes man page","fromName":"Johan Herland","fromEmail":"johan@herland.net","sentAt":"2010-05-10T23:27:43Z","receivedAt":"2010-05-10T23:27:43Z","isPatch":true,"sender":{"key":"johan@herland.net","avatar":"https://avatars.githubusercontent.com/u/547031?v=4"},"body":"On Sunday 09 May 2010, Jonathan Nieder wrote:\n> Many thanks for the feedback from last round[1]. I tried to take your\n> comments to heart and carry them out as well as I could. I hope you\n> like the result. Doubtless some of the new text I added is unclear,\n> so as usual, your comments are welcome.\n\nThank you very much for this effort. All patches (modulo the things you're \nworking out with Peff) are\n\nAcked-By: Johan Herland \n\n\nThanks!\n\n...Johan\n\n-- \nJohan Herland, \nwww.herland.net\n"},{"id":"141509","messageId":"201005120946.31193.trast@student.ethz.ch","threadId":"23752","inReplyTo":"20100509032358.GD7958@progeny.tock","subject":"Re: [PATCH 4/8] Documentation/notes: simplify treatment of default notes ref","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-05-12T07:46:30Z","receivedAt":"2010-05-12T07:46:30Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Jonathan Nieder wrote:\n> @@ -187,13 +190,10 @@ CONFIGURATION\n> -------------\n> \n> core.notesRef::\n> -\tWhen showing commit messages, also show notes which are stored in\n> -\tthe given ref. The ref must be fully qualified. If the given\n> -\tref does not exist, it is not an error but means that no\n> -\tnotes should be printed.\n> -+\n> -This setting defaults to \"refs/notes/commits\", and it can be overridden by\n> -the 'GIT_NOTES_REF' environment variable. See linkgit:git-notes[1].\n> +\tNotes ref to read and manipulate instead of\n> +\t`refs/notes/commits`. Must be an unabbreviated ref name.\n> +\tThis setting can be overridden through the environment and\n> +\tcommand line.\n\nIn the end result, this makes core.notesRef the only configuration\nvariable which does not have its environment sibling named explicitly\nin the config section. Would you mind putting GIT_NOTES_REF back in\nthe sentence for consistency with the other variables?\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"141510","messageId":"201005120948.19514.trast@student.ethz.ch","threadId":"23752","inReplyTo":"201005110127.43916.johan@herland.net","subject":"Re: [PATCH v2 0/8] filling out the notes man page","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2010-05-12T07:48:19Z","receivedAt":"2010-05-12T07:48:19Z","isPatch":true,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"Johan Herland wrote:\n> On Sunday 09 May 2010, Jonathan Nieder wrote:\n> > Many thanks for the feedback from last round[1]. I tried to take your\n> > comments to heart and carry them out as well as I could. I hope you\n> > like the result. Doubtless some of the new text I added is unclear,\n> > so as usual, your comments are welcome.\n> \n> Thank you very much for this effort. All patches (modulo the things you're \n> working out with Peff) are\n> \n> Acked-By: Johan Herland \n\nA big \"thanks\" from me, too. I admit I read the end result instead of\nthe series to save myself some confusion. It's a big improvement over\nthe current docs.\n\nAcked-by: Thomas Rast \n\n(I think some config variable unification is a good goal, but I\nwouldn't let that hold back this series.)\n\n-- \nThomas Rast\ntrast@{inf,student}.ethz.ch\n"},{"id":"141521","messageId":"20100512102841.GA17740@progeny.tock","threadId":"23752","inReplyTo":"201005120946.31193.trast@student.ethz.ch","subject":"Re: [PATCH 4/8] Documentation/notes: simplify treatment of default notes ref","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-12T10:28:41Z","receivedAt":"2010-05-12T10:28:41Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Thomas Rast wrote:\n\n> this makes core.notesRef the only configuration\n> variable which does not have its environment sibling named explicitly\n> in the config section. Would you mind putting GIT_NOTES_REF back in\n> the sentence for consistency with the other variables?\n\nNo problem. You mentioned something similar before; sorry about\nmissing it.\n\nThanks,\nJonathan\n"},{"id":"141522","messageId":"20100512105002.GB17740@progeny.tock","threadId":"23752","inReplyTo":"20100510060630.GC13340@coredump.intra.peff.net","subject":"Re: [PATCH 6/8] Documentation/notes: simplify treatment of default display refs","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-12T10:50:02Z","receivedAt":"2010-05-12T10:50:02Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Jeff King wrote:\n\n> Searching\n> for \"conflict\" even in just a list of options should come up with\n> \"merge.conflictstyle\", and I had always intended for such a gitconfig.5\n> to have a full list.\n\nMakes sense. So the breakdown of that page might be\n\n Synopsis\n Description\n Syntax\n Configuration items\n Sections\n Index\n Core configuration\n Identity\n Suppressing advice\n Command aliases\n Colored output\n Paginated output\n Examples\n See also\n\nwith the index listing all configuration items, with a short phrase\ndescribing each.\n\nTo keep this maintainable, I would like to have a single source file\nwith a short and long description for each configuration item. Then\na script would process it into an index and snippets for the relevant\ncommand pages.\n\nI’m anxious to get started. Thanks for the pointers.\nJonathan\n"},{"id":"141524","messageId":"20100512112342.GA23847@coredump.intra.peff.net","threadId":"23752","inReplyTo":"20100512105002.GB17740@progeny.tock","subject":"Re: [PATCH 6/8] Documentation/notes: simplify treatment of default display refs","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2010-05-12T11:23:43Z","receivedAt":"2010-05-12T11:23:43Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, May 12, 2010 at 05:50:02AM -0500, Jonathan Nieder wrote:\n\n> > Searching\n> > for \"conflict\" even in just a list of options should come up with\n> > \"merge.conflictstyle\", and I had always intended for such a gitconfig.5\n> > to have a full list.\n> \n> Makes sense. So the breakdown of that page might be\n> \n> Synopsis\n> Description\n> Syntax\n> Configuration items\n> Sections\n> Index\n> Core configuration\n> Identity\n> Suppressing advice\n> Command aliases\n> Colored output\n> Paginated output\n> Examples\n> See also\n\nYes, I think that is sane. One other option would be to put a few things\nlike \"identity\" into git(1) (where it would presumably be part of an\noverall identity section covering the concepts, config options, and\nenvironment variables).\n\n> To keep this maintainable, I would like to have a single source file\n> with a short and long description for each configuration item. Then\n> a script would process it into an index and snippets for the relevant\n> command pages.\n\nMy plan was to actually include the config's long description in the\nrelevant manpage (so it will be close to point of use, and you can see\nthe context while editing), and then pull the information out of each\npage for the index. Adding a short description would probably be\nsimplest as a specially formatted comment. E.g., in git-add.txt:\n\n add.ignore-errors::\n // @CONFIG: ignore errors on 'git-add'\n Continue adding files when some files cannot be added due to\n indexing errors. Equivalent to using '--ignore-errors'.\n\nand then process it with something like:\n\n perl -ne '\n m{^// @CONFIG: (.*)} && print \"$last - $1\\n\"; $last = $_\n ' git-*.txt >config-index.txt\n\nSo it's sort of literate programming for documentation. :) The comment\nthing is obviously a hack, but it should work well in practice. You\nmight be able to do some semantic markup with special attributes in\nasciidoc.\n\n> I’m anxious to get started. Thanks for the pointers.\n\nI'm happy you're working on this. Thanks.\n\n-Peff\n"},{"id":"141531","messageId":"20100512125706.GA5585@progeny.tock","threadId":"23752","inReplyTo":"201005120948.19514.trast@student.ethz.ch","subject":"[PATCH v3] Documentation/notes: fill out the man page a little","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-05-12T12:57:06Z","receivedAt":"2010-05-12T12:57:06Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Add some basic information to the ‘git notes’ page, mostly by moving\nover information from git-config.1. In particular, clarify that the\nGIT_NOTES_REWRITE_REFS environment variable overrides both\n‘[notes \"rewrite\"] ’ and ‘[notes] rewriteRef’.\n\nAlso add a Configuration section to git-log.1 for the ‘git notes’\npage to refer to.\n\nLater it would be nice to merge some changes back to git-config.1,\nbut one thing at a time.\n\nBased on advice from Johan, Thomas, and Jeff.\n\nAcked-by: Johan Herland \nAcked-by: Thomas Rast \nCc: Jeff King \nSigned-off-by: Jonathan Nieder \n---\nThis patch is meant to replace the jn/notes-doc branch in pu.\nInterdiff from last round:\n\n diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\n index de63ef0..1d8eef1 100644\n --- a/Documentation/git-notes.txt\n +++ b/Documentation/git-notes.txt\n @@ -149,9 +149,12 @@ 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 -`git log -p -g `.\n +Some notes refs may be \"history-less\", either because they point\n +directly to a tree instead of a commit, or because their commits are\n +truncated; the notes generated by textconv caching\n +(see linkgit:gitattributes[5]) are an example of the latter.\n +To see the local history of these refs, view the reflog with\n +`git log -g `.\n \n \n EXAMPLES\n @@ -191,8 +194,8 @@ CONFIGURATION\n core.notesRef::\n \tNotes ref to read and manipulate instead of\n \t`refs/notes/commits`. Must be an unabbreviated ref name.\n -\tThis setting can be overridden through the environment and\n -\tcommand line.\n +\tThis setting can be overridden by the 'GIT_NOTES_REF'\n +\tenvironment variable or the `--ref` option.\n \n notes.displayRef::\n \tWhich ref (or refs, if a glob or specified more than once), in\n\nThomas Rast wrote:\n\n> I admit I read the end result instead of\n> the series to save myself some confusion.\n\nThere’s a good reason to combine patches if I’ve ever heard one.\nThanks for noticing.\n\nJonathan\n\n Documentation/config.txt | 16 +---\n Documentation/git-log.txt | 42 ++++++++++\n Documentation/git-notes.txt | 180 +++++++++++++++++++++++++++++++++++++------\n t/t3307-notes-man.sh | 38 +++++++++\n 4 files changed, 241 insertions(+), 35 deletions(-)\n create mode 100755 t/t3307-notes-man.sh\n\ndiff --git a/Documentation/config.txt b/Documentation/config.txt\nindex 8f86050..cc4bc20 100644\n--- a/Documentation/config.txt\n+++ b/Documentation/config.txt\n@@ -518,18 +518,12 @@ check that makes sure that existing object files will not get overwritten.\n \n core.notesRef::\n \tWhen showing commit messages, also show notes which are stored in\n-\tthe given ref. This ref is expected to contain files named\n-\tafter the full SHA-1 of the commit they annotate. The ref\n-\tmust be fully qualified.\n+\tthe given ref. The ref must be fully qualified. If the given\n+\tref does not exist, it is not an error but means that no\n+\tnotes should be printed.\n +\n-If such a file exists in the given ref, the referenced blob is read, and\n-appended to the commit message, separated by a \"Notes ():\"\n-line (shortened to \"Notes:\" in the case of \"refs/notes/commits\"). If the\n-given ref itself does not exist, it is not an error, but means that no\n-notes should be printed.\n-+\n-This setting defaults to \"refs/notes/commits\", and can be overridden by\n-the `GIT_NOTES_REF` environment variable.\n+This setting defaults to \"refs/notes/commits\", and it can be overridden by\n+the 'GIT_NOTES_REF' environment variable. See linkgit:git-notes[1].\n \n core.sparseCheckout::\n \tEnable \"sparse checkout\" feature. See section \"Sparse checkout\" in\ndiff --git a/Documentation/git-log.txt b/Documentation/git-log.txt\nindex fb184ba..d7f6a9c 100644\n--- a/Documentation/git-log.txt\n+++ b/Documentation/git-log.txt\n@@ -132,6 +132,48 @@ Discussion\n \n include::i18n.txt[]\n \n+Configuration\n+-------------\n+\n+See linkgit:git-config[1] for core variables and linkgit:git-diff[1]\n+for settings related to diff generation.\n+\n+format.pretty::\n+\tDefault for the `--format` option. (See \"PRETTY FORMATS\" above.)\n+\tDefaults to \"medium\".\n+\n+i18n.logOutputEncoding::\n+\tEncoding to use when displaying logs. (See \"Discussion\", above.)\n+\tDefaults to the value of `i18n.commitEncoding` if set, UTF-8\n+\totherwise.\n+\n+log.date::\n+\tDefault format for human-readable dates. (Compare the\n+\t`--date` option.) Defaults to \"default\", which means to write\n+\tdates like `Sat May 8 19:35:34 2010 -0500`.\n+\n+log.showroot::\n+\tIf `false`, 'git log' and related commands will not treat the\n+\tinitial commit as a big creation event. Any root commits in\n+\t`git log -p` output would be shown without a diff attached.\n+\tThe default is `true`.\n+\n+mailmap.file::\n+\tSee linkgit:git-shortlog[1].\n+\n+notes.displayRef::\n+\tWhich refs, in addition to the default set by `core.notesRef`\n+\tor 'GIT_NOTES_REF', to read notes from when showing commit\n+\tmessages with the 'log' family of commands. See\n+\tlinkgit:git-notes[1].\n++\n+May be an unabbreviated ref name or a glob and may be specified\n+multiple times. A warning will be issued for refs that do not exist,\n+but a glob that does not match any refs is silently ignored.\n++\n+This setting can be disabled by the `--no-standard-notes` option,\n+overridden by the 'GIT_NOTES_DISPLAY_REF' environment variable,\n+and supplemented by the `--show-notes` option.\n \n Author\n ------\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex 4e5113b..1d8eef1 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,24 +20,26 @@ 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-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+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 the default setting).\n+\"Notes:\" for `refs/notes/commits`).\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+To change which notes are shown by 'git log', see the\n+\"notes.displayRef\" configuration in linkgit:git-log[1].\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 to carry\n+notes across commands that rewrite commits.\n \n \n SUBCOMMANDS\n@@ -101,15 +103,20 @@ OPTIONS\n \tUse the given note message (instead of prompting).\n \tIf multiple `-m` options are given, their values\n \tare concatenated as separate paragraphs.\n+\tLines starting with `#` and empty lines other than a\n+\tsingle line between paragraphs will be stripped out.\n \n -F ::\n --file=::\n \tTake the note message from the given file. Use '-' to\n \tread the note message from the standard input.\n+\tLines starting with `#` and empty lines other than a\n+\tsingle line between paragraphs will be stripped out.\n \n -C ::\n --reuse-message=::\n-\tReuse the note message from the given note object.\n+\tTake the note message from the given blob object (for\n+\texample, another note).\n \n -c ::\n --reedit-message=::\n@@ -117,22 +124,147 @@ OPTIONS\n \tthe user can further edit the note message.\n \n --ref ::\n-\tManipulate the notes tree in . This overrides both\n-\tGIT_NOTES_REF and the \"core.notesRef\" configuration. The ref\n+\tManipulate the notes tree in . This overrides\n+\t'GIT_NOTES_REF' and the \"core.notesRef\" configuration. The ref\n \tis taken to be in `refs/notes/` if it is not qualified.\n \n \n-NOTES\n------\n+DISCUSSION\n+----------\n+\n+Commit notes are blobs containing extra information about an object\n+(usually information to supplement a commit's message). These blobs\n+are taken from notes refs. A notes ref is usually a branch which\n+contains \"files\" whose paths are the object names for the objects\n+they describe, with some directory separators included for performance\n+reasons footnote:[Permitted pathnames have the form\n+'ab'`/`'cd'`/`'ef'`/`'...'`/`'abcdef...': a sequence of directory\n+names of two hexadecimal digits each followed by a filename with the\n+rest of the object ID.].\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`.\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 \n-Currently the commit message only records which operation triggered\n-the update, and the commit authorship is determined according to the\n-usual rules (see linkgit:git-commit[1]). These details may change in\n-the future.\n+Some notes refs may be \"history-less\", either because they point\n+directly to a tree instead of a commit, or because their commits are\n+truncated; the notes generated by textconv caching\n+(see linkgit:gitattributes[5]) are an example of the latter.\n+To see the local history of these refs, view the reflog with\n+`git log -g `.\n+\n+\n+EXAMPLES\n+--------\n+\n+You can use notes to add annotations with information that was not\n+available at the time a commit was written.\n+\n+------------\n+$ git notes add -m 'Tested-by: Johannes Sixt ' 72a144e2\n+$ git show -s 72a144e\n+[...]\n+ Signed-off-by: Junio C Hamano \n+\n+Notes:\n+ Tested-by: Johannes Sixt \n+------------\n+\n+In principle, a note is a regular Git blob, and any kind of\n+(non-)format is accepted. You can binary-safely create notes from\n+arbitrary files using 'git hash-object':\n+\n+------------\n+$ cc *.c\n+$ blob=$(git hash-object -w a.out)\n+$ git notes --ref=built add -C \"$blob\" HEAD\n+------------\n+\n+Of course, it doesn't make much sense to display non-text-format notes\n+with 'git log', so if you use such notes, you'll probably need to write\n+some special-purpose tools to do something useful with them.\n+\n+\n+CONFIGURATION\n+-------------\n+\n+core.notesRef::\n+\tNotes ref to read and manipulate instead of\n+\t`refs/notes/commits`. Must be an unabbreviated ref name.\n+\tThis setting can be overridden by the 'GIT_NOTES_REF'\n+\tenvironment variable or the `--ref` option.\n+\n+notes.displayRef::\n+\tWhich ref (or refs, if a glob or specified more than once), in\n+\taddition to the default set by `core.notesRef` or\n+\t'GIT_NOTES_REF', to read notes from when showing commit\n+\tmessages with the 'git log' family of commands.\n+\tThis setting can be overridden on the command line or by the\n+\t'GIT_NOTES_DISPLAY_REF' environment variable.\n+\tSee linkgit:git-log[1].\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`, and `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; you must configure this variable to\n+enable note rewriting.\n++\n+Can be overridden with the 'GIT_NOTES_REWRITE_REF' environment variable.\n+\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+\tColon-delimited list of refs or globs indicating which refs,\n+\tin addition to the default from `core.notesRef` or\n+\t'GIT_NOTES_REF', to read notes from when showing commit\n+\tmessages.\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`, and `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 depends\n+on the `notes.rewrite.` and `notes.rewriteRef` settings.\n \n \n Author\ndiff --git a/t/t3307-notes-man.sh b/t/t3307-notes-man.sh\nnew file mode 100755\nindex 0000000..3269f2e\n--- /dev/null\n+++ b/t/t3307-notes-man.sh\n@@ -0,0 +1,38 @@\n+#!/bin/sh\n+\n+test_description='Examples from the git-notes man page\n+\n+Make sure the manual is not full of lies.'\n+\n+. ./test-lib.sh\n+\n+test_expect_success 'setup' '\n+\ttest_commit A &&\n+\ttest_commit B &&\n+\ttest_commit C\n+'\n+\n+test_expect_success 'example 1: notes to add an Acked-by line' '\n+\tcat <<-\\EOF >expect &&\n+\t B\n+\n+\tNotes:\n+\t Acked-by: A C Ker \n+\tEOF\n+\tgit notes add -m \"Acked-by: A C Ker \" B &&\n+\tgit show -s B^{commit} >log &&\n+\ttail -n 4 log >actual &&\n+\ttest_cmp expect actual\n+'\n+\n+test_expect_success 'example 2: binary notes' '\n+\tcp \"$TEST_DIRECTORY\"/test4012.png .\n+\tgit checkout B &&\n+\tblob=$(git hash-object -w test4012.png) &&\n+\tgit notes --ref=logo add -C \"$blob\" &&\n+\tgit notes --ref=logo copy B C &&\n+\tgit notes --ref=logo show C >actual &&\n+\ttest_cmp test4012.png actual\n+'\n+\n+test_done\n-- \n1.7.1\n"}]}