meaning of --8<--

meaning of --8<--

[Markus Heidelberg]

Hi,

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?

Markus

Re: meaning of --8<--

[Peter Harris]

On Sun, Jan 18, 2009 at 10:56 AM, 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?

Common convention, meaning 'cut here'.

Perforated line ------
Scissors 8<

Also used in print (although usually with picture of scissors instead
of the ASCII-art).

Peter Harris

Re: meaning of --8<--

[Samuel Tardieu]

>>>>> "Peter" == Peter Harris <git@peter.is-a-geek.org> writes:

Peter>  Scissors 8<

One can also use the Unicode character 0x2702: ✂ 

  Sam
-- 
Samuel Tardieu -- sam@rfc1149.net -- http://www.rfc1149.net/

Re: meaning of --8<--

[Jay Soffian]

On Sun, Jan 18, 2009 at 10:56 AM, Markus Heidelberg
<markus.heidelberg@web.de> wrote:
> Hi,
>
> I've seen lines like "--8<--" several times on this list, but have no
> clue what it is about.

It is supposed to represent a pair of scissors. Sometimes it is the
other direction: >8. And I've seen folks botch it as: <8 or 8>. This
list is the first (and maybe only?) place I've seen it. Typically you
might see:

--snip--

or

--cut--

> But is this a common convention or git specific and handled by git-am?

Seems to be a convention of this list, and git-am does nothing with it afaik.

j.

Re: meaning of --8<--

[Jeff King]

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