Skip to contentSkip to conversation

Documentation: explain "mboxrd" pretty format

PATCH In review Emma Brooks 3 participants 5 messages Apr 16, 2020 – Apr 17, 2020 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 Documentation: explain "mboxrd" pretty format

The "mboxrd" pretty format was introduced in 9f23e04061 (pretty: support "mboxrd" output format, 2016-06-05) but wasn't mentioned in the documentation.

---
 Documentation/pretty-formats.txt | 6 ++++++
 1 file changed, 6 insertions(+)
Documentation/pretty-formats.txt +6 -0
index a4b6f49186..547a552463 100644
@@ -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
Acked-by on v1 1/1
#1 lore raw
Quoted 3 lines · 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.

Oops :x Thanks for documenting it, now.

Quoted 1 line

Documentation/pretty-formats.txt placeholders, its output is not affected by other options like · line 91

Quoted 11 lines

+++ b/Documentation/pretty-formats.txt

Documentation/pretty-formats.txt +6 -0
@@ -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.

#2 lore raw
In reply to Emma Brooks
Quoted 14 lines · 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.

---
 Documentation/pretty-formats.txt | 6 ++++++
 1 file changed, 6 insertions(+)
Documentation/pretty-formats.txt +0 -0
index a4b6f49186..547a552463 100644

Documentation/pretty-formats.txt placeholders, its output is not affected by other options like · line 90

Quoted 8 lines
Documentation/pretty-formats.txt +5 -0
@@ -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.

Quoted 3 lines
Documentation/pretty-formats.txt +0 -0
 * 'raw'
 +
 The 'raw' format shows the entire commit exactly as
#3 lore raw
Quoted 4 lines · Junio C Hamano

Documentation/pretty-formats.txt placeholders, its output is not affected by other options like · line 90

Quoted 3 lines
Documentation/pretty-formats.txt +3 -0
+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.
Quoted 8 lines

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.

#4 lore raw
Quoted 14 lines · Emma Brooks
Quoted 4 lines · Junio C Hamano

Documentation/pretty-formats.txt placeholders, its output is not affected by other options like · line 90

Quoted 3 lines
Documentation/pretty-formats.txt +3 -0
+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.
Quoted 8 lines

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.

Quoted 5 lines

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" ;-)