{"thread":{"id":"31843","subject":"[PATCH] notes: mention --notes in more places","startedAt":"2012-10-17T03:19:35Z","lastAt":"2012-10-18T12:11:57Z","messageCount":8,"participants":["Eric Blake","Junio C Hamano","Jeff King","Michael J Gruber"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"201398","messageId":"1350443975-19935-1-git-send-email-eblake@redhat.com","threadId":"31843","inReplyTo":null,"subject":"[PATCH] notes: mention --notes in more places","fromName":"Eric Blake","fromEmail":"eblake@redhat.com","sentAt":"2012-10-17T03:19:35Z","receivedAt":"2012-10-17T03:19:35Z","isPatch":true,"sender":{"key":"eblake@redhat.com","avatar":"https://avatars.githubusercontent.com/u/32933908?v=4"},"body":"Every so often, I search 'git send-email --help' to remember some\noption I've used in the past, only to discover that the option is\ndocumented instead in 'git format-patch --help'. Worse, even that\ncommand didn't document the option I was looking for today, which\nwas how to include 'git notes' in the body of the commits I was\nmailing. Reading 'git notes --help' didn't mention this either,\nand I had to resort to searching the source code. It can't hurt\nto add some documentation to make this option less obscure.\n\n* git-notes.txt: Mention that --notes option exists in many\ncommands to override defaults.\n* git-format-patch.txt: Include pretty-options, for things like\n--notes.\n* git-send-email.txt: Mention that revision lists forwarded to\nformat-patch can also include options.\n\nSigned-off-by: Eric Blake \n---\n Documentation/git-format-patch.txt | 2 ++\n Documentation/git-notes.txt | 6 ++++--\n Documentation/git-send-email.txt | 3 ++-\n 3 files changed, 8 insertions(+), 3 deletions(-)\n\ndiff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\nindex 6d43f56..a068f37 100644\n--- a/Documentation/git-format-patch.txt\n+++ b/Documentation/git-format-patch.txt\n@@ -222,6 +222,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.\n \trange are always formatted as creation patches, independently\n \tof this flag.\n\n+include::pretty-options.txt[]\n+\n CONFIGURATION\n -------------\n You can specify extra mail header lines to be added to each message,\ndiff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\nindex b95aafa..be9e60f 100644\n--- a/Documentation/git-notes.txt\n+++ b/Documentation/git-notes.txt\n@@ -39,8 +39,10 @@ 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 in linkgit:git-log[1].\n+To change which notes are shown by default in 'git log', see the\n+\"notes.displayRef\" configuration in linkgit:git-log[1]. Also,\n+many commands understand a `--notes` option to alter the set of\n+notes displayed (see linkgit:git-rev-list[1]).\n\n See the \"notes.rewrite.\" configuration for a way to carry\n notes across commands that rewrite commits.\ndiff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\nindex eeb561c..450d975 100644\n--- a/Documentation/git-send-email.txt\n+++ b/Documentation/git-send-email.txt\n@@ -18,7 +18,8 @@ Takes the patches given on the command line and emails them out.\n Patches can be specified as files, directories (which will send all\n files in the directory), or directly as a revision list. In the\n last case, any format accepted by linkgit:git-format-patch[1] can\n-be passed to git send-email.\n+be passed to git send-email, including additional command line\n+options such as `--cover-letter` or `--notes`.\n\n The header of the email is configurable by command line options. If not\n specified on the command line, the user will be prompted with a ReadLine\n-- \n1.7.11.7\n"},{"id":"201401","messageId":"7vvce9ptmr.fsf@alter.siamese.dyndns.org","threadId":"31843","inReplyTo":"1350443975-19935-1-git-send-email-eblake@redhat.com","subject":"Re: [PATCH] notes: mention --notes in more places","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-10-17T05:14:36Z","receivedAt":"2012-10-17T05:14:36Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Eric Blake writes:\n\n> * git-notes.txt: Mention that --notes option exists in many\n> commands to override defaults.\n> * git-format-patch.txt: Include pretty-options, for things like\n> --notes.\n> * git-send-email.txt: Mention that revision lists forwarded to\n> format-patch can also include options.\n\nOverall I feel fairly negative on this one, even though there are\ngood bits.\n\n>\n> Signed-off-by: Eric Blake \n> ---\n> Documentation/git-format-patch.txt | 2 ++\n> Documentation/git-notes.txt | 6 ++++--\n> Documentation/git-send-email.txt | 3 ++-\n> 3 files changed, 8 insertions(+), 3 deletions(-)\n>\n> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt\n> index 6d43f56..a068f37 100644\n> --- a/Documentation/git-format-patch.txt\n> +++ b/Documentation/git-format-patch.txt\n> @@ -222,6 +222,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.\n> \trange are always formatted as creation patches, independently\n> \tof this flag.\n>\n> +include::pretty-options.txt[]\n\nIn the context of format-patch, the inclusion of pretty-options\nprobably causes more harm than being helpful, I am afraid. If you\nuse \"--pretty=\", \"--format=\", or \"--oneline\", the\noutput will no longer be a proper mbox and is not suitable for\nasking somebody else to apply.\n\nAt the very least, you would need to add something like:\n\n ifndef::git-format-patch[]\n ... enclose everything that should not be used with format-patch\n endif::git-format-patch[]\n\nto the included file, and then define the token before the\ninclusion, like this:\n\n :git-format-patch: 1\n include::pretty-formats.txt[]\n\nto limit the damage.\n\nEven with such a change to include only --notes, I am not sure if\nthe result is something we would want to recommend/advertise to our\nusers.\n\nThe output from format-patch with --notes shows the notes, after\nadding a blank line to the sign-off block, to look like this:\n\n\tFrom: A U Thor \n Date: Tue, 16 Oct 2012 19:26:23 +0200\n\tSubject: [PATCH] Gostak: distim the doshes correctly\n\n\tWith the current code, the Gostak cannot correctly distim\n the doshes, because ...\n\n\tSigned-off-by: Junio C Hamano \n\n\tNotes:\n\t\tThis patch was inspired by Eric Blake\n\n\t---\n\tdiff --git a/gostak b/gostak\n ...\n\nI am not sure if this is suiable for sending to somebody and asking\nit to be applied.\n\n> diff --git a/Documentation/git-notes.txt b/Documentation/git-notes.txt\n> index b95aafa..be9e60f 100644\n> --- a/Documentation/git-notes.txt\n> +++ b/Documentation/git-notes.txt\n> @@ -39,8 +39,10 @@ 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 in linkgit:git-log[1].\n> +To change which notes are shown by default in 'git log', see the\n> +\"notes.displayRef\" configuration in linkgit:git-log[1]. Also,\n> +many commands understand a `--notes` option to alter the set of\n> +notes displayed (see linkgit:git-rev-list[1]).\n>\n> See the \"notes.rewrite.\" configuration for a way to carry\n> notes across commands that rewrite commits.\n\nOK.\n\n> diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt\n> index eeb561c..450d975 100644\n> --- a/Documentation/git-send-email.txt\n> +++ b/Documentation/git-send-email.txt\n> @@ -18,7 +18,8 @@ Takes the patches given on the command line and emails them out.\n> Patches can be specified as files, directories (which will send all\n> files in the directory), or directly as a revision list. In the\n> last case, any format accepted by linkgit:git-format-patch[1] can\n> -be passed to git send-email.\n> +be passed to git send-email, including additional command line\n> +options such as `--cover-letter` or `--notes`.\n\nOK for --cover-letter, dubious on --notes.\n"},{"id":"201403","messageId":"20121017055136.GA12301@sigill.intra.peff.net","threadId":"31843","inReplyTo":"1350443975-19935-1-git-send-email-eblake@redhat.com","subject":"Re: [PATCH] notes: mention --notes in more places","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-10-17T05:51:37Z","receivedAt":"2012-10-17T05:51:37Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Tue, Oct 16, 2012 at 09:19:35PM -0600, Eric Blake wrote:\n\n> Every so often, I search 'git send-email --help' to remember some\n> option I've used in the past, only to discover that the option is\n> documented instead in 'git format-patch --help'. Worse, even that\n> command didn't document the option I was looking for today, which\n> was how to include 'git notes' in the body of the commits I was\n> mailing. Reading 'git notes --help' didn't mention this either,\n> and I had to resort to searching the source code. It can't hurt\n> to add some documentation to make this option less obscure.\n\nI think this is a good direction, but...\n\n> * git-notes.txt: Mention that --notes option exists in many\n> commands to override defaults.\n> * git-format-patch.txt: Include pretty-options, for things like\n> --notes.\n\nThere are many things in pretty-options that would not be appropriate\nfor format-patch. We should probably wrap them like this:\n\ndiff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt\nindex 5e49942..a0f1d15 100644\n--- a/Documentation/pretty-options.txt\n+++ b/Documentation/pretty-options.txt\n@@ -1,3 +1,4 @@\n+ifndef::git-format-patch[]\n --pretty[=]::\n --format=::\n \n@@ -27,6 +28,7 @@ people using 80-column terminals.\n --oneline::\n \tThis is a shorthand for \"--pretty=oneline --abbrev-commit\"\n \tused together.\n+endif::git-format-patch[]\n \n --encoding[=]::\n \tThe commit objects record the encoding used for the log message\n\nIt may also make sense to show notes differently when outputting the\n\"email\" format as format-patch does. E.g., using a triple-dash would\nkeep them separate from the commit message when using \"git am\". Like:\n\n your commit message\n\n Signed-off-by: You\n ---\n your notes go here\n\nWe've talked about it several times, but it's never happened (probably\nbecause most people don't actually use notes).\n\n-Peff\n"},{"id":"201404","messageId":"4a445f32-893d-4b27-b056-00b3f036bbaf@email.android.com","threadId":"31843","inReplyTo":"20121017055136.GA12301@sigill.intra.peff.net","subject":"Re: [PATCH] notes: mention --notes in more places","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-10-17T06:25:01Z","receivedAt":"2012-10-17T06:25:01Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King wrote:\n\n>It may also make sense to show notes differently when outputting the\n>\"email\" format as format-patch does. E.g., using a triple-dash would\n>keep them separate from the commit message when using \"git am\". Like:\n>\n> your commit message\n>\n> Signed-off-by: You\n> ---\n> your notes go here\n>\n>We've talked about it several times, but it's never happened (probably\n>because most people don't actually use notes).\n\nIt is sometimes scary how we end up saying identical things independently :-) \n"},{"id":"201427","messageId":"507EB310.8020904@redhat.com","threadId":"31843","inReplyTo":"20121017055136.GA12301@sigill.intra.peff.net","subject":"Re: [PATCH] notes: mention --notes in more places","fromName":"Eric Blake","fromEmail":"eblake@redhat.com","sentAt":"2012-10-17T13:30:56Z","receivedAt":"2012-10-17T13:30:56Z","isPatch":true,"sender":{"key":"eblake@redhat.com","avatar":"https://avatars.githubusercontent.com/u/32933908?v=4"},"body":"On 10/16/2012 11:51 PM, Jeff King wrote:\n> It may also make sense to show notes differently when outputting the\n> \"email\" format as format-patch does. E.g., using a triple-dash would\n> keep them separate from the commit message when using \"git am\". Like:\n> \n> your commit message\n> \n> Signed-off-by: You\n> ---\n> your notes go here\n\nThat's _precisely_ what I want! I want to use notes as a way of\ntracking my edits for what I did in v2 of a patch, at the time I commit\nmy v2, so that I can send a revised series including the notes in a\nmanner most efficient for someone else using 'git am' on the series to\nsee why I sent a v2 but without polluting the upstream repository with\nuseless versioning information from the email.\n\n> \n> We've talked about it several times, but it's never happened (probably\n> because most people don't actually use notes).\n\nAnd people (like me) don't use notes because they aren't documented.\nCatch-22, so we have to start somewhere.\n\nI'll submit a v2 with the non-controversial edits, and spend some time\ntrying to figure out how to isolate the portion of pretty-options.txt\nthat is relevant to format-patch. If it's easy enough, I can also\nconsider using --- instead of Notes: as the separator when using\nformat-patch.\n\n-- \nEric Blake eblake@redhat.com +1-919-301-3266\nLibvirt virtualization library http://libvirt.org\n\n"},{"id":"201444","messageId":"20121017190507.GA17648@sigill.intra.peff.net","threadId":"31843","inReplyTo":"507EB310.8020904@redhat.com","subject":"Re: [PATCH] notes: mention --notes in more places","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2012-10-17T19:05:07Z","receivedAt":"2012-10-17T19:05:07Z","isPatch":true,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Wed, Oct 17, 2012 at 07:30:56AM -0600, Eric Blake wrote:\n\n> > We've talked about it several times, but it's never happened (probably\n> > because most people don't actually use notes).\n> \n> And people (like me) don't use notes because they aren't documented.\n> Catch-22, so we have to start somewhere.\n\nOh, I definitely agree your patch is the right direction. I was just\nexplaining why it hasn't happened, even though people think it's a good\nidea.\n\n> I'll submit a v2 with the non-controversial edits, and spend some time\n> trying to figure out how to isolate the portion of pretty-options.txt\n> that is relevant to format-patch. If it's easy enough, I can also\n> consider using --- instead of Notes: as the separator when using\n> format-patch.\n\nHmm. After digging in the archive, it seems we (including both you and\nme!) have discussed this several times, and there are even some patches\nfloating around. Maybe one of them would be a good starting point for\nyour submission (I did not read carefully over all of the arguments for\neach):\n\n Patch from Thomas, Feb 2010:\n\n http://thread.gmane.org/gmane.comp.version-control.git/139919/focus=140818\n\n Discussion between us, Dec 2010:\n\n http://thread.gmane.org/gmane.comp.version-control.git/163141\n\n Patch from Michael, Apr 2011:\n\n http://thread.gmane.org/gmane.comp.version-control.git/172079\n\n-Peff\n"},{"id":"201450","messageId":"7vsj9cn4z5.fsf@alter.siamese.dyndns.org","threadId":"31843","inReplyTo":"20121017190507.GA17648@sigill.intra.peff.net","subject":"Re: [PATCH] notes: mention --notes in more places","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2012-10-17T21:50:06Z","receivedAt":"2012-10-17T21:50:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> On Wed, Oct 17, 2012 at 07:30:56AM -0600, Eric Blake wrote:\n>\n>> > We've talked about it several times, but it's never happened (probably\n>> > because most people don't actually use notes).\n>> \n>> And people (like me) don't use notes because they aren't documented.\n>> Catch-22, so we have to start somewhere.\n>\n> Oh, I definitely agree your patch is the right direction. I was just\n> explaining why it hasn't happened, even though people think it's a good\n> idea.\n>\n>> I'll submit a v2 with the non-controversial edits, and spend some time\n>> trying to figure out how to isolate the portion of pretty-options.txt\n>> that is relevant to format-patch. If it's easy enough, I can also\n>> consider using --- instead of Notes: as the separator when using\n>> format-patch.\n>\n> Hmm. After digging in the archive, it seems we (including both you and\n> me!) have discussed this several times, and there are even some patches\n> floating around. Maybe one of them would be a good starting point for\n> your submission (I did not read carefully over all of the arguments for\n> each):\n\nThomas's oldest one looked like a good starting point but we've\ngained a codepath to spit out the contents of notes since then, which\nprobably needs to be killed at least for this codepath.\n\nA few problems I noticed while looking at log-tree.c and pretty.c\n\n * pretty_print_commit() shows notes at the end of existing\n message. There is no provision for the callers to affect what\n comes between the existing log message and the notes text.\n\n * show_log() has the \"add-signoff\" that appends a sign-off after\n whatever pretty_print_commit() gives.\n\nTaken together, they make it unnecessarily cumbersome to inject a\nnew sign-off and \"---\" between the log message and notes.\n\nThe easiest is to add another parameter to pretty_print_commit that\nis inserted immediately after the log message before notes are\nappended. That way, we can update show_log() to first format\nadditional sign off (if needed) and then \"---\\n\" (again, if needed)\nto a new strbuf and pass it as the new argument when calling the\npretty_print_commit() function.\n"},{"id":"201509","messageId":"507FF20D.6030106@drmicha.warpmail.net","threadId":"31843","inReplyTo":"20121017190507.GA17648@sigill.intra.peff.net","subject":"Re: [PATCH] notes: mention --notes in more places","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2012-10-18T12:11:57Z","receivedAt":"2012-10-18T12:11:57Z","isPatch":true,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Jeff King venit, vidit, dixit 17.10.2012 21:05:\n> On Wed, Oct 17, 2012 at 07:30:56AM -0600, Eric Blake wrote:\n> \n>>> We've talked about it several times, but it's never happened (probably\n>>> because most people don't actually use notes).\n>>\n>> And people (like me) don't use notes because they aren't documented.\n>> Catch-22, so we have to start somewhere.\n> \n> Oh, I definitely agree your patch is the right direction. I was just\n> explaining why it hasn't happened, even though people think it's a good\n> idea.\n> \n>> I'll submit a v2 with the non-controversial edits, and spend some time\n>> trying to figure out how to isolate the portion of pretty-options.txt\n>> that is relevant to format-patch. If it's easy enough, I can also\n>> consider using --- instead of Notes: as the separator when using\n>> format-patch.\n> \n> Hmm. After digging in the archive, it seems we (including both you and\n> me!) have discussed this several times, and there are even some patches\n> floating around. Maybe one of them would be a good starting point for\n> your submission (I did not read carefully over all of the arguments for\n> each):\n> \n> Patch from Thomas, Feb 2010:\n> \n> http://thread.gmane.org/gmane.comp.version-control.git/139919/focus=140818\n> \n> Discussion between us, Dec 2010:\n> \n> http://thread.gmane.org/gmane.comp.version-control.git/163141\n> \n> Patch from Michael, Apr 2011:\n> \n> http://thread.gmane.org/gmane.comp.version-control.git/172079\n\nThat one used to work for about one more year or so (it went through a\nfew rebases) but stopped working during some rework involving the\nsignature (signed-off-by), i.e. it puts the notes before the signed-off\nnow. I didn't update it because nobody seemed interested anyway (and\nbecause branch-notes got implemented in a different, non-note way, so I\ndumped that part of my workflow also).\n\nMichael\n"}]}