Autogenerated HTML docs for v1.7.5.1-169-g505a1

1 files changed, 274 insertions, 1 deletions

diff --git a/git-format-patch.html b/git-format-patch.html
index e1454e25b..8a2725de6 100644
--- a/git-format-patch.html
+++ b/git-format-patch.html
@@ -1138,6 +1138,279 @@ attachments, and sign off patches with configuration variables.</p></div>
         signoff = true</tt></pre>

 </div></div>

 </div>

+<h2 id="_discussion">DISCUSSION</h2>

+<div class="sectionbody">

+<div class="paragraph"><p>The patch produced by <em>git format-patch</em> 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:</p></div>

+<div class="listingblock">

+<div class="content">

+<pre><tt>From 8f72bad1baf19a53459661343e21d6491c3908d3 Mon Sep 17 00:00:00 2001

+From: Tony Luck &lt;tony.luck@intel.com&gt;

+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 &amp; trim looking

+...</tt></pre>

+</div></div>

+<div class="paragraph"><p>Typically it will be placed in a MUA&#8217;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, in our example, starts

+with "arch/arm config files were&#8230;".  On the receiving end, readers

+can save interesting patches in a UNIX mailbox and apply them with

+<a href="git-am.html">git-am(1)</a>.</p></div>

+<div class="paragraph"><p>When a patch is part of an ongoing discussion, the patch generated by

+<em>git format-patch</em> can be tweaked to take advantage of the <em>git am

+--scissors</em> feature.  After your response to the discussion comes a

+line that consists solely of "<tt>-- &gt;8 --</tt>" (scissors and perforation),

+followed by the patch with unnecessary header fields removed:</p></div>

+<div class="listingblock">

+<div class="content">

+<pre><tt>...

+&gt; So we should do such-and-such.

+

+Makes sense to me.  How about this patch?

+

+-- &gt;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

+...</tt></pre>

+</div></div>

+<div class="paragraph"><p>When sending a patch this way, most often you are sending your own

+patch, so in addition to the "<tt>From $SHA1 $magic_timestamp</tt>" marker you

+should omit <tt>From:</tt> and <tt>Date:</tt> 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.</p></div>

+<h3 id="_checking_for_patch_corruption">Checking for patch corruption</h3><div style="clear:left"></div>

+<div class="paragraph"><p>Many mailers if not set up properly will corrupt whitespace.  Here are

+two common types of corruption:</p></div>

+<div class="ulist"><ul>

+<li>

+<p>

+Empty context lines that do not have <em>any</em> whitespace.

+</p>

+</li>

+<li>

+<p>

+Non-empty context lines that have one extra whitespace at the

+  beginning.

+</p>

+</li>

+</ul></div>

+<div class="paragraph"><p>One way to test if your MUA is set up correctly is:</p></div>

+<div class="ulist"><ul>

+<li>

+<p>

+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.

+</p>

+</li>

+<li>

+<p>

+Save that patch to a file in UNIX mailbox format.  Call it a.patch,

+  say.

+</p>

+</li>

+<li>

+<p>

+Apply it:

+</p>

+<div class="literalblock">

+<div class="content">

+<pre><tt>$ git fetch &lt;project&gt; master:test-apply

+$ git checkout test-apply

+$ git reset --hard

+$ git am a.patch</tt></pre>

+</div></div>

+</li>

+</ul></div>

+<div class="paragraph"><p>If it does not apply correctly, there can be various reasons.</p></div>

+<div class="ulist"><ul>

+<li>

+<p>

+The patch itself does not apply cleanly.  That is <em>bad</em> but

+  does not have much to do with your MUA.  You might want to rebase

+  the patch with <a href="git-rebase.html">git-rebase(1)</a> before regenerating it in

+  this case.

+</p>

+</li>

+<li>

+<p>

+The MUA corrupted your patch; "am" would complain that

+  the patch does not apply.  Look in the .git/rebase-apply/ subdirectory and

+  see what <em>patch</em> file contains and check for the common

+  corruption patterns mentioned above.

+</p>

+</li>

+<li>

+<p>

+While at it, check the <em>info</em> and <em>final-commit</em> files as well.

+  If what is in <em>final-commit</em> 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.

+</p>

+</li>

+</ul></div>

+</div>

+<h2 id="_mua_specific_hints">MUA-SPECIFIC HINTS</h2>

+<div class="sectionbody">

+<div class="paragraph"><p>Here are some hints on how to successfully submit patches inline using

+various mailers.</p></div>

+<h3 id="_gmail">GMail</h3><div style="clear:left"></div>

+<div class="paragraph"><p>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.</p></div>

+<div class="paragraph"><p>For hints on using <em>git send-email</em> to send your patches through the

+GMail SMTP server, see the EXAMPLE section of <a href="git-send-email.html">git-send-email(1)</a>.</p></div>

+<div class="paragraph"><p>For hints on submission using the IMAP interface, see the EXAMPLE

+section of <a href="git-imap-send.html">git-imap-send(1)</a>.</p></div>

+<h3 id="_thunderbird">Thunderbird</h3><div style="clear:left"></div>

