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 | ||
e226b4f0 | 43 | Email clients should generate and maintain "References:" or "In-Reply-To:" |
a6cd6bf9 RD |
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 | ||
e226b4f0 | 92 | To insert a patch use :menuselection:`Message-->Insert File` (:kbd:`CTRL-I`) |
06ad6367 | 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 | |
e226b4f0 FV |
135 | Then from the :menuselection:`Message` menu item, select |
136 | :menuselection:`insert file` and 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 | |
e226b4f0 FV |
152 | them as text, right click on the attachment and select :menuselection:`properties`, |
153 | and highlight :menuselection:`Suggest automatic display` to make the attachment | |
06ad6367 | 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 | 158 | :menuselection:`save as`. You can use the whole email unmodified as a patch |
e226b4f0 FV |
159 | if it was properly composed. Emails are saved as read-write for user only so |
160 | you will have to chmod them to make them group and world readable if you copy | |
161 | them elsewhere. | |
a6cd6bf9 | 162 | |
a6cd6bf9 | 163 | Lotus Notes (GUI) |
06ad6367 | 164 | ***************** |
a6cd6bf9 RD |
165 | |
166 | Run away from it. | |
167 | ||
e34e20e0 SS |
168 | IBM Verse (Web GUI) |
169 | ******************* | |
170 | ||
171 | See Lotus Notes. | |
172 | ||
a6cd6bf9 | 173 | Mutt (TUI) |
06ad6367 | 174 | ********** |
a6cd6bf9 | 175 | |
06ad6367 | 176 | Plenty of Linux developers use ``mutt``, so it must work pretty well. |
a6cd6bf9 RD |
177 | |
178 | Mutt doesn't come with an editor, so whatever editor you use should be | |
179 | used in a way that there are no automatic linebreaks. Most editors have | |
06ad6367 MCC |
180 | an :menuselection:`insert file` option that inserts the contents of a file |
181 | unaltered. | |
182 | ||
183 | To use ``vim`` with mutt:: | |
a6cd6bf9 | 184 | |
a6cd6bf9 RD |
185 | set editor="vi" |
186 | ||
06ad6367 MCC |
187 | If using xclip, type the command:: |
188 | ||
a6cd6bf9 | 189 | :set paste |
06ad6367 MCC |
190 | |
191 | before middle button or shift-insert or use:: | |
192 | ||
a6cd6bf9 RD |
193 | :r filename |
194 | ||
195 | if you want to include the patch inline. | |
06ad6367 MCC |
196 | (a)ttach works fine without ``set paste``. |
197 | ||
198 | You can also generate patches with ``git format-patch`` and then use Mutt | |
199 | to send them:: | |
a6cd6bf9 | 200 | |
803cfe26 EK |
201 | $ mutt -H 0001-some-bug-fix.patch |
202 | ||
a6cd6bf9 | 203 | Config options: |
06ad6367 | 204 | |
a6cd6bf9 | 205 | It should work with default settings. |
06ad6367 MCC |
206 | However, it's a good idea to set the ``send_charset`` to:: |
207 | ||
a6cd6bf9 RD |
208 | set send_charset="us-ascii:utf-8" |
209 | ||
91633a6d | 210 | Mutt is highly customizable. Here is a minimum configuration to start |
06ad6367 MCC |
211 | using Mutt to send patches through Gmail:: |
212 | ||
213 | # .muttrc | |
214 | # ================ IMAP ==================== | |
215 | set imap_user = 'yourusername@gmail.com' | |
216 | set imap_pass = 'yourpassword' | |
217 | set spoolfile = imaps://imap.gmail.com/INBOX | |
218 | set folder = imaps://imap.gmail.com/ | |
219 | set record="imaps://imap.gmail.com/[Gmail]/Sent Mail" | |
220 | set postponed="imaps://imap.gmail.com/[Gmail]/Drafts" | |
221 | set mbox="imaps://imap.gmail.com/[Gmail]/All Mail" | |
222 | ||
223 | # ================ SMTP ==================== | |
224 | set smtp_url = "smtp://username@smtp.gmail.com:587/" | |
225 | set smtp_pass = $imap_pass | |
226 | set ssl_force_tls = yes # Require encrypted connection | |
227 | ||
228 | # ================ Composition ==================== | |
229 | set editor = `echo \$EDITOR` | |
230 | set edit_headers = yes # See the headers when editing | |
231 | set charset = UTF-8 # value of $LANG; also fallback for send_charset | |
232 | # Sender, email address, and sign-off line must match | |
233 | unset use_domain # because joe@localhost is just embarrassing | |
234 | set realname = "YOUR NAME" | |
235 | set from = "username@gmail.com" | |
236 | set use_from = yes | |
91633a6d EK |
237 | |
238 | The Mutt docs have lots more information: | |
06ad6367 | 239 | |
dff2c2e6 | 240 | https://gitlab.com/muttmua/mutt/-/wikis/UseCases/Gmail |
06ad6367 | 241 | |
dff2c2e6 | 242 | http://www.mutt.org/doc/manual/ |
91633a6d | 243 | |
a6cd6bf9 | 244 | Pine (TUI) |
06ad6367 | 245 | ********** |
a6cd6bf9 RD |
246 | |
247 | Pine has had some whitespace truncation issues in the past, but these | |
248 | should all be fixed now. | |
249 | ||
250 | Use alpine (pine's successor) if you can. | |
251 | ||
252 | Config options: | |
06ad6367 MCC |
253 | |
254 | - ``quell-flowed-text`` is needed for recent versions | |
255 | - the ``no-strip-whitespace-before-send`` option is needed | |
a6cd6bf9 RD |
256 | |
257 | ||
a6cd6bf9 | 258 | Sylpheed (GUI) |
06ad6367 | 259 | ************** |
a6cd6bf9 RD |
260 | |
261 | - Works well for inlining text (or using attachments). | |
262 | - Allows use of an external editor. | |
a6cd6bf9 RD |
263 | - Is slow on large folders. |
264 | - Won't do TLS SMTP auth over a non-SSL connection. | |
265 | - Has a helpful ruler bar in the compose window. | |
266 | - Adding addresses to address book doesn't understand the display name | |
267 | properly. | |
268 | ||
a6cd6bf9 | 269 | Thunderbird (GUI) |
06ad6367 | 270 | ***************** |
a6cd6bf9 | 271 | |
e0e34e97 RL |
272 | Thunderbird is an Outlook clone that likes to mangle text, but there are ways |
273 | to coerce it into behaving. | |
a6cd6bf9 | 274 | |
d50ca078 | 275 | - Allow use of an external editor: |
a6cd6bf9 | 276 | The easiest thing to do with Thunderbird and patches is to use an |
06ad6367 | 277 | "external editor" extension and then just use your favorite ``$EDITOR`` |
a6cd6bf9 RD |
278 | for reading/merging patches into the body text. To do this, download |
279 | and install the extension, then add a button for it using | |
06ad6367 MCC |
280 | :menuselection:`View-->Toolbars-->Customize...` and finally just click on it |
281 | when in the :menuselection:`Compose` dialog. | |
a6cd6bf9 | 282 | |
d50ca078 | 283 | Please note that "external editor" requires that your editor must not |
a02b4fc2 | 284 | fork, or in other words, the editor must not return before closing. |
d50ca078 GS |
285 | You may have to pass additional flags or change the settings of your |
286 | editor. Most notably if you are using gvim then you must pass the -f | |
06ad6367 MCC |
287 | option to gvim by putting ``/usr/bin/gvim -f`` (if the binary is in |
288 | ``/usr/bin``) to the text editor field in :menuselection:`external editor` | |
289 | settings. If you are using some other editor then please read its manual | |
290 | to find out how to do this. | |
d50ca078 | 291 | |
e0e34e97 RL |
292 | To beat some sense out of the internal editor, do this: |
293 | ||
06ad6367 MCC |
294 | - Edit your Thunderbird config settings so that it won't use ``format=flowed``. |
295 | Go to :menuselection:`edit-->preferences-->advanced-->config editor` to bring up | |
296 | the thunderbird's registry editor. | |
e0e34e97 | 297 | |
06ad6367 | 298 | - Set ``mailnews.send_plaintext_flowed`` to ``false`` |
6989b5bb | 299 | |
06ad6367 | 300 | - Set ``mailnews.wraplength`` from ``72`` to ``0`` |
6989b5bb | 301 | |
06ad6367 | 302 | - :menuselection:`View-->Message Body As-->Plain Text` |
e0e34e97 | 303 | |
06ad6367 | 304 | - :menuselection:`View-->Character Encoding-->Unicode (UTF-8)` |
e0e34e97 | 305 | |
a6cd6bf9 | 306 | TkRat (GUI) |
06ad6367 | 307 | *********** |
a6cd6bf9 RD |
308 | |
309 | Works. Use "Insert file..." or external editor. | |
310 | ||
1b6bcdbe | 311 | Gmail (Web GUI) |
06ad6367 | 312 | *************** |
1b6bcdbe | 313 | |
5ce9f07b DY |
314 | Does not work for sending patches. |
315 | ||
316 | Gmail web client converts tabs to spaces automatically. | |
317 | ||
318 | At the same time it wraps lines every 78 chars with CRLF style line breaks | |
319 | although tab2space problem can be solved with external editor. | |
320 | ||
321 | Another problem is that Gmail will base64-encode any message that has a | |
322 | non-ASCII character. That includes things like European names. |