{"thread":{"id":"53242","subject":"[PATCH] Documentation: explain \"mboxrd\" pretty format","startedAt":"2020-04-16T04:19:30Z","lastAt":"2020-04-17T02:01:06Z","messageCount":5,"participants":["Emma Brooks","Eric Wong","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"395567","messageId":"20200416041658.85100-1-me@pluvano.com","threadId":"53242","inReplyTo":null,"subject":"[PATCH] Documentation: explain \"mboxrd\" pretty format","fromName":"Emma Brooks","fromEmail":"me@pluvano.com","sentAt":"2020-04-16T04:16:59Z","receivedAt":"2020-04-16T04:19:30Z","isPatch":true,"sender":{"key":"me@pluvano.com","avatar":"https://avatars.githubusercontent.com/u/50312486?v=4"},"body":"The \"mboxrd\" pretty format was introduced in 9f23e04061 (pretty: support\n\"mboxrd\" output format, 2016-06-05) but wasn't mentioned in the\ndocumentation.\n\nSigned-off-by: Emma Brooks \n---\n Documentation/pretty-formats.txt | 6 ++++++\n 1 file changed, 6 insertions(+)\n\ndiff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt\nindex a4b6f49186..547a552463 100644\n--- a/Documentation/pretty-formats.txt\n+++ b/Documentation/pretty-formats.txt\n@@ -83,6 +83,12 @@ placeholders, its output is not affected by other options like\n \n \t \n \n+* 'mboxrd'\n++\n+Like 'email', but lines in the commit message starting with \"From \"\n+(preceded by zero or more \">\") are quoted with \">\" so they aren't\n+confused as starting a new commit.\n+\n * 'raw'\n +\n The 'raw' format shows the entire commit exactly as\n"},{"id":"395568","messageId":"20200416044445.tgofuvhp6c2i4ebh@dcvr","threadId":"53242","inReplyTo":"20200416041658.85100-1-me@pluvano.com","subject":"Re: [PATCH] Documentation: explain \"mboxrd\" pretty format","fromName":"Eric Wong","fromEmail":"e@80x24.org","sentAt":"2020-04-16T04:44:45Z","receivedAt":"2020-04-16T04:44:51Z","isPatch":true,"sender":{"key":"e@80x24.org","avatar":null},"body":"Emma Brooks wrote:\n> The \"mboxrd\" pretty format was introduced in 9f23e04061 (pretty: support\n> \"mboxrd\" output format, 2016-06-05) but wasn't mentioned in the\n> documentation.\n\nOops :x Thanks for documenting it, now.\n\n> Signed-off-by: Emma Brooks \n\nAcked-by: Eric Wong \n\n> +++ b/Documentation/pretty-formats.txt\n> @@ -83,6 +83,12 @@ placeholders, its output is not affected by other options like\n> \n> \t \n> \n> +* 'mboxrd'\n> ++\n> +Like 'email', but lines in the commit message starting with \"From \"\n> +(preceded by zero or more \">\") are quoted with \">\" so they aren't\n> +confused as starting a new commit.\n> +\n\nLooks good to me, thanks again.\n"},{"id":"395572","messageId":"xmqqlfmw2f9z.fsf@gitster.c.googlers.com","threadId":"53242","inReplyTo":"20200416041658.85100-1-me@pluvano.com","subject":"Re: [PATCH] Documentation: explain \"mboxrd\" pretty format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-04-16T05:03:36Z","receivedAt":"2020-04-16T05:03:49Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Emma Brooks writes:\n\n> The \"mboxrd\" pretty format was introduced in 9f23e04061 (pretty: support\n> \"mboxrd\" output format, 2016-06-05) but wasn't mentioned in the\n> documentation.\n>\n> Signed-off-by: Emma Brooks \n> ---\n> Documentation/pretty-formats.txt | 6 ++++++\n> 1 file changed, 6 insertions(+)\n>\n> diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt\n> index a4b6f49186..547a552463 100644\n> --- a/Documentation/pretty-formats.txt\n> +++ b/Documentation/pretty-formats.txt\n> @@ -83,6 +83,12 @@ placeholders, its output is not affected by other options like\n> \n> \t \n> \n> +* 'mboxrd'\n> ++\n> +Like 'email', but lines in the commit message starting with \"From \"\n> +(preceded by zero or more \">\") are quoted with \">\" so they aren't\n> +confused as starting a new commit.\n\nI am torn between rephrasing \"starting a new commit\" with \"starting\na new e-mail message\", and keeping it as-is. Technically, the latter\nis more correct---the >From quoting is a technique to avoid starting\na line with \"From \" in a reversible way, as pieces of e-mails in a\nsingle mailbox file needs to be split at the boundary. But in the\ncontext of format-patch, perhaps saying each \"record\" in the output\nfile is a \"commit\" (not a piece of e-mail message) would probably be\nan acceptable white lie.\n\nThanks.\n\n\n> * 'raw'\n> +\n> The 'raw' format shows the entire commit exactly as\n"},{"id":"395639","messageId":"20200417014713.GA20574@pluvano.com","threadId":"53242","inReplyTo":"xmqqlfmw2f9z.fsf@gitster.c.googlers.com","subject":"Re: [PATCH] Documentation: explain \"mboxrd\" pretty format","fromName":"Emma Brooks","fromEmail":"me@pluvano.com","sentAt":"2020-04-17T01:47:13Z","receivedAt":"2020-04-17T01:47:31Z","isPatch":true,"sender":{"key":"me@pluvano.com","avatar":"https://avatars.githubusercontent.com/u/50312486?v=4"},"body":"On 2020-04-15 22:03:36-0700, Junio C Hamano wrote:\n> > +Like 'email', but lines in the commit message starting with \"From \"\n> > +(preceded by zero or more \">\") are quoted with \">\" so they aren't\n> > +confused as starting a new commit.\n> \n> I am torn between rephrasing \"starting a new commit\" with \"starting\n> a new e-mail message\", and keeping it as-is. Technically, the latter\n> is more correct---the >From quoting is a technique to avoid starting\n> a line with \"From \" in a reversible way, as pieces of e-mails in a\n> single mailbox file needs to be split at the boundary. But in the\n> context of format-patch, perhaps saying each \"record\" in the output\n> file is a \"commit\" (not a piece of e-mail message) would probably be\n> an acceptable white lie.\n\nWhile it is more accurate to say \"starting a new email\" rather than\n\"commit\", I think it might be less confusing to say \"starting a new\ncommit\", if the reader isn't already familiar with how mbox works or its\nvariants, since the pretty formats control commit display and would\ntypically be thought about in terms of commits rather than emails.\n"},{"id":"395641","messageId":"xmqqzhbax44l.fsf@gitster.c.googlers.com","threadId":"53242","inReplyTo":"20200417014713.GA20574@pluvano.com","subject":"Re: [PATCH] Documentation: explain \"mboxrd\" pretty format","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2020-04-17T02:00:58Z","receivedAt":"2020-04-17T02:01:06Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Emma Brooks writes:\n\n> On 2020-04-15 22:03:36-0700, Junio C Hamano wrote:\n>> > +Like 'email', but lines in the commit message starting with \"From \"\n>> > +(preceded by zero or more \">\") are quoted with \">\" so they aren't\n>> > +confused as starting a new commit.\n>> \n>> I am torn between rephrasing \"starting a new commit\" with \"starting\n>> a new e-mail message\", and keeping it as-is. Technically, the latter\n>> is more correct---the >From quoting is a technique to avoid starting\n>> a line with \"From \" in a reversible way, as pieces of e-mails in a\n>> single mailbox file needs to be split at the boundary. But in the\n>> context of format-patch, perhaps saying each \"record\" in the output\n>> file is a \"commit\" (not a piece of e-mail message) would probably be\n>> an acceptable white lie.\n>\n> While it is more accurate to say \"starting a new email\" rather than\n> \"commit\", I think it might be less confusing to say \"starting a new\n> commit\", if the reader isn't already familiar with how mbox works or its\n> variants, since the pretty formats control commit display and would\n> typically be thought about in terms of commits rather than emails.\n\nExactly. That is why I said that I was torn between technical\ncorrectness and tool-specific description. \"torn between\" is quite\ndifferent from \"inclined to prefer the one different from yours\" ;-)\n\n"}]}