Commit | Line | Data |
---|---|---|
06ad6367 MCC |
1 | .. _email_clients: |
2 | ||
a6cd6bf9 | 3 | Email clients info for Linux |
06ad6367 | 4 | ============================ |
a6cd6bf9 | 5 | |
7d19e91b | 6 | Git |
06ad6367 MCC |
7 | --- |
8 | ||
9 | These days most developers use ``git send-email`` instead of regular | |
7d19e91b | 10 | email clients. The man page for this is quite good. On the receiving |
06ad6367 | 11 | end, maintainers use ``git am`` to apply the patches. |
7d19e91b | 12 | |
06ad6367 MCC |
13 | If you are new to ``git`` then send your first patch to yourself. Save it |
14 | as raw text including all the headers. Run ``git am raw_email.txt`` and | |
15 | then review the changelog with ``git log``. When that works then send | |
7d19e91b DC |
16 | the patch to the appropriate mailing list(s). |
17 | ||
a6cd6bf9 | 18 | General Preferences |
06ad6367 MCC |
19 | ------------------- |
20 | ||
a6cd6bf9 RD |
21 | Patches for the Linux kernel are submitted via email, preferably as |
22 | inline text in the body of the email. Some maintainers accept | |
23 | attachments, but then the attachments should have content-type | |
06ad6367 | 24 | ``text/plain``. However, attachments are generally frowned upon because |
a6cd6bf9 RD |
25 | it makes quoting portions of the patch more difficult in the patch |
26 | review process. | |
27 | ||
28 | Email clients that are used for Linux kernel patches should send the | |
29 | patch text untouched. For example, they should not modify or delete tabs | |
30 | or spaces, even at the beginning or end of lines. | |
31 | ||
06ad6367 | 32 | Don't send patches with ``format=flowed``. This can cause unexpected |
a6cd6bf9 RD |
33 | and unwanted line breaks. |
34 | ||
35 | Don't let your email client do automatic word wrapping for you. | |
36 | This can also corrupt your patch. | |
37 | ||
38 | Email clients should not modify the character set encoding of the text. | |
39 | Emailed patches should be in ASCII or UTF-8 encoding only. | |
40 | If you configure your email client to send emails with UTF-8 encoding, | |
41 | you avoid some possible charset problems. | |
42 | ||
43 | Email clients should generate and maintain References: or In-Reply-To: | |
44 | headers so that mail threading is not broken. | |
45 | ||
46 | Copy-and-paste (or cut-and-paste) usually does not work for patches | |
47 | because tabs are converted to spaces. Using xclipboard, xclip, and/or | |
48 | xcutsel may work, but it's best to test this for yourself or just avoid | |
49 | copy-and-paste. | |
50 | ||
51 | Don't use PGP/GPG signatures in mail that contains patches. | |
52 | This breaks many scripts that read and apply the patches. | |
53 | (This should be fixable.) | |
54 | ||
55 | It's a good idea to send a patch to yourself, save the received message, | |
56 | and successfully apply it with 'patch' before sending patches to Linux | |
57 | mailing lists. | |
58 | ||
59 | ||
60 | Some email client (MUA) hints | |
06ad6367 MCC |
61 | ----------------------------- |
62 | ||
a6cd6bf9 RD |
63 | Here are some specific MUA configuration hints for editing and sending |
64 | patches for the Linux kernel. These are not meant to be complete | |
65 | software package configuration summaries. | |
66 | ||
06ad6367 | 67 | |
a6cd6bf9 | 68 | Legend: |
a6cd6bf9 | 69 | |
06ad6367 MCC |
70 | - TUI = text-based user interface |
71 | - GUI = graphical user interface | |
72 | ||
a6cd6bf9 | 73 | Alpine (TUI) |
06ad6367 | 74 | ************ |
a6cd6bf9 RD |
75 | |
76 | Config options: | |
a6cd6bf9 | 77 | |
06ad6367 MCC |
78 | In the :menuselection:`Sending Preferences` section: |
79 | ||
80 | - :menuselection:`Do Not Send Flowed Text` must be ``enabled`` | |
81 | - :menuselection:`Strip Whitespace Before Sending` must be ``disabled`` | |
a6cd6bf9 RD |
82 | |
83 | When composing the message, the cursor should be placed where the patch | |
06ad6367 | 84 | should appear, and then pressing :kbd:`CTRL-R` let you specify the patch file |
a6cd6bf9 RD |
85 | to insert into the message. |
86 | ||
04a3302b | 87 | Claws Mail (GUI) |
06ad6367 | 88 | **************** |
04a3302b RL |
89 | |
90 | Works. Some people use this successfully for patches. | |
91 | ||
06ad6367 MCC |
92 | To insert a patch use :menuselection:`Message-->Insert` File (:kbd:`CTRL-I`) |
93 | or an external editor. | |
04a3302b RL |
94 | |
95 | If the inserted patch has to be edited in the Claws composition window | |
06ad6367 MCC |
96 | "Auto wrapping" in |
97 | :menuselection:`Configuration-->Preferences-->Compose-->Wrapping` should be | |
04a3302b RL |
98 | disabled. |
99 | ||
a6cd6bf9 | 100 | Evolution (GUI) |
06ad6367 | 101 | *************** |
a6cd6bf9 RD |
102 | |
103 | Some people use this successfully for patches. | |
104 | ||
105 | When composing mail select: Preformat | |
06ad6367 | 106 | from :menuselection:`Format-->Paragraph Style-->Preformatted` (:kbd:`CTRL-7`) |
a6cd6bf9 RD |
107 | or the toolbar |
108 | ||
109 | Then use: | |
06ad6367 | 110 | :menuselection:`Insert-->Text File...` (:kbd:`ALT-N x`) |
a6cd6bf9 RD |
111 | to insert the patch. |
112 | ||
06ad6367 MCC |
113 | You can also ``diff -Nru old.c new.c | xclip``, select |
114 | :menuselection:`Preformat`, then paste with the middle button. | |
a6cd6bf9 | 115 | |
a6cd6bf9 | 116 | Kmail (GUI) |
06ad6367 | 117 | *********** |
a6cd6bf9 RD |
118 | |
119 | Some people use Kmail successfully for patches. | |
120 | ||
121 | The default setting of not composing in HTML is appropriate; do not | |
122 | enable it. | |
123 | ||
124 | When composing an email, under options, uncheck "word wrap". The only | |
125 | disadvantage is any text you type in the email will not be word-wrapped | |
126 | so you will have to manually word wrap text before the patch. The easiest | |
127 | way around this is to compose your email with word wrap enabled, then save | |
128 | it as a draft. Once you pull it up again from your drafts it is now hard | |
129 | word-wrapped and you can uncheck "word wrap" without losing the existing | |
130 | wrapping. | |
131 | ||
132 | At the bottom of your email, put the commonly-used patch delimiter before | |
06ad6367 | 133 | inserting your patch: three hyphens (``---``). |
a6cd6bf9 | 134 | |
06ad6367 MCC |
135 | Then from the :menuselection:`Message` menu item, select insert file and |
136 | choose your patch. | |
a6cd6bf9 | 137 | As an added bonus you can customise the message creation toolbar menu |
06ad6367 | 138 | and put the :menuselection:`insert file` icon there. |
a6cd6bf9 | 139 | |
d9a6ed1f | 140 | Make the composer window wide enough so that no lines wrap. As of |
5d3687d7 LC |
141 | KMail 1.13.5 (KDE 4.5.4), KMail will apply word wrapping when sending |
142 | the email if the lines wrap in the composer window. Having word wrapping | |
143 | disabled in the Options menu isn't enough. Thus, if your patch has very | |
144 | long lines, you must make the composer window very wide before sending | |
145 | the email. See: https://bugs.kde.org/show_bug.cgi?id=174034 | |
146 | ||
a6cd6bf9 RD |
147 | You can safely GPG sign attachments, but inlined text is preferred for |
148 | patches so do not GPG sign them. Signing patches that have been inserted | |
149 | as inlined text will make them tricky to extract from their 7-bit encoding. | |
150 | ||
151 | If you absolutely must send patches as attachments instead of inlining | |
152 | them as text, right click on the attachment and select properties, and | |
06ad6367 MCC |
153 | highlight :menuselection:`Suggest automatic display` to make the attachment |
154 | inlined to make it more viewable. | |
a6cd6bf9 RD |
155 | |
156 | When saving patches that are sent as inlined text, select the email that | |
157 | contains the patch from the message list pane, right click and select | |
06ad6367 MCC |
158 | :menuselection:`save as`. You can use the whole email unmodified as a patch |
159 | if it was properly composed. There is no option currently to save the email | |
160 | when you are actually viewing it in its own window -- there has been a request | |
161 | filed at kmail's bugzilla and hopefully this will be addressed. Emails are | |
162 | saved as read-write for user only so you will have to chmod them to make them | |
a6cd6bf9 RD |
163 | group and world readable if you copy them elsewhere. |
164 | ||
a6cd6bf9 | 165 | Lotus Notes (GUI) |
06ad6367 | 166 | ***************** |
a6cd6bf9 RD |
167 | |
168 | Run away from it. | |
169 | ||
e34e20e0 SS |
170 | IBM Verse (Web GUI) |
171 | ******************* | |
172 | ||
173 | See Lotus Notes. | |
174 | ||
a6cd6bf9 | 175 | Mutt (TUI) |
06ad6367 | 176 | ********** |
a6cd6bf9 | 177 | |
06ad6367 | 178 | Plenty of Linux developers use ``mutt``, so it must work pretty well. |
a6cd6bf9 RD |
179 | |
180 | Mutt doesn't come with an editor, so whatever editor you use should be | |
181 | used in a way that there are no automatic linebreaks. Most editors have | |
06ad6367 MCC |
182 | an :menuselection:`insert file` option that inserts the contents of a file |
183 | unaltered. | |
184 | ||
185 | To use ``vim`` with mutt:: | |
a6cd6bf9 | 186 | |
a6cd6bf9 RD |
187 | set editor="vi" |
188 | ||
06ad6367 MCC |
189 | If using xclip, type the command:: |
190 | ||
a6cd6bf9 | 191 | :set paste |
06ad6367 MCC |
192 | |
193 | before middle button or shift-insert or use:: | |
194 | ||
a6cd6bf9 RD |
195 | :r filename |
196 | ||
197 | if you want to include the patch inline. | |
06ad6367 MCC |
198 | (a)ttach works fine without ``set paste``. |
199 | ||
200 | You can also generate patches with ``git format-patch`` and then use Mutt | |
201 | to send them:: | |
a6cd6bf9 | 202 | |
803cfe26 EK |
203 | $ mutt -H 0001-some-bug-fix.patch |
204 | ||
a6cd6bf9 | 205 | Config options: |
06ad6367 | 206 | |
a6cd6bf9 | 207 | It should work with default settings. |
06ad6367 MCC |
208 | However, it's a good idea to set the ``send_charset`` to:: |
209 | ||
a6cd6bf9 RD |
210 | set send_charset="us-ascii:utf-8" |
211 | ||
91633a6d | 212 | Mutt is highly customizable. Here is a minimum configuration to start |
06ad6367 MCC |
213 | using Mutt to send patches through Gmail:: |
214 | ||
215 | # .muttrc | |
216 | # ================ IMAP ==================== | |
217 | set imap_user = 'yourusername@gmail.com' | |
218 | set imap_pass = 'yourpassword' | |
219 | set spoolfile = imaps://imap.gmail.com/INBOX | |
220 | set folder = imaps://imap.gmail.com/ | |
221 | set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" | |
222 | set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" | |
223 | set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" | |
224 | ||
225 | # ================ SMTP ==================== | |
226 | set smtp_url = "smtp://username@smtp.gmail.com:587/" | |
227 | set smtp_pass = $imap_pass | |
228 | set ssl_force_tls = yes # Require encrypted connection | |
229 | ||
230 | # ================ Composition ==================== | |
231 | set editor = `echo \$EDITOR` | |
232 | set edit_headers = yes # See the headers when editing | |
233 | set charset = UTF-8 # value of $LANG; also fallback for send_charset | |
234 | # Sender, email address, and sign-off line must match | |
235 | unset use_domain # because joe@localhost is just embarrassing | |
236 | set realname = "YOUR NAME" | |
237 | set from = "username@gmail.com" | |
238 | set use_from = yes | |
91633a6d EK |
239 | |
240 | The Mutt docs have lots more information: | |
06ad6367 | 241 | |
91633a6d | 242 | http://dev.mutt.org/trac/wiki/UseCases/Gmail |
06ad6367 | 243 | |
91633a6d EK |
244 | http://dev.mutt.org/doc/manual.html |
245 | ||
a6cd6bf9 | 246 | Pine (TUI) |
06ad6367 | 247 | ********** |
a6cd6bf9 RD |
248 | |
249 | Pine has had some whitespace truncation issues in the past, but these | |
250 | should all be fixed now. | |
251 | ||
252 | Use alpine (pine's successor) if you can. | |
253 | ||
254 | Config options: | |
06ad6367 MCC |
255 | |
256 | - ``quell-flowed-text`` is needed for recent versions | |
257 | - the ``no-strip-whitespace-before-send`` option is needed | |
a6cd6bf9 RD |
258 | |
259 | ||
a6cd6bf9 | 260 | Sylpheed (GUI) |
06ad6367 | 261 | ************** |
a6cd6bf9 RD |
262 | |
263 | - Works well for inlining text (or using attachments). | |
264 | - Allows use of an external editor. | |
a6cd6bf9 RD |
265 | - Is slow on large folders. |
266 | - Won't do TLS SMTP auth over a non-SSL connection. | |
267 | - Has a helpful ruler bar in the compose window. | |
268 | - Adding addresses to address book doesn't understand the display name | |
269 | properly. | |
270 | ||
a6cd6bf9 | 271 | Thunderbird (GUI) |
06ad6367 | 272 | ***************** |
a6cd6bf9 | 273 | |
e0e34e97 RL |
274 | Thunderbird is an Outlook clone that likes to mangle text, but there are ways |
275 | to coerce it into behaving. | |
a6cd6bf9 | 276 | |
d50ca078 | 277 | - Allow use of an external editor: |
a6cd6bf9 | 278 | The easiest thing to do with Thunderbird and patches is to use an |
06ad6367 | 279 | "external editor" extension and then just use your favorite ``$EDITOR`` |
a6cd6bf9 RD |
280 | for reading/merging patches into the body text. To do this, download |
281 | and install the extension, then add a button for it using | |
06ad6367 MCC |
282 | :menuselection:`View-->Toolbars-->Customize...` and finally just click on it |
283 | when in the :menuselection:`Compose` dialog. | |
a6cd6bf9 | 284 | |
d50ca078 | 285 | Please note that "external editor" requires that your editor must not |
a02b4fc2 | 286 | fork, or in other words, the editor must not return before closing. |
d50ca078 GS |
287 | You may have to pass additional flags or change the settings of your |
288 | editor. Most notably if you are using gvim then you must pass the -f | |
06ad6367 MCC |
289 | option to gvim by putting ``/usr/bin/gvim -f`` (if the binary is in |
290 | ``/usr/bin``) to the text editor field in :menuselection:`external editor` | |
291 | settings. If you are using some other editor then please read its manual | |
292 | to find out how to do this. | |
d50ca078 | 293 | |
e0e34e97 RL |
294 | To beat some sense out of the internal editor, do this: |
295 | ||
06ad6367 MCC |
296 | - Edit your Thunderbird config settings so that it won't use ``format=flowed``. |
297 | Go to :menuselection:`edit-->preferences-->advanced-->config editor` to bring up | |
298 | the thunderbird's registry editor. | |
e0e34e97 | 299 | |
06ad6367 | 300 | - Set ``mailnews.send_plaintext_flowed`` to ``false`` |
6989b5bb | 301 | |
06ad6367 | 302 | - Set ``mailnews.wraplength`` from ``72`` to ``0`` |
6989b5bb | 303 | |
06ad6367 | 304 | - :menuselection:`View-->Message Body As-->Plain Text` |
e0e34e97 | 305 | |
06ad6367 | 306 | - :menuselection:`View-->Character Encoding-->Unicode (UTF-8)` |
e0e34e97 | 307 | |
a6cd6bf9 | 308 | TkRat (GUI) |
06ad6367 | 309 | *********** |
a6cd6bf9 RD |
310 | |
311 | Works. Use "Insert file..." or external editor. | |
312 | ||
1b6bcdbe | 313 | Gmail (Web GUI) |
06ad6367 | 314 | *************** |
1b6bcdbe | 315 | |
5ce9f07b DY |
316 | Does not work for sending patches. |
317 | ||
318 | Gmail web client converts tabs to spaces automatically. | |
319 | ||
320 | At the same time it wraps lines every 78 chars with CRLF style line breaks | |
321 | although tab2space problem can be solved with external editor. | |
322 | ||
323 | Another problem is that Gmail will base64-encode any message that has a | |
324 | non-ASCII character. That includes things like European names. |