Re: [PATCH] docs/git-mailinfo: Mention the manual separator (---)
"W. Trevor King" <wking@tremily.us> writes:
Show 26 quoted lines
> 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.
Show 25 quoted lines
> +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
> -------
W. Trevor King