[PATCH] Documentation: explain "mboxrd" pretty format

[PATCH] Documentation: explain "mboxrd" pretty format

[Emma Brooks]

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 <me@pluvano.com>
---
 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
 
 	  <full commit message>
 
+* '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

Re: [PATCH] Documentation: explain "mboxrd" pretty format

[Eric Wong]

Emma Brooks <me@pluvano.com> 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 <me@pluvano.com>

Acked-by: Eric Wong <e@80x24.org>

> +++ b/Documentation/pretty-formats.txt
> @@ -83,6 +83,12 @@ placeholders, its output is not affected by other options like
>  
>  	  <full commit message>
>  
> +* '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.

Re: [PATCH] Documentation: explain "mboxrd" pretty format

[Junio C Hamano]

Emma Brooks <me@pluvano.com> 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 <me@pluvano.com>
> ---
>  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
>  
>  	  <full commit message>
>  
> +* '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

Re: [PATCH] Documentation: explain "mboxrd" pretty format

[Emma Brooks]

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.

Re: [PATCH] Documentation: explain "mboxrd" pretty format

[Junio C Hamano]

Emma Brooks <me@pluvano.com> 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" ;-)