[PATCH] docs/git-mailinfo: Mention the manual separator (---)

[PATCH] docs/git-mailinfo: Mention the manual separator (---)

[W. Trevor King]

And explain how it interacts with the scissors setting.

Signed-off-by: W. Trevor King <wking@tremily.us>
---
The three-dash limit comes from f0658cf2 (restrict the patch
filtering, 2007-03-12), but I couldn't find any associated
documentation.  Since the effect is so similar to the scissors line, I
thought about adding the information to the --scissors entry.  The
manual separator is really independent from the scissors though, so I
settled on explaining both separators in the DESCRIPTION.

This patch is against 'maint'.

 Documentation/git-mailinfo.txt | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt
index 164a3c6..6c6c527 100644
--- a/Documentation/git-mailinfo.txt
+++ b/Documentation/git-mailinfo.txt
@@ -21,6 +21,29 @@ written out to the standard output to be used by 'git am'
 to create a commit.  It is usually not necessary to use this
 command directly.  See linkgit:git-am[1] instead.
 
+The commit message extracted from the e-mail depends on the scissors
+setting (see '--[no-]scissors' in the OPTIONS section).  Besides the
+scissors option (which discards content before the scissors), you can
+also use '---' as a separator (which discards content after the
+separator).  For example, without scissors you can have a body like
+this:
+
+------------
+Your commit message.
+---
+Comments that aren't part of the commit message.
+------------
+
+With scissors, you can have a body like this:
+
+------------
+Comments that aren't part of the commit message.
+--->8---
+Your commit message.
+---
+More comments that aren't part of the commit message.
+------------
+
 
 OPTIONS
 -------
-- 
2.1.0.60.g85f0837

Re: [PATCH] docs/git-mailinfo: Mention the manual separator (---)

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> And explain how it interacts with the scissors setting.
>
> Signed-off-by: W. Trevor King <wking@tremily.us>
> ---
> The three-dash limit comes from f0658cf2 (restrict the patch
> filtering, 2007-03-12), but I couldn't find any associated
> documentation.  Since the effect is so similar to the scissors line, I
> thought about adding the information to the --scissors entry.  The
> manual separator is really independent from the scissors though, so I
> settled on explaining both separators in the DESCRIPTION.
>
> This patch is against 'maint'.
>
>  Documentation/git-mailinfo.txt | 23 +++++++++++++++++++++++
>  1 file changed, 23 insertions(+)
>
> diff --git a/Documentation/git-mailinfo.txt b/Documentation/git-mailinfo.txt
> index 164a3c6..6c6c527 100644
> --- a/Documentation/git-mailinfo.txt
> +++ b/Documentation/git-mailinfo.txt
> @@ -21,6 +21,29 @@ written out to the standard output to be used by 'git am'
>  to create a commit.  It is usually not necessary to use this
>  command directly.  See linkgit:git-am[1] instead.
>  
> +The commit message extracted from the e-mail depends on the scissors
> +setting (see '--[no-]scissors' in the OPTIONS section). ...

It encourages a wrong way to look at it to phrase it like this.

The scissors marker is not about commit log message alone, as you
can have in-body headers like From: and Subject: to override them
after the marker, and also in-body headers before the scissors are
ignored (it is not even "We read From: from the part before the
scissors but then let it be overriden with another From: after the
scissors" ).  The right way to look at it is this: "The scissors
line will cause everything before it discarded and Git pretends as
if the body of the message begins after it".

If we are extending the documentation on "---", it should also
mention the caveats, namely, it is encouraged to indent the extra
message by a SP or something to make sure that it is not mistaken as
part of the patch.  I suspect that this omission from this patch
stems from "content after the separator is discarded", which is not
the case.  Content after the separator is fed to "git apply" as a
patch.  "apply" may "discard" non-patch and the end result may be
that the garbage disappears, but that is not the primary reason why
it does not appear in the resulting log message.  If anything, "---"
separates between the log part from patch part.

The second example concentrates too heavily on log message which
makes it a not-very-good addition as-is.

> +Besides the
> +scissors option (which discards content before the scissors), you can
> +also use '---' as a separator (which discards content after the
> +separator).  For example, without scissors you can have a body like
> +this:
> +
> +------------
> +Your commit message.
> +---
> +Comments that aren't part of the commit message.
> +------------
> +
> +With scissors, you can have a body like this:
> +
> +------------
> +Comments that aren't part of the commit message.
> +--->8---
> +Your commit message.
> +---
> +More comments that aren't part of the commit message.
> +------------
> +
>  
>  OPTIONS
>  -------

Re: [PATCH] docs/git-mailinfo: Mention the manual separator (---)

[W. Trevor King]

[-- Attachment #1: Type: text/plain, Size: 875 bytes --]

On Tue, Sep 30, 2014 at 02:12:58PM -0700, Junio C Hamano wrote:
> If we are extending the documentation on "---", …

Ah, I see that the --- are actually mentioned already in the
DISCUSSION section of git-am(1) since 2499857b (git-am documentation:
describe what is taken from where, 2007-03-24).  I expected the docs
to be either in git-mailinfo(1) (since the code added by f0658cf2
(restrict the patch filtering, 2007-03-12) is in mailinfo) or to match
a grep for '---'.  Maybe we should drop this patch in favor of notes
in git-mailinfo(1) and git-format-patch(1) pointing folks at the
DISCUSSION section in git-am(1) and a more easily grepable “three
dashes ('---')" in gi-am(1)?

Cheers,
Trevor

-- 
This email may be signed or encrypted with GnuPG (http://www.gnupg.org).
For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 819 bytes --]

Re: [PATCH] docs/git-mailinfo: Mention the manual separator (---)

[Junio C Hamano]

"W. Trevor King" <wking@tremily.us> writes:

> ...  Maybe we should drop this patch in favor of notes
> in git-mailinfo(1) and git-format-patch(1) pointing folks at the
> DISCUSSION section in git-am(1) and a more easily grepable “three
> dashes ('---')" in gi-am(1)?

I am all for dropping new changes and expecially duplicates ;-)

Because I would be a bad judge for suggesting the place that a new
reader likely expects to find relevant information, as I am not a
new reader who does not know where to start looking, I'll let others
figure out where the best places to add enhancements to are.

Thanks.