[PATCH] remove doubled words, e.g., s/to to/to/, and fix related typos

[PATCH] remove doubled words, e.g., s/to to/to/, and fix related typos

[Jim Meyering]

I found that some doubled words had snuck back into projects from
which I'd already removed them, so now there's a "syntax-check" makefile
rule in gnulib to help prevent recurrence.  Running the command below
spotted a few in git, too:

This patch is relative to "next".

>From d21d6f61bbeeba4a754cdcded66ca86a709695ee Mon Sep 17 00:00:00 2001
From: Jim Meyering <meyering@redhat.com>
Date: Wed, 13 Apr 2011 17:34:44 +0200
Subject: [PATCH] remove doubled words, e.g., s/to to/to/, and fix related
 typos

Run this command to identify suspects:
git ls-files | xargs perl -0777 -n \
  -e 'while (/\b(then?|[iao]n|i[fst]|but|f?or|at|and|[dt])\s+\1\b/gims)' \
  -e '{$n=($` =~ tr/\n/\n/ + 1); ($v=$&)=~s/\n/\\n/g;' \
  -e 'print "$ARGV:$n:$v\n"}'
* Documentation/SubmittingPatches: Remove doubled "to".
* Documentation/git-fetch.txt: Remove doubled "or".
* Documentation/git-pack-objects.txt: Remove doubled "it".
* compat/mingw.c: Likewise.
* compat/nedmalloc/malloc.c.h: Change "an an" to "as an".
Remove doubled "is" and "or".
* gitweb/README: Change "Is is" to "This is".
* sha1_file.c: Remove doubled "at" in comment.
* vcs-svn/trp.txt: Remove doubled "if".

Signed-off-by: Jim Meyering <meyering@redhat.com>
---
 Documentation/SubmittingPatches    |    3 +--
 Documentation/git-fetch.txt        |    2 +-
 Documentation/git-pack-objects.txt |    2 +-
 compat/mingw.c                     |    2 +-
 compat/nedmalloc/malloc.c.h        |   10 ++++------
 gitweb/README                      |    2 +-
 sha1_file.c                        |    2 +-
 vcs-svn/trp.txt                    |    2 +-
 8 files changed, 11 insertions(+), 14 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index c3b0816..c6a5032 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -276,7 +276,7 @@ don't hide your real name.

 If you like, you can put extra tags at the end:

-1. "Reported-by:" is used to to credit someone who found the bug that
+1. "Reported-by:" is used to credit someone who found the bug that
    the patch attempts to fix.
 2. "Acked-by:" says that the person who is more familiar with the area
    the patch attempts to modify liked the patch.
@@ -608,4 +608,3 @@ following commands:
 Just make sure to disable line wrapping in the email client (GMail web
 interface will line wrap no matter what, so you need to use a real
 IMAP client).
-
diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt
index 67d2214..60ac8d2 100644
--- a/Documentation/git-fetch.txt
+++ b/Documentation/git-fetch.txt
@@ -34,7 +34,7 @@ pointed by remote tags that it does not yet have, then fetch
 those missing tags.  If the other end has tags that point at
 branches you are not interested in, you will not get them.

-'git fetch' can fetch from either a single named repository, or
+'git fetch' can fetch from either a single named repository,
 or from several repositories at once if <group> is given and
 there is a remotes.<group> entry in the configuration file.
 (See linkgit:git-config[1]).
diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index 08c89d2..20c8551 100644
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -115,7 +115,7 @@ base-name::

 --honor-pack-keep::
 	This flag causes an object already in a local pack that
-	has a .keep file to be ignored, even if it it would have
+	has a .keep file to be ignored, even if it would have
 	otherwise been packed.

 --incremental::
diff --git a/compat/mingw.c b/compat/mingw.c
index 878b1de..4423961 100644
--- a/compat/mingw.c
+++ b/compat/mingw.c
@@ -1130,7 +1130,7 @@ char **make_augmented_environ(const char *const *vars)

 /*
  * Note, this isn't a complete replacement for getaddrinfo. It assumes
- * that service contains a numerical port, or that it it is null. It
+ * that service contains a numerical port, or that it is null. It
  * does a simple search using gethostbyname, and returns one IPv4 host
  * if one was found.
  */
diff --git a/compat/nedmalloc/malloc.c.h b/compat/nedmalloc/malloc.c.h
index 87260d2..ff7c2c4 100644
--- a/compat/nedmalloc/malloc.c.h
+++ b/compat/nedmalloc/malloc.c.h
@@ -100,7 +100,7 @@

        If you don't like either of these options, you can define
        CORRUPTION_ERROR_ACTION and USAGE_ERROR_ACTION to do anything
-       else. And if if you are sure that your program using malloc has
+       else. And if you are sure that your program using malloc has
        no errors or vulnerabilities, you can define INSECURE to 1,
        which might (or might not) provide a small performance improvement.

@@ -2279,12 +2279,12 @@ nextchunk-> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   of the same size are arranged in a circularly-linked list, with only
   the oldest chunk (the next to be used, in our FIFO ordering)
   actually in the tree.  (Tree members are distinguished by a non-null
-  parent pointer.)  If a chunk with the same size an an existing node
+  parent pointer.)  If a chunk with the same size as an existing node
   is inserted, it is linked off the existing node using pointers that
   work in the same way as fd/bk pointers of small chunks.

   Each tree contains a power of 2 sized range of chunk sizes (the
-  smallest is 0x100 <= x < 0x180), which is is divided in half at each
+  smallest is 0x100 <= x < 0x180), which is divided in half at each
   tree level, with the chunks in the smaller half of the range (0x100
   <= x < 0x140 for the top nose) in the left subtree and the larger
   half (0x140 <= x < 0x180) in the right subtree.  This is, of course,
@@ -3943,7 +3943,7 @@ static void* sys_alloc(mstate m, size_t nb) {
     least-preferred order):
     1. A call to MORECORE that can normally contiguously extend memory.
        (disabled if not MORECORE_CONTIGUOUS or not HAVE_MORECORE or
-       or main space is mmapped or a previous contiguous call failed)
+       main space is mmapped or a previous contiguous call failed)
     2. A call to MMAP new space (disabled if not HAVE_MMAP).
        Note that under the default settings, if MORECORE is unable to
        fulfill a request, and HAVE_MMAP is true, then mmap is
@@ -5748,5 +5748,3 @@ History:
 	 structure of old version,  but most details differ.)

 */
-
-
diff --git a/gitweb/README b/gitweb/README
index 4a67393..a92bde7 100644
--- a/gitweb/README
+++ b/gitweb/README
@@ -29,7 +29,7 @@ You can specify the following configuration variables when building GIT:
    The filesystem traversing limit for getting the project list; the number
    is taken as depth relative to the projectroot.  It is used when
    GITWEB_LIST is a directory (or is not set; then project root is used).
