# [PATCH] Documentation: explain "mboxrd" pretty format 5 messages from 2020-04-16 to 2020-04-17. Participants: Emma Brooks, Eric Wong, Junio C Hamano. Thread: https://gitlist.dev/t/53242 ## Emma Brooks, 2020-04-16 04:16 Subject: [PATCH] Documentation: explain "mboxrd" pretty format Message-ID: <20200416041658.85100-1-me@pluvano.com> URL: https://gitlist.dev/e/20200416041658.85100-1-me%40pluvano.com ``` The "mboxrd" pretty format was introduced in 9f23e04061 (pretty: support "mboxrd" output format, 2016-06-05) but wasn't mentioned in the documentation. Signed-off-by: Emma Brooks --- Documentation/pretty-formats.txt | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index a4b6f49186..547a552463 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -83,6 +83,12 @@ placeholders, its output is not affected by other options like +* 'mboxrd' ++ +Like 'email', but lines in the commit message starting with "From " +(preceded by zero or more ">") are quoted with ">" so they aren't +confused as starting a new commit. + * 'raw' + The 'raw' format shows the entire commit exactly as ``` ## Eric Wong, 2020-04-16 04:44 Subject: Re: [PATCH] Documentation: explain "mboxrd" pretty format Message-ID: <20200416044445.tgofuvhp6c2i4ebh@dcvr> URL: https://gitlist.dev/e/20200416044445.tgofuvhp6c2i4ebh%40dcvr In-Reply-To: <20200416041658.85100-1-me@pluvano.com> ``` Emma Brooks wrote: > The "mboxrd" pretty format was introduced in 9f23e04061 (pretty: support > "mboxrd" output format, 2016-06-05) but wasn't mentioned in the > documentation. Oops :x Thanks for documenting it, now. > Signed-off-by: Emma Brooks Acked-by: Eric Wong > +++ b/Documentation/pretty-formats.txt > @@ -83,6 +83,12 @@ placeholders, its output is not affected by other options like > > > > +* 'mboxrd' > ++ > +Like 'email', but lines in the commit message starting with "From " > +(preceded by zero or more ">") are quoted with ">" so they aren't > +confused as starting a new commit. > + Looks good to me, thanks again. ``` ## Junio C Hamano, 2020-04-16 05:03 Subject: Re: [PATCH] Documentation: explain "mboxrd" pretty format Message-ID: URL: https://gitlist.dev/e/xmqqlfmw2f9z.fsf%40gitster.c.googlers.com In-Reply-To: <20200416041658.85100-1-me@pluvano.com> ``` Emma Brooks writes: > The "mboxrd" pretty format was introduced in 9f23e04061 (pretty: support > "mboxrd" output format, 2016-06-05) but wasn't mentioned in the > documentation. > > Signed-off-by: Emma Brooks > --- > Documentation/pretty-formats.txt | 6 ++++++ > 1 file changed, 6 insertions(+) > > diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt > index a4b6f49186..547a552463 100644 > --- a/Documentation/pretty-formats.txt > +++ b/Documentation/pretty-formats.txt > @@ -83,6 +83,12 @@ placeholders, its output is not affected by other options like > > > > +* 'mboxrd' > ++ > +Like 'email', but lines in the commit message starting with "From " > +(preceded by zero or more ">") are quoted with ">" so they aren't > +confused as starting a new commit. I am torn between rephrasing "starting a new commit" with "starting a new e-mail message", and keeping it as-is. Technically, the latter is more correct---the >From quoting is a technique to avoid starting a line with "From " in a reversible way, as pieces of e-mails in a single mailbox file needs to be split at the boundary. But in the context of format-patch, perhaps saying each "record" in the output file is a "commit" (not a piece of e-mail message) would probably be an acceptable white lie. Thanks. > * 'raw' > + > The 'raw' format shows the entire commit exactly as ``` ## Emma Brooks, 2020-04-17 01:47 Subject: Re: [PATCH] Documentation: explain "mboxrd" pretty format Message-ID: <20200417014713.GA20574@pluvano.com> URL: https://gitlist.dev/e/20200417014713.GA20574%40pluvano.com In-Reply-To: ``` On 2020-04-15 22:03:36-0700, Junio C Hamano wrote: > > +Like 'email', but lines in the commit message starting with "From " > > +(preceded by zero or more ">") are quoted with ">" so they aren't > > +confused as starting a new commit. > > I am torn between rephrasing "starting a new commit" with "starting > a new e-mail message", and keeping it as-is. Technically, the latter > is more correct---the >From quoting is a technique to avoid starting > a line with "From " in a reversible way, as pieces of e-mails in a > single mailbox file needs to be split at the boundary. But in the > context of format-patch, perhaps saying each "record" in the output > file is a "commit" (not a piece of e-mail message) would probably be > an acceptable white lie. While it is more accurate to say "starting a new email" rather than "commit", I think it might be less confusing to say "starting a new commit", if the reader isn't already familiar with how mbox works or its variants, since the pretty formats control commit display and would typically be thought about in terms of commits rather than emails. ``` ## Junio C Hamano, 2020-04-17 02:00 Subject: Re: [PATCH] Documentation: explain "mboxrd" pretty format Message-ID: URL: https://gitlist.dev/e/xmqqzhbax44l.fsf%40gitster.c.googlers.com In-Reply-To: <20200417014713.GA20574@pluvano.com> ``` Emma Brooks writes: > On 2020-04-15 22:03:36-0700, Junio C Hamano wrote: >> > +Like 'email', but lines in the commit message starting with "From " >> > +(preceded by zero or more ">") are quoted with ">" so they aren't >> > +confused as starting a new commit. >> >> I am torn between rephrasing "starting a new commit" with "starting >> a new e-mail message", and keeping it as-is. Technically, the latter >> is more correct---the >From quoting is a technique to avoid starting >> a line with "From " in a reversible way, as pieces of e-mails in a >> single mailbox file needs to be split at the boundary. But in the >> context of format-patch, perhaps saying each "record" in the output >> file is a "commit" (not a piece of e-mail message) would probably be >> an acceptable white lie. > > While it is more accurate to say "starting a new email" rather than > "commit", I think it might be less confusing to say "starting a new > commit", if the reader isn't already familiar with how mbox works or its > variants, since the pretty formats control commit display and would > typically be thought about in terms of commits rather than emails. Exactly. That is why I said that I was torn between technical correctness and tool-specific description. "torn between" is quite different from "inclined to prefer the one different from yours" ;-) ```