+<div class="paragraph"><p>By default, Thunderbird will both wrap emails as well as flag

+them as being <em>format=flowed</em>, both of which will make the

+resulting email unusable by git.</p></div>

+<div class="paragraph"><p>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.</p></div>

+<h4 id="_approach_1_add_on">Approach #1 (add-on)</h4>

+<div class="paragraph"><p>Install the Toggle Word Wrap add-on that is available from

+<a href="https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/">https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/</a>

+It adds a menu entry "Enable Word Wrap" in the composer&#8217;s "Options" menu

+that you can tick off. Now you can compose the message as you otherwise do

+(cut + paste, <em>git format-patch</em> | <em>git imap-send</em>, etc), but you have to

+insert line breaks manually in any text that you type.</p></div>

+<h4 id="_approach_2_configuration">Approach #2 (configuration)</h4>

+<div class="paragraph"><p>Three steps:</p></div>

+<div class="olist arabic"><ol class="arabic">

+<li>

+<p>

+Configure your mail server composition as plain text:

+   Edit&#8230;Account Settings&#8230;Composition &amp; Addressing,

+   uncheck "Compose Messages in HTML".

+</p>

+</li>

+<li>

+<p>

+Configure your general composition window to not wrap.

+</p>

+<div class="paragraph"><p>In Thunderbird 2:

+Edit..Preferences..Composition, wrap plain text messages at 0</p></div>

+<div class="paragraph"><p>In Thunderbird 3:

+Edit..Preferences..Advanced..Config Editor.  Search for

+"mail.wrap_long_lines".

+Toggle it to make sure it is set to <tt>false</tt>.</p></div>

+</li>

+<li>

+<p>

+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 <tt>false</tt>.

+</p>

+</li>

+</ol></div>

+<div class="paragraph"><p>After that is done, you should be able to compose email as you

+otherwise would (cut + paste, <em>git format-patch</em> | <em>git imap-send</em>, etc),

+and the patches will not be mangled.</p></div>

+<h4 id="_approach_3_external_editor">Approach #3 (external editor)</h4>

+<div class="paragraph"><p>The following Thunderbird extensions are needed:

+AboutConfig from <a href="http://aboutconfig.mozdev.org/">http://aboutconfig.mozdev.org/</a> and

+External Editor from <a href="http://globs.org/articles.php?lng=en&amp;pg=8">http://globs.org/articles.php?lng=en&amp;pg=8</a></p></div>

+<div class="olist arabic"><ol class="arabic">

+<li>

+<p>

+Prepare the patch as a text file using your method of choice.

+</p>

+</li>

+<li>

+<p>

+Before opening a compose window, use Edit&#8594;Account Settings to

+   uncheck the "Compose messages in HTML format" setting in the

+   "Composition &amp; Addressing" panel of the account to be used to

+   send the patch.

+</p>

+</li>

+<li>

+<p>

+In the main Thunderbird window, <em>before</em> you open the compose

+   window for the patch, use Tools&#8594;about:config to set the

+   following to the indicated values:

+</p>

+<div class="listingblock">

+<div class="content">

+<pre><tt>        mailnews.send_plaintext_flowed  =&gt; false

+        mailnews.wraplength             =&gt; 0</tt></pre>

+</div></div>

+</li>

+<li>

+<p>

+Open a compose window and click the external editor icon.

+</p>

+</li>

+<li>

+<p>

+In the external editor window, read in the patch file and exit

+   the editor normally.

+</p>

+</li>

+</ol></div>

+<div class="paragraph"><p>Side note: it may be possible to do step 2 with

+about:config and the following settings but no one&#8217;s tried yet.</p></div>

+<div class="listingblock">

+<div class="content">

+<pre><tt>        mail.html_compose                       =&gt; false

+        mail.identity.default.compose_html      =&gt; false

+        mail.identity.id?.compose_html          =&gt; false</tt></pre>

+</div></div>

+<div class="paragraph"><p>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.</p></div>

+<h3 id="_kmail">KMail</h3><div style="clear:left"></div>

+<div class="paragraph"><p>This should help you to submit patches inline using KMail.</p></div>

+<div class="olist arabic"><ol class="arabic">

+<li>

+<p>

+Prepare the patch as a text file.

+</p>

+</li>

+<li>

+<p>

+Click on New Mail.

+</p>

+</li>

+<li>

+<p>

+Go under "Options" in the Composer window and be sure that

+   "Word wrap" is not set.

+</p>

+</li>

+<li>

+<p>

+Use Message &#8594; Insert file&#8230; and insert the patch.

+</p>

+</li>

+<li>

+<p>

+Back in the compose window: add whatever other text you wish to the

+   message, complete the addressing and subject fields, and press send.

+</p>

+</li>

+</ol></div>

+</div>

 <h2 id="_examples">EXAMPLES</h2>

 <div class="sectionbody">

 <div class="ulist"><ul>

@@ -1208,7 +1481,7 @@ as e-mailable patches:
 </div>

 <div id="footer">

 <div id="footer-text">

-Last updated 2011-04-27 21:09:28 UTC

+Last updated 2011-05-05 01:29:54 UTC

 </div>

 </div>

 </body>