From 57756161eed50f2b52c9e32b01f6388814a09943 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Thu, 14 Apr 2011 21:24:01 -0500 Subject: Documentation: explain how to check for patch corruption 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 Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 58 +++++++++----------------------------- Documentation/git-format-patch.txt | 46 ++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+), 44 deletions(-) (limited to 'Documentation') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index c6a5032912..20b4101474 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 155b7ae3cb..8bf6a68501 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 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 -------- -- cgit v1.2.1 From dc53151f02ce05f21641895f08808ff7caa9854f Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Thu, 14 Apr 2011 21:28:06 -0500 Subject: Documentation: hints for sending patches inline with Thunderbird 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 Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 81 +------------------------------------ Documentation/git-format-patch.txt | 83 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 80 deletions(-) (limited to 'Documentation') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 20b4101474..7908119f18 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 8bf6a68501..627f381331 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 -------- -- cgit v1.2.1 From 967ab8efd7f294c05b57db600c4e548d7c4f8b2f Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Thu, 14 Apr 2011 21:32:55 -0500 Subject: Documentation: publicize KMail hints for sending patches inline 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 Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 22 ++-------------------- Documentation/git-format-patch.txt | 16 ++++++++++++++++ 2 files changed, 18 insertions(+), 20 deletions(-) (limited to 'Documentation') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 7908119f18..e9d8c3f6c1 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 627f381331..04e0f02d8e 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 -------- -- cgit v1.2.1 From 36c10e6d7543f9f35295df0113b0c250ad421eb4 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Thu, 14 Apr 2011 21:33:57 -0500 Subject: Documentation: publicize hints for sending patches with GMail 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 Signed-off-by: Junio C Hamano --- 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(-) (limited to 'Documentation') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index e9d8c3f6c1..938eccf2a5 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 04e0f02d8e..81b442eb28 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 d3013d6a29..4e09708cc9 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 ee14f74fd3..5a168cfab2 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 -- cgit v1.2.1 From b895960516ef3edf66b5200019e2851e1a779053 Mon Sep 17 00:00:00 2001 From: Johannes Sixt Date: Mon, 18 Apr 2011 08:31:16 +0200 Subject: Documentation/format-patch: suggest Toggle Word Wrap add-on for Thunderbird 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 Signed-off-by: Junio C Hamano --- Documentation/git-format-patch.txt | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) (limited to 'Documentation') diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 81b442eb28..c2fd8e4b9d 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -357,11 +357,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: @@ -388,7 +398,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: -- cgit v1.2.1