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