| Message ID | 20200416041658.85100-1-me@pluvano.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Documentation: explain "mboxrd" pretty format | expand |
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.
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
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.
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" ;-)
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
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(+)