-   Is is meant to speed up project listing on large work trees by limiting
+   This is meant to speed up project listing on large work trees by limiting
    search depth.  [Default: 2007]
  * GITWEB_LIST
    Points to a directory to scan for projects (defaults to project root
diff --git a/sha1_file.c b/sha1_file.c
index df0edba..889fe71 100644
--- a/sha1_file.c
+++ b/sha1_file.c
@@ -1534,7 +1534,7 @@ static int unpack_object_header(struct packed_git *p,
 	enum object_type type;

 	/* use_pack() assures us we have [base, base + 20) available
-	 * as a range that we can look at at.  (Its actually the hash
+	 * as a range that we can look at.  (Its actually the hash
 	 * size that is assured.)  With our object header encoding
 	 * the maximum deflated object size is 2^137, which is just
 	 * insane, so we know won't exceed what we have been given.
diff --git a/vcs-svn/trp.txt b/vcs-svn/trp.txt
index 5ca6b42..177ebca 100644
--- a/vcs-svn/trp.txt
+++ b/vcs-svn/trp.txt
@@ -96,7 +96,7 @@ node_type *foo_search(struct trp_root \*treap, node_type \*key)::

 node_type *foo_nsearch(struct trp_root \*treap, node_type \*key)::

-	Like `foo_search`, but if if the key is missing return what
+	Like `foo_search`, but if the key is missing return what
 	would be key's successor, were key in treap (NULL if no
 	successor).

--
1.7.5.rc1.228.g86d60b

Re: [PATCH] remove doubled words, e.g., s/to to/to/, and fix related typos

[Drew Northup]

On Wed, 2011-04-13 at 17:39 +0200, Jim Meyering wrote:
> I found that some doubled words had snuck back into projects from
> which I'd already removed them, so now there's a "syntax-check" makefile
> rule in gnulib to help prevent recurrence.  Running the command below
> spotted a few in git, too:
> 
> This patch is relative to "next".

Jim,
Try putting the output of git format-patch into your drafts folder, then
open that draft in your mail client. The output of format-patch isn't
meant to be pasted directly into a mail message.

> 
> >From d21d6f61bbeeba4a754cdcded66ca86a709695ee Mon Sep 17 00:00:00 2001
> From: Jim Meyering <meyering@redhat.com>

<rest of submission removed>

The above tells me that you just dumped the output of format-patch into
your mail client. There is a full tutorial in
Documentation/SubmittingPatches in git.git.

-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: [PATCH] remove doubled words, e.g., s/to to/to/, and fix related typos

[Junio C Hamano]

Jim Meyering <jim@meyering.net> writes:

> I found that some doubled words had snuck back into projects from
> which I'd already removed them, so now there's a "syntax-check" makefile
> rule in gnulib to help prevent recurrence.

Thanks.

Re: [PATCH] remove doubled words, e.g., s/to to/to/, and fix related typos

[Jim Meyering]

Drew Northup wrote:
> On Wed, 2011-04-13 at 17:39 +0200, Jim Meyering wrote:
>> I found that some doubled words had snuck back into projects from
>> which I'd already removed them, so now there's a "syntax-check" makefile
>> rule in gnulib to help prevent recurrence.  Running the command below
>> spotted a few in git, too:
>>
>> This patch is relative to "next".
>
> Jim,
> Try putting the output of git format-patch into your drafts folder, then
> open that draft in your mail client. The output of format-patch isn't
> meant to be pasted directly into a mail message.

I hope I haven't caused Junio or anyone else undue trouble.
I know well how format-patch output can be used, but in the vast
majority of patch-including messages I send, I include format-patch
output mainly as an FYI, *following* commentary that does not
belong in the log, so it's ok there -- desirable, even.

I find it slightly backwards to have to put non-log (i.e, intro
commentary) *after* the real log, and that's why I've developed
this habit.

I'll try to remember to do it the other way when the
recipient is more likely to apply the patch.

[PATCH/RFC] Documentation/format-patch: summarize patch-sending workflow

[Jonathan Nieder]

Hi Jim,

Jim Meyering wrote:

> I hope I haven't caused Junio or anyone else undue trouble.
> I know well how format-patch output can be used, but in the vast
> majority of patch-including messages I send, I include format-patch
> output mainly as an FYI, *following* commentary that does not
> belong in the log, so it's ok there -- desirable, even.

Sure, that's true.  The main problem with including a patch in mbox
format inline is that the "From " line tends to get corrupted.  How
about something like patch?

-- 8< --
Subject: Documentation/format-patch: summarize patch-sending workflow

Add a DISCUSSION section to encourage people to send patches in a
form that can be applied by "git am" automatically.  There are two
such forms:

 1. The default form in which most metadata goes in the mail header
    and the message body starts with the patch description;

 2. The snipsnip form in which a message starts with pertinent
    discussion and ends with a patch after a "scissors" mark.

While at it, include a pointer to Documentation/SubmittingPatches
for MUA-specific hints.

Inspired-by: Jim Meyering <jim@meyering.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/git-format-patch.txt |   48 +++++++++++++++++++++++++++++++++++-
 1 files changed, 47 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index a5525e9..5118fdb 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -274,9 +274,55 @@ as e-mailable patches:
 $ git format-patch -3
 ------------
 
+DISCUSSION
+----------
+The patch produced by 'git format-patch' is in UNIX mailbox format,
+like so:
+
+------------
+From f97e66080296c741200eacf1eaeb73f05b19e140 Mon Sep 17 00:00:00 2001
+From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= <avarab@gmail.com>
+Date: Sun, 10 Apr 2011 19:37:01 +0000
+Subject: [PATCH] Makefile: extract Q_() source strings as ngettext()
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+Content-Transfer-Encoding: 8bit
+
+The patch adding the Q_() wrapper function around ngettext[1] didn't
+contain a corresponding update to the "pot" target in the Makefile. As
+...
+------------
+
+Typically it will be placed in a MUA's drafts folder, edited to add
+timely commentary that should not go in the changelog after the three
+dashes, and then sent as a message whose body starts with "The patch
+adding the Q_() wrapper function ...".  On the receiving end, readers
+can save interesting patches in a UNIX mailbox and apply them with
+linkgit:git-am[1].
+
+'git am --scissors' accepts an alternative format with the patch
+inline in the message:
+
+------------
+...
+> So we should do such-and-such.
+
+Makes sense to me.  How about this patch?
+
+-- 8< --
+From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
+Subject: Makefile: extract Q_() source strings as ngettext()
+
+The patch adding the Q_() wrapper function around ngettext[1] didn't
+....
+------------
+
+See linkgit:git-am[1] for details.
+
 SEE ALSO
 --------
-linkgit:git-am[1], linkgit:git-send-email[1]
+linkgit:git-am[1], linkgit:git-send-email[1], linkgit:git-imap-send[1],
+Documentation/SubmittingPatches
 
 GIT
 ---
-- 
1.7.5.rc0

Re: [PATCH] remove doubled words, e.g., s/to to/to/, and fix related typos

[Jakub Narebski]

Jim Meyering <jim@meyering.net> writes:
> Drew Northup wrote:
>> On Wed, 2011-04-13 at 17:39 +0200, Jim Meyering wrote:

>>> I found that some doubled words had snuck back into projects from
>>> which I'd already removed them, so now there's a "syntax-check" makefile
>>> rule in gnulib to help prevent recurrence.  Running the command below
>>> spotted a few in git, too:
>>>
>>> This patch is relative to "next".
>>
>> Jim,
>> Try putting the output of git format-patch into your drafts folder, then
>> open that draft in your mail client. The output of format-patch isn't
>> meant to be pasted directly into a mail message.
> 
> I hope I haven't caused Junio or anyone else undue trouble.
> I know well how format-patch output can be used, but in the vast
> majority of patch-including messages I send, I include format-patch
> output mainly as an FYI, *following* commentary that does not
> belong in the log, so it's ok there -- desirable, even.
> 
> I find it slightly backwards to have to put non-log (i.e, intro
> commentary) *after* the real log, and that's why I've developed
> this habit.
> 
> I'll try to remember to do it the other way when the
> recipient is more likely to apply the patch.

You can put patch _after_ commentary, but if you do it this way you
should include "scissors" line to make it possible to extract commit
part automatically by "git am --scissors", and remove unnecessary
headers.

In other words you had:

> From d21d6f61bbeeba4a754cdcded66ca86a709695ee Mon Sep 17 00:00:00 2001
> From: Jim Meyering <meyering@redhat.com>
> Date: Wed, 13 Apr 2011 17:34:44 +0200
> Subject: [PATCH] remove doubled words, e.g., s/to to/to/, and fix related
>  typos
> 
> Run this command to identify suspects:

and you should have

  -- >8 --
  Run this command to identify suspects:

or in case author is different from email from

  -- >8 --
  From: Jim Meyering <meyering@redhat.com>

  Run this command to identify suspects:

HTH
-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: [PATCH/RFC] Documentation/format-patch: summarize patch-sending workflow

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> + ...
> +'git am --scissors' accepts an alternative format with the patch
> +inline in the message:
> +
> +------------
> +...
> +> So we should do such-and-such.
> +
> +Makes sense to me.  How about this patch?
> +
> +-- 8< --
> +From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
> +Subject: Makefile: extract Q_() source strings as ngettext()
> +
> +The patch adding the Q_() wrapper function around ngettext[1] didn't
> +....
> +------------

It still is preferred to remove the magic "From xxxx Mon Sep 17 00:00:00
2001" we placed to help somebody who is inclined to write an /etc/magic
entry to detect files of format-patch output type if you use the scissors
format.

One thing that we probably would want to clarify is use of the "From:" and
the "Subject:" fields after the scissors in such a context.

"How about this patch?" is most likely to be written by the same person as
the message is coming from, so I think you would rarely need a "From:"
after the scissors.  On the other hand, in such a message, you would come
up with a potential solution to a problem raised in a discussion, and the
original subject would likely to be about a description of the problem or
a request for help, while the patch title would be about the solution, so
it is very likely that you would want to have a "Subject:" line after the
scissors.

Scissors can run in either direction; I am right handed and tend to write
them as "-- >8 --", but your example is for a left handed person.  Either
is fine.

Other than that, looks good to me.

[PATCH v2] Documentation: summarize how format-patch output is consumed

[Jonathan Nieder]

Add a DISCUSSION section to encourage people to send patches in a
form that can be applied by "git am" automatically.  There are two
such forms:

 1. The default form in which most metadata goes in the mail header
    and the message body starts with the patch description;

 2. The snipsnip form in which a message starts with pertinent
    discussion and ends with a patch after a "scissors" mark.

Use an example requiring QP encoding in the "Subject:" field intended
for the mailer, to give the reader a chance to reflect on that (rather
than being startled later).  By contrast, in-body "From:" and
"Subject:" lines should be human-readable and not QP encoded.

A patch following "How about this patch?" is most likely to be written
by the same person as the message is coming from, so you would rarely
need a "From:" after the scissors.  On the other hand, such a message
typically presents a potential solution to a problem raised in
discussion and the original subject is likely to be a description of
the problem or a request for help while the patch title is about the
solution, so it is very likely that you would want a "Subject:" line
after the scissors.  It would be nice to clarify use of the "From:",
"Date:", and "Subject:" fields after the scissors in general, but this
patch avoids the topic in hope of leading the reader to look to
git-am(1) for a detailed discussion.

While at it, include a pointer to Documentation/SubmittingPatches
for MUA-specific hints.

Inspired-by: Jim Meyering <jim@meyering.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Improved-by: Junio C Hamano <gitster@pobox.com>
---
Junio C Hamano wrote:

> It still is preferred to remove the magic "From xxxx Mon Sep 17 00:00:00
> 2001" we placed to help somebody who is inclined to write an /etc/magic
> entry to detect files of format-patch output type if you use the scissors
> format.
[and many useful suggestions]

Thanks.  Changes since v1:

 - no more inline "From:" field
 - different patch to demonstrate qp-encoding in "Subject:" instead
 - use right-handed scissors

I didn't find a way to sneak in a comment about "file" magic; that can
come another day.

 Documentation/git-format-patch.txt |   50 +++++++++++++++++++++++++++++++++++-
 1 files changed, 49 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index a5525e9..875ea9b 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -274,9 +274,57 @@ as e-mailable patches:
 $ git format-patch -3
 ------------
 
+DISCUSSION
+----------
+The patch produced by 'git format-patch' is in UNIX mailbox format,
+like so:
+
+------------
+From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
+From: Tony Luck <tony.luck@intel.com>
+Date: Tue, 13 Jul 2010 11:42:54 -0700
+Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
+ =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+Content-Transfer-Encoding: 8bit
+
+arch/arm config files were slimmed down using a python script
+(See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
+
+Do the same for ia64 so we can have sleek & trim looking
+...
+------------
+
+Typically it will be placed in a MUA's drafts folder, edited to add
+timely commentary that should not go in the changelog after the three
+dashes, and then sent as a message whose body starts with "arch/arm
+config files were".  On the receiving end, readers can save
+interesting patches in a UNIX mailbox and apply them with
+linkgit:git-am[1].
+
+'git am --scissors' accepts an alternative format with the patch
+inline in the message:
+
+------------
+...
+> So we should do such-and-such.
+
+Makes sense to me.  How about this patch?
+
+-- >8 --
+Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
+
+arch/arm config files were slimmed down using a python script
+...
+------------
+
+See linkgit:git-am[1] for details.
+
 SEE ALSO
 --------
-linkgit:git-am[1], linkgit:git-send-email[1]
+linkgit:git-am[1], linkgit:git-send-email[1], linkgit:git-imap-send[1],
+Documentation/SubmittingPatches
 
 GIT
 ---
-- 
1.7.5.rc0

Re: [PATCH v2] Documentation: summarize how format-patch output is consumed

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> It would be nice to clarify use of the "From:",
> "Date:", and "Subject:" fields after the scissors in general, but this
> patch avoids the topic in hope of leading the reader to look to
> git-am(1) for a detailed discussion.

That is going backwards.  The new discussion section is to help people who
send e-mails using the output of this command, and the information you are
leaving out is more useful to these people to decide what to cut and what
to keep.  The users of "am" do not have make the choice to begin with.

> I didn't find a way to sneak in a comment about "file" magic; that can
> come another day.

Heh, you could have done something like:

> +DISCUSSION
> +----------
> +The patch produced by 'git format-patch' is in UNIX mailbox format,
> +like so:

    -like so:
    +with a fixed "magic" datestamp to help people recognize that such a file
    +is an output from format-patch and not a real mailbox, like so:

if you really wanted to ;-).

> +Typically it will be placed in a MUA's drafts folder, edited to add
> +timely commentary that should not go in the changelog after the three
> +dashes, and then sent as a message whose body starts with "arch/arm
> +config files were".  On the receiving end, readers can save
> +interesting patches in a UNIX mailbox and apply them with
> +linkgit:git-am[1].

Good.  I would suggest rephrasing the next paragraph, though.

> +'git am --scissors' accepts an alternative format with the patch
> +inline in the message:

-'git am --scissors' accepts an alternative format with the patch
-inline in the message:
+When sending a patch as part of an ongoing discussion, the patch generated
+by 'git format-patch' can be to take advantage of `git am --scissors`
+feature.  After writing your response to the discussion, write a line that
+consists solely of "-- >8 --" (scissors), append the patch, and remove
+unnecessary header fields, like this:

> +------------
> +...
> +> So we should do such-and-such.
> +
> +Makes sense to me.  How about this patch?
> +
> +-- >8 --
> +Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
> +
> +arch/arm config files were slimmed down using a python script
> +...
> +------------

+Note that when used this way, most often you are sending your own patch,
+so you should omit From: and Date: lines from the patch file, together
+with the "From $SHA-1 $magic_timestamp" marker.  Also your patch title
+is likely to be different from the subject of the discussion you are
+sending this response to, so it is likely that you would want to keep the
+Subject: line, like the example above.
+

> +See linkgit:git-am[1] for details.
> +

> -linkgit:git-am[1], linkgit:git-send-email[1]
> +linkgit:git-am[1], linkgit:git-send-email[1], linkgit:git-imap-send[1],
> +Documentation/SubmittingPatches

Hmm, I suspect this is (1) bad because the end users without the source
may not have access to it, and (2) bad because it may indicate that there
are hints and tricks in SubmittingPatches file, which narrowly targets
developers of this project, but they would also be helpful to the general
audience.  Perhaps some text needs moving from there to here?

[PATCH/RFC v3 0/5] Documentation/format-patch: more hints on submitting patches

[Jonathan Nieder]

Junio C Hamano wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:

>> -linkgit:git-am[1], linkgit:git-send-email[1]
>> +linkgit:git-am[1], linkgit:git-send-email[1], linkgit:git-imap-send[1],
>> +Documentation/SubmittingPatches
>
> Hmm, I suspect this is (1) bad because the end users without the source
> may not have access to it, and (2) bad because it may indicate that there
> are hints and tricks in SubmittingPatches file, which narrowly targets
> developers of this project, but they would also be helpful to the general
> audience.  Perhaps some text needs moving from there to here?

Yep, true.  How about this?

Patch 1 explains the "canonical" and "with scissors" formats of mails
with patches.  It's basically the same as before, except with lots of
nice suggestions from Junio incorporated.

Patch 2 explains how new patch submitters can test their tools before
unleashing them on the world.  It should be common sense, but...  The
text is taken from Documentation/SubmittingPatches.

Patch 3 is rough; it exposes the Thunderbird MUA-specific hints.  Help
making it accurate and consistent with git-imap-send(1) would be very
much appreciated

Patch 4 contains KMail hints from SubmittingPatches; help would
appreciated in making sure that's still accurate, too.

Patch 5 contains the famous GMail hints, finally spreading them out
in EXAMPLES sections where they belong.

Maybe this can be a good starting point for future changes.

Jonathan Nieder (5):
  Documentation: describe the format of messages with inline patches
  Documentation: explain how to check for patch corruption
  Documentation: hints for sending patches inline with Thunderbird
  Documentation: publicize KMail hints for sending patches inline
  Documentation: publicize hints for sending patches with GMail

 Documentation/SubmittingPatches    |  207 +++-------------------------------
 Documentation/git-format-patch.txt |  217 ++++++++++++++++++++++++++++++++++++
 Documentation/git-imap-send.txt    |   29 +++++
 Documentation/git-send-email.txt   |   19 +++-
 4 files changed, 277 insertions(+), 195 deletions(-)

[PATCH 1/5] Documentation: describe the format of messages with inline patches

[Jonathan Nieder]

Add a DISCUSSION section to the "git format-patch" manual to encourage
people to send patches in a form that can be applied by "git am"
automatically.  There are two such forms:

 1. The default form in which most metadata goes in the mail header
    and the message body starts with the patch description;

 2. The snipsnip form in which a message starts with pertinent
    discussion and ends with a patch after a "scissors" mark.

The example requires QP encoding in the "Subject:" header intended for
the mailer to give the reader a chance to reflect on that, rather than
being startled by it later.  By contrast, in-body "From:" and
"Subject:" lines should be human-readable and not QP encoded.

Inspired-by: Jim Meyering <jim@meyering.net>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
Improved-by: Junio C Hamano <gitster@pobox.com>
---
 Documentation/git-format-patch.txt |   58 ++++++++++++++++++++++++++++++++++++
 1 files changed, 58 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index a5525e9..a4a9813 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -229,6 +229,64 @@ attachments, and sign off patches with configuration variables.
 ------------
 
 
+DISCUSSION
+----------
+
+The patch produced by 'git format-patch' is in UNIX mailbox format,
+with a fixed "magic" time stamp to indicate that the file is output
+from format-patch rather than a real mailbox, like so:
+
+------------
+From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001
+From: Tony Luck <tony.luck@intel.com>
+Date: Tue, 13 Jul 2010 11:42:54 -0700
+Subject: [PATCH] =?UTF-8?q?[IA64]=20Put=20ia64=20config=20files=20on=20the=20?=
+ =?UTF-8?q?Uwe=20Kleine-K=C3=B6nig=20diet?=
+MIME-Version: 1.0
+Content-Type: text/plain; charset=UTF-8
+Content-Transfer-Encoding: 8bit
+
+arch/arm config files were slimmed down using a python script
+(See commit c2330e286f68f1c408b4aa6515ba49d57f05beae comment)
+
+Do the same for ia64 so we can have sleek & trim looking
+...
+------------
+
+Typically it will be placed in a MUA's drafts folder, edited to add
+timely commentary that should not go in the changelog after the three
+dashes, and then sent as a message whose body starts with "arch/arm
+config files were".  On the receiving end, readers can save
+interesting patches in a UNIX mailbox and apply them with
+linkgit:git-am[1].
+
+When a patch is part of an ongoing discussion, the patch generated by
+'git format-patch' can be tweaked to take advantage of the 'git am
+--scissors' feature.  After your response to the discussion comes a
+line that consists solely of "`-- >8 --`" (scissors and perforation),
+followed by the patch with unnecessary header fields removed:
+
+------------
+...
+> So we should do such-and-such.
+
+Makes sense to me.  How about this patch?
+
+-- >8 --
+Subject: [IA64] Put ia64 config files on the Uwe Kleine-König diet
+
+arch/arm config files were slimmed down using a python script
+...
+------------
+
+When sending a patch this way, most often you are sending your own
+patch, so in addition to the "`From $SHA1 $magic_timestamp`" marker you
+should omit `From:` and `Date:` lines from the patch file.  The patch
+title is likely to be different from the subject of the discussion the
+patch is in response to, so it is likely that you would want to keep
+the Subject: line, like the example above.
+
+
 EXAMPLES
 --------
 
-- 
1.7.5.rc0

[PATCH 2/5] Documentation: explain how to check for patch corruption

[Jonathan Nieder]

SubmittingPatches has some excellent advice about how to check a patch
for corruption before sending it off.  Move it to the format-patch
manual so it can be installed with git's documentation for use by
people not necessarily interested in the git project's practices.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 Documentation/SubmittingPatches    |   58 ++++++++---------------------------
 Documentation/git-format-patch.txt |   46 ++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+), 44 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index c6a5032..20b4101 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -344,50 +344,20 @@ MUA specific hints
 
 Some of patches I receive or pick up from the list share common
 patterns of breakage.  Please make sure your MUA is set up
-properly not to corrupt whitespaces.  Here are two common ones
-I have seen:
-
-* Empty context lines that do not have _any_ whitespace.
-
-* Non empty context lines that have one extra whitespace at the
-  beginning.
-
-One test you could do yourself if your MUA is set up correctly is:
-
-* Send the patch to yourself, exactly the way you would, except
-  To: and Cc: lines, which would not contain the list and
-  maintainer address.
-
-* Save that patch to a file in UNIX mailbox format.  Call it say
-  a.patch.
-
-* Try to apply to the tip of the "master" branch from the
-  git.git public repository:
-
-    $ git fetch http://kernel.org/pub/scm/git/git.git master:test-apply
-    $ git checkout test-apply
-    $ git reset --hard
-    $ git am a.patch
-
-If it does not apply correctly, there can be various reasons.
-
-* Your patch itself does not apply cleanly.  That is _bad_ but
-  does not have much to do with your MUA.  Please rebase the
-  patch appropriately.
-
-* Your MUA corrupted your patch; "am" would complain that
-  the patch does not apply.  Look at .git/rebase-apply/ subdirectory and
-  see what 'patch' file contains and check for the common
-  corruption patterns mentioned above.
-
-* While you are at it, check what are in 'info' and
-  'final-commit' files as well.  If what is in 'final-commit' is
-  not exactly what you would want to see in the commit log
-  message, it is very likely that your maintainer would end up
-  hand editing the log message when he applies your patch.
-  Things like "Hi, this is my first patch.\n", if you really
-  want to put in the patch e-mail, should come after the
-  three-dash line that signals the end of the commit message.
+properly not to corrupt whitespaces.
+
+See the DISCUSSION section of git-format-patch(1) for hints on
+checking your patch by mailing it to yourself and applying with
+git-am(1).
+
+While you are at it, check the resulting commit log message from
+a trial run of applying the patch.  If what is in the resulting
+commit is not exactly what you would want to see, it is very
+likely that your maintainer would end up hand editing the log
+message when he applies your patch.  Things like "Hi, this is my
+first patch.\n", if you really want to put in the patch e-mail,
+should come after the three-dash line that signals the end of the
+commit message.
 
 
 Pine
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index a4a9813..5c60418 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -286,6 +286,52 @@ title is likely to be different from the subject of the discussion the
 patch is in response to, so it is likely that you would want to keep
 the Subject: line, like the example above.
 
+Checking for patch corruption
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Many mailers if not set up properly will corrupt whitespace.  Here are
+two common types of corruption:
+
+* Empty context lines that do not have _any_ whitespace.
+
+* Non-empty context lines that have one extra whitespace at the
+  beginning.
+
+One way to test if your MUA is set up correctly is:
+
+* Send the patch to yourself, exactly the way you would, except
+  with To: and Cc: lines that do not contain the list and
+  maintainer address.
+
+* Save that patch to a file in UNIX mailbox format.  Call it a.patch,
+  say.
+
+* Apply it:
+
+    $ git fetch <project> master:test-apply
+    $ git checkout test-apply
+    $ git reset --hard
+    $ git am a.patch
+
+If it does not apply correctly, there can be various reasons.
+
+* The patch itself does not apply cleanly.  That is _bad_ but
+  does not have much to do with your MUA.  You might want to rebase
+  the patch with linkgit:git-rebase[1] before regenerating it in
+  this case.
+
+* The MUA corrupted your patch; "am" would complain that
+  the patch does not apply.  Look in the .git/rebase-apply/ subdirectory and
+  see what 'patch' file contains and check for the common
+  corruption patterns mentioned above.
+
+* While at it, check the 'info' and 'final-commit' files as well.
+  If what is in 'final-commit' is not exactly what you would want to
+  see in the commit log message, it is very likely that the
+  receiver would end up hand editing the log message when applying
+  your patch.  Things like "Hi, this is my first patch.\n" in the
+  patch e-mail should come after the three-dash line that signals
+  the end of the commit message.
+
 
 EXAMPLES
 --------
-- 
1.7.5.rc0

[PATCH 3/5] Documentation: hints for sending patches inline with Thunderbird

[Jonathan Nieder]

The standard reference for this information is the article
"Plain text e-mail - Thunderbird#Completely_plain_email" at
kb.mozillazine.org, but the hints hidden away in git's
SubmittingPatches file are more complete.  Move them to the
"git format-patch" manual so they can be installed with git and
read by a wide audience.

While at it, make some tweaks:

 - update "Approach #1" so it might work with Thunderbird 3;
 - remove ancient version numbers from the descriptions of both
   approaches so current readers might have more reason to
   complain if they don't work.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
As mentioned in the cover letter, this is rough.  Help making it
accurate and consistent with git-imap-send(1) would be very much
appreciated.

 Documentation/SubmittingPatches    |   81 +----------------------------------
 Documentation/git-format-patch.txt |   83 ++++++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+), 80 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 20b4101..7908119 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -416,86 +416,7 @@ it.
 Thunderbird
 -----------
 
-(A Large Angry SCM)
-
-By default, Thunderbird will both wrap emails as well as flag them as
-being 'format=flowed', both of which will make the resulting email unusable
-by git.
-
-Here are some hints on how to successfully submit patches inline using
-Thunderbird.
-
-There are two different approaches.  One approach is to configure
-Thunderbird to not mangle patches.  The second approach is to use
-an external editor to keep Thunderbird from mangling the patches.
-
-Approach #1 (configuration):
-
-This recipe is current as of Thunderbird 2.0.0.19.  Three steps:
-  1.  Configure your mail server composition as plain text
-      Edit...Account Settings...Composition & Addressing,
-        uncheck 'Compose Messages in HTML'.
-  2.  Configure your general composition window to not wrap
-      Edit..Preferences..Composition, wrap plain text messages at 0
-  3.  Disable the use of format=flowed
-      Edit..Preferences..Advanced..Config Editor.  Search for:
-        mailnews.send_plaintext_flowed
-      toggle it to make sure it is set to 'false'.
-
-After that is done, you should be able to compose email as you
-otherwise would (cut + paste, git-format-patch | git-imap-send, etc),
-and the patches should not be mangled.
-
-Approach #2 (external editor):
-
-This recipe appears to work with the current [*1*] Thunderbird from Suse.
-
-The following Thunderbird extensions are needed:
-	AboutConfig 0.5
-		http://aboutconfig.mozdev.org/
-	External Editor 0.7.2
-		http://globs.org/articles.php?lng=en&pg=8
-
-1) Prepare the patch as a text file using your method of choice.
-
-2) Before opening a compose window, use Edit->Account Settings to
-uncheck the "Compose messages in HTML format" setting in the
-"Composition & Addressing" panel of the account to be used to send the
-patch. [*2*]
-
-3) In the main Thunderbird window, _before_ you open the compose window
-for the patch, use Tools->about:config to set the following to the
-indicated values:
-	mailnews.send_plaintext_flowed	=> false
-	mailnews.wraplength		=> 0
-
-4) Open a compose window and click the external editor icon.
-
-5) In the external editor window, read in the patch file and exit the
-editor normally.
-
-6) Back in the compose window: Add whatever other text you wish to the
-message, complete the addressing and subject fields, and press send.
-
-7) Optionally, undo the about:config/account settings changes made in
-steps 2 & 3.
-
-
-[Footnotes]
-*1* Version 1.0 (20041207) from the MozillaThunderbird-1.0-5 rpm of Suse
-9.3 professional updates.
-
-*2* It may be possible to do this with about:config and the following
-settings but I haven't tried, yet.
-	mail.html_compose			=> false
-	mail.identity.default.compose_html	=> false
-	mail.identity.id?.compose_html		=> false
-
-(Lukas Sandström)
-
-There is a script in contrib/thunderbird-patch-inline which can help
-you include patches with Thunderbird in an easy way. To use it, do the
-steps above and then use the script as the external editor.
+See the MUA-SPECIFIC HINTS section of git-format-patch(1).
 
 Gnus
 ----
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 5c60418..cbf2b9c 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -332,6 +332,89 @@ If it does not apply correctly, there can be various reasons.
   patch e-mail should come after the three-dash line that signals
   the end of the commit message.
 
+MUA-SPECIFIC HINTS
+------------------
+Here are some hints on how to successfully submit patches inline using
+various mailers.
+
+Thunderbird
+~~~~~~~~~~~
+By default, Thunderbird will both wrap emails as well as flag
+them as being 'format=flowed', both of which will make the
+resulting email unusable by git.
+
+There are two different approaches.  One approach is to configure
+Thunderbird to not mangle patches.  The second approach is to use
+an external editor to keep Thunderbird from mangling the patches.
+
+Approach #1 (configuration)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Three steps:
+
+1. Configure your mail server composition as plain text:
+   Edit...Account Settings...Composition & Addressing,
+   uncheck "Compose Messages in HTML".
+
+2. Configure your general composition window to not wrap.
++
+In Thunderbird 2:
+Edit..Preferences..Composition, wrap plain text messages at 0
++
+In Thunderbird 3:
+Edit..Preferences..Advanced..Config Editor.  Search for
+"mail.wrap_long_lines".
+Toggle it to make sure it is set to `false`.
+
+3. Disable the use of format=flowed:
+Edit..Preferences..Advanced..Config Editor.  Search for
+"mailnews.send_plaintext_flowed".
+Toggle it to make sure it is set to `false`.
+
+After that is done, you should be able to compose email as you
+otherwise would (cut + paste, 'git format-patch' | 'git imap-send', etc),
+and the patches will not be mangled.
+
+Approach #2 (external editor)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following Thunderbird extensions are needed:
+AboutConfig from http://aboutconfig.mozdev.org/ and
+External Editor from http://globs.org/articles.php?lng=en&pg=8
+
+1. Prepare the patch as a text file using your method of choice.
+
+2. Before opening a compose window, use Edit->Account Settings to
+   uncheck the "Compose messages in HTML format" setting in the
+   "Composition & Addressing" panel of the account to be used to
+   send the patch.
+
+3. In the main Thunderbird window, 'before' you open the compose
+   window for the patch, use Tools->about:config to set the
+   following to the indicated values:
++
+----------
+	mailnews.send_plaintext_flowed  => false
+	mailnews.wraplength             => 0
+----------
+
+4. Open a compose window and click the external editor icon.
+
+5. In the external editor window, read in the patch file and exit
+   the editor normally.
+
+Side note: it may be possible to do step 2 with
+about:config and the following settings but no one's tried yet.
+
+----------
+	mail.html_compose                       => false
+	mail.identity.default.compose_html      => false
+	mail.identity.id?.compose_html          => false
+----------
+
+There is a script in contrib/thunderbird-patch-inline which can help
+you include patches with Thunderbird in an easy way. To use it, do the
+steps above and then use the script as the external editor.
+
 
 EXAMPLES
 --------
-- 
1.7.5.rc0

[PATCH 4/5] Documentation: publicize KMail hints for sending patches inline

[Jonathan Nieder]

These hints are in git's private SubmittingPatches document but a
wider audience might be interested.  Move them to the "git
format-patch" manpage.

I'm not sure what gotchas these hints are meant to work around.
They might be completely false.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
A quick search for "how to send patches with KMail" gave me the
"external editor" trick.  Do these instructions work? ;-)

Anyway, this patch reuses the current instructions from
SubmittingPatches as-is.

 Documentation/SubmittingPatches    |   22 ++--------------------
 Documentation/git-format-patch.txt |   16 ++++++++++++++++
 2 files changed, 18 insertions(+), 20 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index 7908119..e9d8c3f 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -413,8 +413,8 @@ that or Gentoo did it.) So you need to set the
 it.
 
 
-Thunderbird
------------
+Thunderbird, KMail
+------------------
 
 See the MUA-SPECIFIC HINTS section of git-format-patch(1).
 
@@ -433,24 +433,6 @@ message in raw form before using '|' to run the pipe can work
 this problem around.
 
 
-KMail
------
-
-This should help you to submit patches inline using KMail.
-
-1) Prepare the patch as a text file.
-
-2) Click on New Mail.
-
-3) Go under "Options" in the Composer window and be sure that
-"Word wrap" is not set.
-
-4) Use Message -> Insert file... and insert the patch.
-
-5) Back in the compose window: add whatever other text you wish to the
-message, complete the addressing and subject fields, and press send.
-
-
 Gmail
 -----
 
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index cbf2b9c..8887375 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -415,6 +415,22 @@ There is a script in contrib/thunderbird-patch-inline which can help
 you include patches with Thunderbird in an easy way. To use it, do the
 steps above and then use the script as the external editor.
 
+KMail
+~~~~~
+This should help you to submit patches inline using KMail.
+
+1. Prepare the patch as a text file.
+
+2. Click on New Mail.
+
+3. Go under "Options" in the Composer window and be sure that
+   "Word wrap" is not set.
+
+4. Use Message -> Insert file... and insert the patch.
+
+5. Back in the compose window: add whatever other text you wish to the
+   message, complete the addressing and subject fields, and press send.
+
 
 EXAMPLES
 --------
-- 
1.7.5.rc0

[PATCH 5/5] Documentation: publicize hints for sending patches with GMail

[Jonathan Nieder]

The hints in SubmittingPatches about stopping GMail from clobbering
patches are widely useful both as examples of "git send-email" and
"git imap-send" usage.

Move the documentation to the appropriate places.

While at it, don't encourage storing passwords in config files.

Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
That's the end of the series.  Thoughts welcome as always.

 Documentation/SubmittingPatches    |   54 +----------------------------------
 Documentation/git-format-patch.txt |   14 +++++++++
 Documentation/git-imap-send.txt    |   29 +++++++++++++++++++
 Documentation/git-send-email.txt   |   19 ++++++++++--
 4 files changed, 61 insertions(+), 55 deletions(-)

diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
index e9d8c3f..938eccf 100644
--- a/Documentation/SubmittingPatches
+++ b/Documentation/SubmittingPatches
@@ -413,8 +413,8 @@ that or Gentoo did it.) So you need to set the
 it.
 
 
-Thunderbird, KMail
-------------------
+Thunderbird, KMail, GMail
+-------------------------
 
 See the MUA-SPECIFIC HINTS section of git-format-patch(1).
 
@@ -431,53 +431,3 @@ characters (most notably in people's names), and also
 whitespaces (fatal in patches).  Running 'C-u g' to display the
 message in raw form before using '|' to run the pipe can work
 this problem around.
-
-
-Gmail
------
-
-GMail does not appear to have any way to turn off line wrapping in the web
-interface, so this will mangle any emails that you send.  You can however
-use "git send-email" and send your patches through the GMail SMTP server, or
-use any IMAP email client to connect to the google IMAP server and forward
-the emails through that.
-
-To use "git send-email" and send your patches through the GMail SMTP server,
-edit ~/.gitconfig to specify your account settings:
-
-[sendemail]
-	smtpencryption = tls
-	smtpserver = smtp.gmail.com
-	smtpuser = user@gmail.com
-	smtppass = p4ssw0rd
-	smtpserverport = 587
-
-Once your commits are ready to be sent to the mailing list, run the
-following commands:
-
-  $ git format-patch --cover-letter -M origin/master -o outgoing/
-  $ edit outgoing/0000-*
-  $ git send-email outgoing/*
-
-To submit using the IMAP interface, first, edit your ~/.gitconfig to specify your
-account settings:
-
-[imap]
-	folder = "[Gmail]/Drafts"
-	host = imaps://imap.gmail.com
-	user = user@gmail.com
-	pass = p4ssw0rd
-	port = 993
-	sslverify = false
-
-You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error
-that the "Folder doesn't exist".
-
-Once your commits are ready to be sent to the mailing list, run the
-following commands:
-
-  $ git format-patch --cover-letter -M --stdout origin/master | git imap-send
-
-Just make sure to disable line wrapping in the email client (GMail web
-interface will line wrap no matter what, so you need to use a real
-IMAP client).
diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 8887375..c44e248 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -337,6 +337,20 @@ MUA-SPECIFIC HINTS
 Here are some hints on how to successfully submit patches inline using
 various mailers.
 
+GMail
+~~~~~
+GMail does not have any way to turn off line wrapping in the web
+interface, so it will mangle any emails that you send.  You can however
+use "git send-email" and send your patches through the GMail SMTP server, or
+use any IMAP email client to connect to the google IMAP server and forward
+the emails through that.
+
+For hints on using 'git send-email' to send your patches through the
+GMail SMTP server, see the EXAMPLE section of linkgit:git-send-email[1].
+
+For hints on submission using the IMAP interface, see the EXAMPLE
+section of linkgit:git-imap-send[1].
+
 Thunderbird
 ~~~~~~~~~~~
 By default, Thunderbird will both wrap emails as well as flag
diff --git a/Documentation/git-imap-send.txt b/Documentation/git-imap-send.txt
index d3013d6..4e09708 100644
--- a/Documentation/git-imap-send.txt
+++ b/Documentation/git-imap-send.txt
@@ -111,6 +111,31 @@ Using direct mode with SSL:
 ..........................
 
 
+EXAMPLE
+-------
+To submit patches using GMail's IMAP interface, first, edit your ~/.gitconfig
+to specify your account settings:
+
+---------
+[imap]
+	folder = "[Gmail]/Drafts"
+	host = imaps://imap.gmail.com
+	user = user@gmail.com
+	port = 993
+	sslverify = false
+---------
+
+You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error
+that the "Folder doesn't exist".
+
+Once the commits are ready to be sent, run the following command:
+
+  $ git format-patch --cover-letter -M --stdout origin/master | git imap-send
+
+Just make sure to disable line wrapping in the email client (GMail's web
+interface will wrap lines no matter what, so you need to use a real
+IMAP client).
+
 CAUTION
 -------
 It is still your responsibility to make sure that the email message
@@ -124,6 +149,10 @@ Thunderbird in particular is known to be problematic.  Thunderbird
 users may wish to visit this web page for more information:
   http://kb.mozillazine.org/Plain_text_e-mail_-_Thunderbird#Completely_plain_email
 
+SEE ALSO
+--------
+linkgit:git-format-patch[1], linkgit:git-send-email[1], mbox(5)
+
 GIT
 ---
 Part of the linkgit:git[1] suite
diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index ee14f74..5a168cf 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -348,10 +348,12 @@ sendemail.confirm::
 	one of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm'
 	in the previous section for the meaning of these values.
 
+EXAMPLE
+-------
 Use gmail as the smtp server
-----------------------------
-
-Add the following section to the config file:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To use 'git send-email' to send your patches through the GMail SMTP server,
+edit ~/.gitconfig to specify your account settings:
 
 	[sendemail]
 		smtpencryption = tls
@@ -359,9 +361,20 @@ Add the following section to the config file:
 		smtpuser = yourname@gmail.com
 		smtpserverport = 587
 
+Once your commits are ready to be sent to the mailing list, run the
+following commands:
+
+	$ git format-patch --cover-letter -M origin/master -o outgoing/
+	$ edit outgoing/0000-*
+	$ git send-email outgoing/*
+
 Note: the following perl modules are required
       Net::SMTP::SSL, MIME::Base64 and Authen::SASL
 
+SEE ALSO
+--------
+linkgit:git-format-patch[1], linkgit:git-imap-send[1], mbox(5)
+
 GIT
 ---
 Part of the linkgit:git[1] suite
-- 
1.7.5.rc0

Re: [PATCH 2/5] Documentation: explain how to check for patch corruption

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> SubmittingPatches has some excellent advice about how to check a patch
> for corruption before sending it off.  Move it to the format-patch
> manual so it can be installed with git's documentation for use by
> people not necessarily interested in the git project's practices.
>
> Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
> ---
>  Documentation/SubmittingPatches    |   58 ++++++++---------------------------
>  Documentation/git-format-patch.txt |   46 ++++++++++++++++++++++++++++
>  2 files changed, 60 insertions(+), 44 deletions(-)
>
> diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches
> index c6a5032..20b4101 100644
> --- a/Documentation/SubmittingPatches
> +++ b/Documentation/SubmittingPatches
> @@ -344,50 +344,20 @@ MUA specific hints
>  
>  Some of patches I receive or pick up from the list share common
>  patterns of breakage.  Please make sure your MUA is set up
> +properly not to corrupt whitespaces.
> +
> +See the DISCUSSION section of git-format-patch(1) for hints on
> +checking your patch by mailing it to yourself and applying with
> +git-am(1).
> +
> +While you are at it, check the resulting commit log message from
> +a trial run of applying the patch.  If what is in the resulting
> +commit is not exactly what you would want to see, it is very
> +likely that your maintainer would end up hand editing the log
> +message when he applies your patch.  Things like "Hi, this is my
> +first patch.\n", if you really want to put in the patch e-mail,
> +should come after the three-dash line that signals the end of the
> +commit message.

Perhaps the last paragraph can also go, as a copy of it now is in git-am(1)?

> diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
> index a4a9813..5c60418 100644
> --- a/Documentation/git-format-patch.txt
> +++ b/Documentation/git-format-patch.txt
> @@ -286,6 +286,52 @@ title is likely to be different from the subject
> +One way to test if your MUA is set up correctly is:
> +
> +* Send the patch to yourself, exactly the way you would, except
> +  with To: and Cc: lines that do not contain the list and
> +  maintainer address.

... "except for removing other people from To: and Cc: lines to avoid
spamming them with your test"?

Re: [PATCH 2/5] Documentation: explain how to check for patch corruption

[Jonathan Nieder]

Junio C Hamano wrote:
> Jonathan Nieder <jrnieder@gmail.com> writes:

>> +++ b/Documentation/SubmittingPatches
[...]
>> +While you are at it, check the resulting commit log message from
>> +a trial run of applying the patch.  If what is in the resulting
[...]
> Perhaps the last paragraph can also go, as a copy of it now is in git-am(1)?

Yes, good idea.  I wanted to keep a reminder to look over the
resulting commit (and especially its log message), but this section is
definitely not the place.

>> +++ b/Documentation/git-format-patch.txt
>> @@ -286,6 +286,52 @@ title is likely to be different from the subject
>> +One way to test if your MUA is set up correctly is:
>> +
>> +* Send the patch to yourself, exactly the way you would, except
>> +  with To: and Cc: lines that do not contain the list and
>> +  maintainer address.
>
> ... "except for removing other people from To: and Cc: lines to avoid
> spamming them with your test"?

Yes, that is much clearer.  If you'd like, I can collect other
corrections and read it over again myself to resend tomorrow.

[PATCH/RFC 6/5] Documentation/format-patch: suggest Toggle Word Wrap add-on for Thunderbird

[Johannes Sixt]

From: Johannes Sixt <j6t@kdbg.org>

Signed-off-by: Johannes Sixt <j6t@kdbg.org>
---
 How about this as 6/5? I used the method described for this submission, so if
 what you got is unusable, you know what to think of the suggestion ;)

 I put this suggestion as approach #1 because I think it is superior to the
 other two (iff it worked).

 -- Hannes

 Documentation/git-format-patch.txt |   18 ++++++++++++++----
 1 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -343,11 +343,21 @@ By default, Thunderbird will both wrap emails as well as flag
 them as being 'format=flowed', both of which will make the
 resulting email unusable by git.
 
-There are two different approaches.  One approach is to configure
-Thunderbird to not mangle patches.  The second approach is to use
+There are three different approaches: use an add-on to turn off line wraps,
+configure Thunderbird to not mangle patches, or use
 an external editor to keep Thunderbird from mangling the patches.
 
-Approach #1 (configuration)
+Approach #1 (add-on)
+^^^^^^^^^^^^^^^^^^^^
+
+Install the Toggle Word Wrap add-on that is available from
+https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/
+It adds a menu entry "Enable Word Wrap" that you can tick off. Now you
+can compose the message as you otherwise do (cut + paste,
+'git format-patch' | 'git imap-send', etc), but you have to insert
+line breaks manually in any additional text that you type.
+
+Approach #2 (configuration)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Three steps:
 
@@ -374,7 +384,7 @@ After that is done, you should be able to compose email as you
 otherwise would (cut + paste, 'git format-patch' | 'git imap-send', etc),
 and the patches will not be mangled.
 
-Approach #2 (external editor)
+Approach #3 (external editor)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The following Thunderbird extensions are needed:

Re: [PATCH/RFC 6/5] Documentation/format-patch: suggest Toggle Word Wrap add-on for Thunderbird

[Junio C Hamano]

Johannes Sixt <j.sixt@viscovery.net> writes:

> From: Johannes Sixt <j6t@kdbg.org>
>
> Signed-off-by: Johannes Sixt <j6t@kdbg.org>
> ---
>  How about this as 6/5? I used the method described for this submission, so if
>  what you got is unusable, you know what to think of the suggestion ;)

It seems to apply fine ;-).

>  I put this suggestion as approach #1 because I think it is superior to the
>  other two (iff it worked).

Care to reword "superior" in a less subjective way (which should be very
easy --- both existing suggestions seem to force plain-text no-wrap on any
and all outgoing mails and to make it cumbersome to flip back and forth,
as opposed to this one that gives a one-click on-demand way to do so only
when you are sending a patch) and put it in the log message?

Re: [PATCH/RFC 6/5] Documentation/format-patch: suggest Toggle Word Wrap add-on for Thunderbird

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 15.04.2011 19:54:
> Johannes Sixt <j.sixt@viscovery.net> writes:
> 
>> From: Johannes Sixt <j6t@kdbg.org>
>>
>> Signed-off-by: Johannes Sixt <j6t@kdbg.org>
>> ---
>>  How about this as 6/5? I used the method described for this submission, so if
>>  what you got is unusable, you know what to think of the suggestion ;)
> 
> It seems to apply fine ;-).
> 
>>  I put this suggestion as approach #1 because I think it is superior to the
>>  other two (iff it worked).
> 
> Care to reword "superior" in a less subjective way (which should be very
> easy --- both existing suggestions seem to force plain-text no-wrap on any
> and all outgoing mails and to make it cumbersome to flip back and forth,
> as opposed to this one that gives a one-click on-demand way to do so only
> when you are sending a patch) and put it in the log message?

Does this add-on toggle "format fl[oa]wed" also? Otherwise you have to
make this is off also.

BTW: "AboutConfig" was great while it was needed, but these days you can
access Thunderbird's about:config from the options.

Michael

Re: [PATCH/RFC 6/5] Documentation/format-patch: suggest Toggle Word Wrap add-on for Thunderbird

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> Junio C Hamano venit, vidit, dixit 15.04.2011 19:54:
>> Johannes Sixt <j.sixt@viscovery.net> writes:
>> 
>>> From: Johannes Sixt <j6t@kdbg.org>
>>>
>>> Signed-off-by: Johannes Sixt <j6t@kdbg.org>
>>> ---
>>>  How about this as 6/5? I used the method described for this submission, so if
>>>  what you got is unusable, you know what to think of the suggestion ;)
>> 
>> It seems to apply fine ;-).
>> 
>>>  I put this suggestion as approach #1 because I think it is superior to the
>>>  other two (iff it worked).
>> 
>> Care to reword "superior" in a less subjective way (which should be very
>> easy --- both existing suggestions seem to force plain-text no-wrap on any
>> and all outgoing mails and to make it cumbersome to flip back and forth,
>> as opposed to this one that gives a one-click on-demand way to do so only
>> when you are sending a patch) and put it in the log message?
> 
> Does this add-on toggle "format fl[oa]wed" also? Otherwise you have to
> make this is off also.
>
> BTW: "AboutConfig" was great while it was needed, but these days you can
> access Thunderbird's about:config from the options.

I have no idea on neither of these two points, as I don't use these GUI
thingies myself.

Re: [PATCH 1/5] Documentation: describe the format of messages with inline patches

[Drew Northup]

On Thu, 2011-04-14 at 21:22 -0500, Jonathan Nieder wrote:
> Add a DISCUSSION section to the "git format-patch" manual to encourage
> people to send patches in a form that can be applied by "git am"
> automatically.  There are two such forms:
> 
>  1. The default form in which most metadata goes in the mail header
>     and the message body starts with the patch description;
...
> +DISCUSSION
> +----------
> +
> +The patch produced by 'git format-patch' is in UNIX mailbox format,
...
> +
> +arch/arm config files were slimmed down using a python script
...
> +Typically it will be placed in a MUA's drafts folder, edited to add
> +timely commentary that should not go in the changelog after the three
> +dashes, and then sent as a message whose body starts with "arch/arm
> +config files were".  On the receiving end, readers can save
> +interesting patches in a UNIX mailbox and apply them with
> +linkgit:git-am[1].

Maybe I'm too picky, but I'd feel more comfortable saying:

...
dashes, and then sent as a message which in our example stars with
"arch/arm config files were..." On the receiving end, readers can save
...


-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59

Re: [PATCH/RFC 6/5] Documentation/format-patch: suggest Toggle Word Wrap add-on for Thunderbird

[Jonathan Nieder]

Michael J Gruber wrote:

> Does this add-on toggle "format fl[oa]wed" also?

Yep, it does.  Great find, Hannes.

> BTW: "AboutConfig" was great while it was needed, but these days you can
> access Thunderbird's about:config from the options.

So to summarize the three approaches (this is not a proposed wording;
I'm just trying to clear things up for myself):

 By default, Thunderbird will send HTML mail, wrap outgoing mail to 72
 characters for plain text mail, and transforms plain text mail to
 match the follow=flowed spec.

 To disable HTML mail, use Edit->Account Settings to uncheck the
 "Compose messages in HTML format" setting in the "Composition &
 Addressing" panel of the account to be used to send the patch.
 You've probably done this already --- many development lists do not
 like HTML mail for ordinary discussion, either.

 To disable wrapping and format=flowed, install the Toggle Word Wrap
 add-on that is available from
 https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/
 It adds a menu entry "Enable Word Wrap" that you can tick off. Now you
 can compose the message as you otherwise do (cut + paste,
 'git format-patch' | 'git imap-send', etc), but you have to insert
 line breaks manually in any additional text that you type.

 That's it.

 If for some reason that add-on doesn't work (maybe you don't like
 add-ons?), use the Config Editor (under Edit->Preferences->Advanced)
 to set

	mailnews.send_plaintext_flowed  => false

 to disable format=flowed and one of the following (?)

	mail.wrap_long_lines => false
	mailnews.wraplength => 0

 to disable line wrapping.

 You might also find the External Editor add-on from
 http://globs.org/articles.php?lng=en&pg=8 useful.
 There is a script in contrib/thunderbird-patch-inline which can be used
 as an external editor to include patches with Thunderbird and populate
 the "To:", "Subject:", and "Cc:" fields.

Re: [PATCH 1/5] Documentation: describe the format of messages with inline patches

[Junio C Hamano]

Drew Northup <drew.northup@maine.edu> writes:

> Maybe I'm too picky, but I'd feel more comfortable saying:
>
> ...
> dashes, and then sent as a message which in our example stars with
> "arch/arm config files were..." On the receiving end, readers can save
> ...

Surely you are ;-) I am tempted to squash the following into it.

Thanks.

 Documentation/git-format-patch.txt |    6 +++---
 1 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index c20e0ed..eebfa5c 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -255,9 +255,9 @@ Do the same for ia64 so we can have sleek & trim looking
 
 Typically it will be placed in a MUA's drafts folder, edited to add
 timely commentary that should not go in the changelog after the three
-dashes, and then sent as a message whose body starts with "arch/arm
-config files were".  On the receiving end, readers can save
-interesting patches in a UNIX mailbox and apply them with
+dashes, and then sent as a message whose body, in our example, starts
+with "arch/arm config files were...".  On the receiving end, readers
+can save interesting patches in a UNIX mailbox and apply them with
 linkgit:git-am[1].
 
 When a patch is part of an ongoing discussion, the patch generated by

Re: [PATCH 4/5] Documentation: publicize KMail hints for sending patches inline

[Michele Ballabio]

On Friday 15 April 2011, Jonathan Nieder wrote:
> I'm not sure what gotchas these hints are meant to work around.
> They might be completely false.

These suggestion are there to warn and help about space/word wrap
mangling, and to send a patch in the mail body (as per SubmittingPatches).

> A quick search for "how to send patches with KMail" gave me the
> "external editor" trick.  Do these instructions work? ;-)

They do work, but maybe they are not so important, since they're
helpful only for the one-time-hack-patch and I-don't-want-to-setup-
git-send-email.

When there are more than 3 or 4 patches to send, 'git send-email'
(plus msmtp, if needed) is more comfortable.

There is however, an helpful hint in http://wiki.winehq.org/GitWine
(never tried it, and I'd tend to prefer 'git send-email' anyway, don't
know if this should be mentioned in git docs):


	Using local KMail folders, you can use the following approach:

git format-patch --stdout --keep-subject origin | formail -s procmail

	Assuming you don't already use procmail to sort your email, you can
	use the following .procmailrc

:0
/home/username/.maildir/

	Now, all you need to do is to set up a new receiving account in
	KMail that collects mail from /home/username/.maildir and filter
	emails coming in on that account to your drafts folder. 

[PATCH 6/5 v2] Documentation/format-patch: suggest Toggle Word Wrap add-on for Thunderbird

[Johannes Sixt]

From: Johannes Sixt <j6t@kdbg.org>

Of the (now) three methods to send unmangled patches using Thunderbird,
this method is listed first because it provides a single-click on-demand
option rather than a permanent change of configuration like the other
two methods.

Signed-off-by: Johannes Sixt <j6t@kdbg.org>
---
Am 4/15/2011 19:54, schrieb Junio C Hamano:
> Care to reword "superior" in a less subjective way

Sure.

Differences to v1: More precise description where the new Option is found.

-- Hannes

 Documentation/git-format-patch.txt |   18 ++++++++++++++----
 1 files changed, 14 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
index 8887375..a979b2a 100644
--- a/Documentation/git-format-patch.txt
+++ b/Documentation/git-format-patch.txt
@@ -343,11 +343,21 @@ By default, Thunderbird will both wrap emails as well as flag
 them as being 'format=flowed', both of which will make the
 resulting email unusable by git.
 
-There are two different approaches.  One approach is to configure
-Thunderbird to not mangle patches.  The second approach is to use
+There are three different approaches: use an add-on to turn off line wraps,
+configure Thunderbird to not mangle patches, or use
 an external editor to keep Thunderbird from mangling the patches.
 
-Approach #1 (configuration)
+Approach #1 (add-on)
+^^^^^^^^^^^^^^^^^^^^
+
+Install the Toggle Word Wrap add-on that is available from
+https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/
+It adds a menu entry "Enable Word Wrap" in the composer's "Options" menu
+that you can tick off. Now you can compose the message as you otherwise do
+(cut + paste, 'git format-patch' | 'git imap-send', etc), but you have to
+insert line breaks manually in any text that you type.
+
+Approach #2 (configuration)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Three steps:
 
@@ -374,7 +384,7 @@ After that is done, you should be able to compose email as you
 otherwise would (cut + paste, 'git format-patch' | 'git imap-send', etc),
 and the patches will not be mangled.
 
-Approach #2 (external editor)
+Approach #3 (external editor)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The following Thunderbird extensions are needed:
-- 
1.7.5.rc1.1127.g94456