From df5753c4f6398c1b0a9f5bd4b24d7bf47a33533f Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Wed, 7 Apr 2010 15:59:17 -0700 Subject: SubmittingPatches: update GMail section Even if you use imap-send to throw your drafts in the outbox, using their web interface will mangle your patches. Clarify that the imap-send is meant to be used together with a real MUA that can use IMAP drafts, and remove instructions related to the web interface, which is irrelevant. Add description of send-email as an alternative. Use --cover-letter, and do not use -C nor --no-color, on the example command line for format-patch. Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 35 ++++++++++++++++++++++++----------- 1 file changed, 24 insertions(+), 11 deletions(-) (limited to 'Documentation/SubmittingPatches') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index c686f8646b..abc65de946 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -520,11 +520,9 @@ 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 any IMAP email client to connect to the google imap server, and forward -the emails through that. Just make sure to disable line wrapping in that -email client. Alternatively, use "git send-email" instead. +the emails through that. -Submitting properly formatted patches via Gmail is simple now that -IMAP support is available. First, edit your ~/.gitconfig to specify your +To submit using the IMAP interface, first, edit your ~/.gitconfig to specify your account settings: [imap] @@ -538,14 +536,29 @@ account settings: You might need to instead use: folder = "[Google Mail]/Drafts" if you get an error that the "Folder doesn't exist". -Next, ensure that your Gmail settings are correct. In "Settings" the -"Use Unicode (UTF-8) encoding for outgoing messages" should be checked. +Once your commits are ready to be sent to the mailing list, run the +following command to send the patch emails to your Gmail Drafts +folder. -Once your commits are ready to send to the mailing list, run the following -command to send the patch emails to your Gmail Drafts folder. + $ git format-patch --cover-letter -M --stdout origin/master | git imap-send - $ git format-patch -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). -Go to your Gmail account, open the Drafts folder, find the patch email, fill -in the To: and CC: fields and send away! +Alternatively, you can 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/ + $ git send-email outgoing/* -- cgit v1.2.3 From d0c26f0f56444d93a08121bb1f3691b2bbbfb958 Mon Sep 17 00:00:00 2001 From: Ramkumar Ramachandra Date: Mon, 19 Apr 2010 01:24:20 +0530 Subject: SubmittingPatches: Add new section about what to base work on Add a section 0 explaining which commit to base patches on. Signed-off-by: Ramkumar Ramachandra Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 49 ++++++++++++++++++++++++++++++++--------- 1 file changed, 38 insertions(+), 11 deletions(-) (limited to 'Documentation/SubmittingPatches') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index c686f8646b..10402591ac 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -53,6 +53,34 @@ But the patch submission requirements are a lot more relaxed here on the technical/contents front, because the core GIT is thousand times smaller ;-). So here is only the relevant bits. +(0) Decide what to base your work on. + +In general, always base your work on the oldest branch that your +change is relevant to. + + - A bugfix should be based on 'maint' in general. If the bug is not + present in 'maint', base it on 'master'. For a bug that's not yet + in 'master', find the topic that introduces the regression, and + base your work on the tip of the topic. + + - A new feature should be based on 'master' in general. If the new + feature depends on a topic that is in 'pu', but not in 'master', + base your work on the tip of that topic. + + - Corrections and enhancements to a topic not yet in 'master' should + be based on the tip of that topic. If the topic has not been merged + to 'next', it's alright to add a note to squash minor corrections + into the series. + + - In the exceptional case that a new feature depends on several topics + not in 'master', start working on 'next' or 'pu' privately and send + out patches for discussion. Before the final merge, you may have to + wait until some of the dependent topics graduate to 'master', and + rebase your work. + +To find the tip of a topic branch, run "git log --first-parent +master..pu" and look for the merge commit. The second parent of this +commit is the tip of the topic branch. (1) Make separate commits for logically separate changes. @@ -170,17 +198,16 @@ patch, format it as "multipart/signed", not a text/plain message that starts with '-----BEGIN PGP SIGNED MESSAGE-----'. That is not a text/plain, it's something else. -Note that your maintainer does not necessarily read everything -on the git mailing list. If your patch is for discussion first, -send it "To:" the mailing list, and optionally "cc:" him. If it -is trivially correct or after the list reached a consensus, send -it "To:" the maintainer and optionally "cc:" the list for -inclusion. - -Also note that your maintainer does not actively involve himself in -maintaining what are in contrib/ hierarchy. When you send fixes and -enhancements to them, do not forget to "cc: " the person who primarily -worked on that hierarchy in contrib/. +Unless your patch is a very trivial and an obviously correct one, +first send it with "To:" set to the mailing list, with "cc:" listing +people who are involved in the area you are touching (the output from +"git blame $path" and "git shortlog --no-merges $path" would help to +identify them), to solicit comments and reviews. After the list +reached a consensus that it is a good idea to apply the patch, re-send +it with "To:" set to the maintainer and optionally "cc:" the list for +inclusion. Do not forget to add trailers such as "Acked-by:", +"Reviewed-by:" and "Tested-by:" after your "Signed-off-by:" line as +necessary. (4) Sign your work -- cgit v1.2.3 From e498257d650529812ffe1872b3cd62e2bd604287 Mon Sep 17 00:00:00 2001 From: Michael J Gruber Date: Tue, 25 May 2010 10:30:13 +0200 Subject: Documentation/SubmittingPatches: clarify GMail section and SMTP We keep getting mangled submissions from GMail's web interface. Try to be more proactive in SubmittingPatches by - pointing to MUA specific instructions early on, - structuring the GMail section more clearly, - putting send-email/SMTP before imap-send/IMAP. Signed-off-by: Michael J Gruber Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 40 +++++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 19 deletions(-) (limited to 'Documentation/SubmittingPatches') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index abc65de946..22e38086be 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -41,6 +41,7 @@ Checklist (and a short version for the impatient): maintainer (gitster@pobox.com) if (and only if) the patch is ready for inclusion. If you use git-send-email(1), please test it first by sending email to yourself. + - see below for instructions specific to your mailer Long version: @@ -519,9 +520,27 @@ 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 any IMAP email client to connect to the google imap server, and forward +use "git send e-mail" 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: @@ -537,8 +556,7 @@ You might need to instead use: folder = "[Google Mail]/Drafts" if you get an err that the "Folder doesn't exist". Once your commits are ready to be sent to the mailing list, run the -following command to send the patch emails to your Gmail Drafts -folder. +following commands: $ git format-patch --cover-letter -M --stdout origin/master | git imap-send @@ -546,19 +564,3 @@ 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). -Alternatively, you can 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/ - $ git send-email outgoing/* -- cgit v1.2.3 From 811dd906dbb391544085a3a7ca6cfc7b53d33131 Mon Sep 17 00:00:00 2001 From: Tim Henigan Date: Wed, 26 May 2010 08:36:10 -0400 Subject: Documentation/SubmittingPatches: Fix typo in GMail section Commit e498257d introduced a typo while improving the GMail section of SubmittingPatches. Signed-off-by: Tim Henigan Acked-by: Michael J Gruber Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/SubmittingPatches') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 22e38086be..84248daa58 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -520,7 +520,7 @@ 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 e-mail" and send your patches through the GMail SMTP server, or +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. -- cgit v1.2.3 From 6a58696f5b446cef4874c45b1c953403707325b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Wed, 28 Jul 2010 14:12:59 +0000 Subject: SubmittingPatches: Clarify the Signed-off-by rules MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The wording of the Signed-off-by rules could be read as stating that S-O-B should only be added when the submitter considered the patch ready for inclusion in git.git. We also want Signed-off-by to be used for e.g. RFC patches, in case someone wants to dig an old patch out of the archive and improve it. Change the wording to recommend a Signed-off-by for all submitted patches. The problem with the wording came up in the "[PATCH/RFC] Hacky version of a glob() driven config include" thread[1]. Bert Wesarg suggested[2] that it be removed to avoid confusion, which this change implements. 1. <1273180440-8641-1-git-send-email-avarab@gmail.com> 2. Suggested-by: Bert Wesarg Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) (limited to 'Documentation/SubmittingPatches') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index eb53e0636e..2e18f6b440 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -13,11 +13,9 @@ Checklist (and a short version for the impatient): not "changed" or "changes". - includes motivation for the change, and contrasts its implementation with previous behaviour - - if you want your work included in git.git, add a - "Signed-off-by: Your Name " line to the - commit message (or just use the option "-s" when - committing) to confirm that you agree to the Developer's - Certificate of Origin + - add a "Signed-off-by: Your Name " line to the + commit message (or just use the option "-s" when committing) + to confirm that you agree to the Developer's Certificate of Origin - make sure that you have tests for the bug you are fixing - make sure that the test suite passes after your commit -- cgit v1.2.3 From 43e331e6ee46ba156d43f1fd3ebc91cc35575e47 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=86var=20Arnfj=C3=B6r=C3=B0=20Bjarmason?= Date: Wed, 28 Jul 2010 14:11:25 +0000 Subject: SubmittingPatches: Cite the 50 char subject limit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Change the SubmittingPatches recommendations to mention the 50 character soft limit on patch subject lines. 50 characters is the soft limit mentioned in git-commit(1) and gittutorial(7), it's also the point at which Gitweb, GitHub and various other Git front ends start abbreviating the commit message. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'Documentation/SubmittingPatches') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 2e18f6b440..ece3c77482 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -7,7 +7,8 @@ Checklist (and a short version for the impatient): before committing - do not check in commented out code or unneeded files - the first line of the commit message should be a short - description and should skip the full stop + description (50 characters is the soft limit, see DISCUSSION + in git-commit(1)), and should skip the full stop - the body should provide a meaningful commit message, which: - uses the imperative, present tense: "change", not "changed" or "changes". -- cgit v1.2.3 From 95b7a41a80e56e3df904a2080d0665565c231272 Mon Sep 17 00:00:00 2001 From: Ramkumar Ramachandra Date: Sat, 2 Oct 2010 10:07:43 +0530 Subject: SubmittingPatches: Document some extra tags used in commit messages Document the meanings of the tags "Reported-by:", "Acked-by:", "Reviewed-by:" and "Tested-by:" clearly. Also mention that the user is free to use any custom tags. Helped-by: Jonathan Nieder Liked-by: Sverre Rabbelier Signed-off-by: Ramkumar Ramachandra Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 21 +++++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) (limited to 'Documentation/SubmittingPatches') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index ece3c77482..72741ebda1 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -264,12 +264,21 @@ the change to its true author (see (2) above). Also notice that a real name is used in the Signed-off-by: line. Please don't hide your real name. -Some people also put extra tags at the end. - -"Acked-by:" says that the patch was reviewed by the person who -is more familiar with the issues and the area the patch attempts -to modify. "Tested-by:" says the patch was tested by the person -and found to have the desired effect. +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 + 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. +3. "Reviewed-by:", unlike the other tags, can only be offered by the + reviewer and means that she is completely satisfied that the patch + is ready for application. It is usually offered only after a + detailed review. +4. "Tested-by:" is used to indicate that the person applied the patch + and found it to have the desired effect. + +You can also create your own tag or use one that's in common usage +such as "Thanks-to:", "Based-on-patch-by:", or "Mentored-by:". ------------------------------------------------ An ideal patch flow -- cgit v1.2.3 From d0f7dcbf424e1739437ffe477d87088ca6cb3432 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 8 Mar 2011 16:58:19 -0800 Subject: SubmittingPatches: clarify the expected commit log description Earlier, 47afed5 (SubmittingPatches: itemize and reflect upon well written changes, 2009-04-28) added a discussion on the contents of the commit log message, but the last part of the new paragraph didn't make much sense. Reword it slightly to make it more readable. Update the "quicklist" to clarify what we mean by "motivation" and "contrast". Also mildly discourage external references. Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 26 ++++++++++++++++++-------- 1 file changed, 18 insertions(+), 8 deletions(-) (limited to 'Documentation/SubmittingPatches') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 72741ebda1..c3b0816ed7 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -10,10 +10,18 @@ Checklist (and a short version for the impatient): description (50 characters is the soft limit, see DISCUSSION in git-commit(1)), and should skip the full stop - the body should provide a meaningful commit message, which: - - uses the imperative, present tense: "change", - not "changed" or "changes". - - includes motivation for the change, and contrasts - its implementation with previous behaviour + . explains the problem the change tries to solve, iow, what + is wrong with the current code without the change. + . justifies the way the change solves the problem, iow, why + the result with the change is better. + . alternate solutions considered but discarded, if any. + - describe changes in imperative mood, e.g. "make xyzzy do frotz" + instead of "[This patch] makes xyzzy do frotz" or "[I] changed + xyzzy to do frotz", as if you are giving orders to the codebase + to change its behaviour. + - try to make sure your explanation can be understood without + external resources. Instead of giving a URL to a mailing list + archive, summarize the relevant points of the discussion. - add a "Signed-off-by: Your Name " line to the commit message (or just use the option "-s" when committing) to confirm that you agree to the Developer's Certificate of Origin @@ -90,7 +98,10 @@ your commit head. Instead, always make a commit with complete commit message and generate a series of patches from your repository. It is a good discipline. -Describe the technical detail of the change(s). +Give an explanation for the change(s) that is detailed enough so +that people can judge if it is good thing to do, without reading +the actual patch text to determine how well the code does what +the explanation promises to do. If your description starts to get too long, that's a sign that you probably need to split up your commit to finer grained pieces. @@ -99,9 +110,8 @@ help reviewers check the patch, and future maintainers understand the code, are the most beautiful patches. Descriptions that summarise the point in the subject well, and describe the motivation for the change, the approach taken by the change, and if relevant how this -differs substantially from the prior version, can be found on Usenet -archives back into the late 80's. Consider it like good Netiquette, -but for code. +differs substantially from the prior version, are all good things +to have. Oh, another thing. I am picky about whitespaces. Make sure your changes do not trigger errors with the sample pre-commit hook shipped -- cgit v1.2.3 From 0353a0c4ec91cf2d0a8e209025aa2e1909d05f19 Mon Sep 17 00:00:00 2001 From: Jim Meyering Date: Wed, 13 Apr 2011 17:39:40 +0200 Subject: remove doubled words, e.g., s/to to/to/, and fix related typos 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: 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"}' Signed-off-by: Jim Meyering Signed-off-by: Junio C Hamano --- Documentation/SubmittingPatches | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'Documentation/SubmittingPatches') diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index c3b0816ed7..c6a5032912 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). - -- cgit v1.2.3 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 ++++++++++------------------------------- 1 file changed, 14 insertions(+), 44 deletions(-) (limited to 'Documentation/SubmittingPatches') 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 -- cgit v1.2.3 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 +---------------------------------------- 1 file changed, 1 insertion(+), 80 deletions(-) (limited to 'Documentation/SubmittingPatches') 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 ---- -- cgit v1.2.3 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 ++-------------------- 1 file changed, 2 insertions(+), 20 deletions(-) (limited to 'Documentation/SubmittingPatches') 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 ----- -- cgit v1.2.3 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 ++--------------------------------------- 1 file changed, 2 insertions(+), 52 deletions(-) (limited to 'Documentation/SubmittingPatches') 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). -- cgit v1.2.3