Documentation: explain "mboxrd" pretty format
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
@@ -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
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
Signed-off-by Emma Brooks <[email protected]>
Documentation/pretty-formats.txt placeholders, its output is not affected by other options like · line 91
Quoted 11 lines
+++
b/Documentation/pretty-formats.txtDocumentation/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.
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.Signed-off-by Emma Brooks <[email protected]>--- Documentation/pretty-formats.txt | 6 ++++++ 1 file changed, 6 insertions(+)Documentation/pretty-formats.txt +0
-0
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
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.
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" ;-)