{"thread":{"id":"37625","subject":"[PATCH] docs/git-mailinfo: Mention the manual separator (---)","startedAt":"2014-09-24T15:25:32Z","lastAt":"2014-09-30T22:37:46Z","messageCount":4,"participants":["W. Trevor King","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"249830","messageId":"28b04f1c17f2cc2fe252948bc0b7bb10df24b489.1411571629.git.wking@tremily.us","threadId":"37625","inReplyTo":null,"subject":"[PATCH] docs/git-mailinfo: Mention the manual separator (---)","fromName":"W. Trevor King","fromEmail":"wking@tremily.us","sentAt":"2014-09-24T15:25:32Z","receivedAt":"2014-09-24T15:25:32Z","isPatch":true,"sender":{"key":"wking@tremily.us","avatar":"https://avatars.githubusercontent.com/u/209920?v=4"},"body":"And explain how it interacts with the scissors setting.\n\nSigned-off-by: W. Trevor King <wking@tremily.us>\n---\nThe three-dash limit comes from f0658cf2 (restrict the patch\nfiltering, 2007-03-12), but I couldn't find any associated\ndocumentation.  Since the effect is so similar to the scissors line, I\nthought about adding the information to the --scissors entry.  The\nmanual separator is really independent from the scissors though, so I\nsettled on explaining both separators in the DESCRIPTION.\n\nThis patch is against 'maint'.\n\n Documentation/git-mailinfo.txt | 23 +++++++++++++++++++++++\n 1 file changed, 23 insertions(+)\n\ndiff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt\nindex 164a3c6..6c6c527 100644\n--- a/Documentation/git-mailinfo.txt\n+++ b/Documentation/git-mailinfo.txt\n@@ -21,6 +21,29 @@ written out to the standard output to be used by 'git am'\n to create a commit.  It is usually not necessary to use this\n command directly.  See linkgit:git-am[1] instead.\n \n+The commit message extracted from the e-mail depends on the scissors\n+setting (see '--[no-]scissors' in the OPTIONS section).  Besides the\n+scissors option (which discards content before the scissors), you can\n+also use '---' as a separator (which discards content after the\n+separator).  For example, without scissors you can have a body like\n+this:\n+\n+------------\n+Your commit message.\n+---\n+Comments that aren't part of the commit message.\n+------------\n+\n+With scissors, you can have a body like this:\n+\n+------------\n+Comments that aren't part of the commit message.\n+--->8---\n+Your commit message.\n+---\n+More comments that aren't part of the commit message.\n+------------\n+\n \n OPTIONS\n -------\n-- \n2.1.0.60.g85f0837\n"},{"id":"250048","messageId":"xmqqiok4rew5.fsf@gitster.dls.corp.google.com","threadId":"37625","inReplyTo":"28b04f1c17f2cc2fe252948bc0b7bb10df24b489.1411571629.git.wking@tremily.us","subject":"Re: [PATCH] docs/git-mailinfo: Mention the manual separator (---)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-09-30T21:12:58Z","receivedAt":"2014-09-30T21:12:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"W. Trevor King\" <wking@tremily.us> writes:\n\n> And explain how it interacts with the scissors setting.\n>\n> Signed-off-by: W. Trevor King <wking@tremily.us>\n> ---\n> The three-dash limit comes from f0658cf2 (restrict the patch\n> filtering, 2007-03-12), but I couldn't find any associated\n> documentation.  Since the effect is so similar to the scissors line, I\n> thought about adding the information to the --scissors entry.  The\n> manual separator is really independent from the scissors though, so I\n> settled on explaining both separators in the DESCRIPTION.\n>\n> This patch is against 'maint'.\n>\n>  Documentation/git-mailinfo.txt | 23 +++++++++++++++++++++++\n>  1 file changed, 23 insertions(+)\n>\n> diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt\n> index 164a3c6..6c6c527 100644\n> --- a/Documentation/git-mailinfo.txt\n> +++ b/Documentation/git-mailinfo.txt\n> @@ -21,6 +21,29 @@ written out to the standard output to be used by 'git am'\n>  to create a commit.  It is usually not necessary to use this\n>  command directly.  See linkgit:git-am[1] instead.\n>  \n> +The commit message extracted from the e-mail depends on the scissors\n> +setting (see '--[no-]scissors' in the OPTIONS section). ...\n\nIt encourages a wrong way to look at it to phrase it like this.\n\nThe scissors marker is not about commit log message alone, as you\ncan have in-body headers like From: and Subject: to override them\nafter the marker, and also in-body headers before the scissors are\nignored (it is not even \"We read From: from the part before the\nscissors but then let it be overriden with another From: after the\nscissors\" ).  The right way to look at it is this: \"The scissors\nline will cause everything before it discarded and Git pretends as\nif the body of the message begins after it\".\n\nIf we are extending the documentation on \"---\", it should also\nmention the caveats, namely, it is encouraged to indent the extra\nmessage by a SP or something to make sure that it is not mistaken as\npart of the patch.  I suspect that this omission from this patch\nstems from \"content after the separator is discarded\", which is not\nthe case.  Content after the separator is fed to \"git apply\" as a\npatch.  \"apply\" may \"discard\" non-patch and the end result may be\nthat the garbage disappears, but that is not the primary reason why\nit does not appear in the resulting log message.  If anything, \"---\"\nseparates between the log part from patch part.\n\nThe second example concentrates too heavily on log message which\nmakes it a not-very-good addition as-is.\n\n> +Besides the\n> +scissors option (which discards content before the scissors), you can\n> +also use '---' as a separator (which discards content after the\n> +separator).  For example, without scissors you can have a body like\n> +this:\n> +\n> +------------\n> +Your commit message.\n> +---\n> +Comments that aren't part of the commit message.\n> +------------\n> +\n> +With scissors, you can have a body like this:\n> +\n> +------------\n> +Comments that aren't part of the commit message.\n> +--->8---\n> +Your commit message.\n> +---\n> +More comments that aren't part of the commit message.\n> +------------\n> +\n>  \n>  OPTIONS\n>  -------\n"},{"id":"250050","messageId":"20140930214846.GK3770@odin.tremily.us","threadId":"37625","inReplyTo":"xmqqiok4rew5.fsf@gitster.dls.corp.google.com","subject":"Re: [PATCH] docs/git-mailinfo: Mention the manual separator (---)","fromName":"W. Trevor King","fromEmail":"wking@tremily.us","sentAt":"2014-09-30T21:48:46Z","receivedAt":"2014-09-30T21:48:46Z","isPatch":true,"sender":{"key":"wking@tremily.us","avatar":"https://avatars.githubusercontent.com/u/209920?v=4"},"body":"On Tue, Sep 30, 2014 at 02:12:58PM -0700, Junio C Hamano wrote:\n> If we are extending the documentation on \"---\", …\n\nAh, I see that the --- are actually mentioned already in the\nDISCUSSION section of git-am(1) since 2499857b (git-am documentation:\ndescribe what is taken from where, 2007-03-24).  I expected the docs\nto be either in git-mailinfo(1) (since the code added by f0658cf2\n(restrict the patch filtering, 2007-03-12) is in mailinfo) or to match\na grep for '---'.  Maybe we should drop this patch in favor of notes\nin git-mailinfo(1) and git-format-patch(1) pointing folks at the\nDISCUSSION section in git-am(1) and a more easily grepable “three\ndashes ('---')\" in gi-am(1)?\n\nCheers,\nTrevor\n\n-- \nThis email may be signed or encrypted with GnuPG (http://www.gnupg.org).\nFor more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy\n"},{"id":"250053","messageId":"xmqq38b8rayt.fsf@gitster.dls.corp.google.com","threadId":"37625","inReplyTo":"20140930214846.GK3770@odin.tremily.us","subject":"Re: [PATCH] docs/git-mailinfo: Mention the manual separator (---)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2014-09-30T22:37:46Z","receivedAt":"2014-09-30T22:37:46Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"W. Trevor King\" <wking@tremily.us> writes:\n\n> ...  Maybe we should drop this patch in favor of notes\n> in git-mailinfo(1) and git-format-patch(1) pointing folks at the\n> DISCUSSION section in git-am(1) and a more easily grepable “three\n> dashes ('---')\" in gi-am(1)?\n\nI am all for dropping new changes and expecially duplicates ;-)\n\nBecause I would be a bad judge for suggesting the place that a new\nreader likely expects to find relevant information, as I am not a\nnew reader who does not know where to start looking, I'll let others\nfigure out where the best places to add enhancements to are.\n\nThanks.\n"}]}