Re: meaning of --8<--

[Jeff King <peff@peff.net>]

On Sun, Jan 18, 2009 at 04:56:37PM +0100, Markus Heidelberg wrote:

> I've seen lines like "--8<--" several times on this list, but have no
> clue what it is about. OK, seems like it's used to insert diffs in the
> middle of a mail message.
> But is this a common convention or git specific and handled by git-am?
> Is it documented anywhere?

As others have explained, it is supposed to be scissors, and it is not
handled by git-am. But the real point of it is to help the person
applying (e.g., Junio) manually separate cover letter from the commit
message. So one way of sending cover material is putting it after the
"---" and before the diff:

  Subject: [PATCH] first line of commit message

  more commit message
  ---
  Here is cover letter material that doesn't go in the commit message.
  It is stripped automatically by git-am.

  diff --git ...

but that is often unnatural to read, because the cover letter material
often introduces the commit, especially when you are replying in the
middle of a thread. So then you end up with:

  Subject: Re: whatever thread you're in

  Somebody else said:
  > blah blah blah

  I disagree. You should do it like this instead:

  -- >8 --
  first line of commit message

  more commit message
  ---

  diff --git ...

git-am will put everything down to the "---" into the commit message,
but it is simple enough to amend away everything else.

So in that sense, it doesn't really matter _what_ the separator is, but
it should be visibly obvious to a human so that they can fix up the
commit message. The only exception is that it should _not_ be "---",
because that is treated specially by git-am.

-Peff