]> git.cworth.org Git - notmuch-old/blob - doc/notmuch-emacs.rst
162f62a4c7b2197c2bc28a35c329ed3818cf5571
[notmuch-old] / doc / notmuch-emacs.rst
1 .. _notmuch-emacs:
2
3 ==========================
4 Emacs Frontend for Notmuch
5 ==========================
6
7 About this Manual
8 =================
9
10 This manual covers only the Emacs interface to Notmuch. For information
11 on the command line interface, see section “Description” in the Notmuch
12 Manual Pages. To save typing, we will sometimes use *notmuch* in this
13 manual to refer to the Emacs interface to Notmuch. When this distinction
14 is important, we’ll refer to the Emacs interface as
15 *notmuch-emacs*.
16
17 Notmuch-emacs is highly customizable via the the Emacs customization
18 framework (or just by setting the appropriate variables). We try to
19 point out relevant variables in this manual, but in order to avoid
20 duplication of information, you can usually find the most detailed
21 description in the variables' docstring.
22
23 notmuch-hello
24 =============
25
26 .. index::
27    single: notmuch-hello
28    single: notmuch
29
30 ``notmuch-hello`` is the main entry point for Notmuch. You can start it
31 with ``M-x notmuch`` or ``M-x notmuch-hello``. The startup screen looks
32 something like the following. There are some hints at the bottom of the
33 screen. There are three main parts to the notmuch-hello screen,
34 discussed below. The **bold** text indicates buttons you can click with
35 a mouse or by positioning the cursor and pressing ``<return>``
36
37 |   Welcome to **notmuch** You have 52 messages.
38 |
39 | Saved searches: **[edit]**
40 |
41 |         52 **inbox**           52 **unread**
42 |
43 | Search: ____________________________________
44 |
45 | All tags: **[show]**
46 |
47 |        Hit \`?' for context-sensitive help in any Notmuch screen.
48 |                     Customize Notmuch or this page.
49
50 You can change the overall appearance of the notmuch-hello screen by
51 customizing the variables
52
53 .. emacsvar:: notmuch-hello-sections
54
55        |docstring::notmuch-hello-sections|
56
57 .. emacsvar:: notmuch-hello-thousands-separator
58
59        |docstring::notmuch-hello-thousands-separator|
60
61 .. emacsvar:: notmuch-show-logo
62
63        |docstring::notmuch-show-logo|
64
65 .. emacsvar:: notmuch-column-control
66
67     Controls the number of columns for saved searches/tags in notmuch view.
68
69     This variable has three potential types of values:
70
71     .. describe:: t
72
73        Automatically calculate the number of columns possible based
74        on the tags to be shown and the window width.
75
76     .. describe:: integer <n>
77
78        A lower bound on the number of characters that will
79        be used to display each column.
80
81     .. describe:: float <f>
82
83        A fraction of the window width that is the lower bound on the
84        number of characters that should be used for each column.
85
86     So:
87
88     - if you would like two columns of tags, set this to 0.5.
89
90     - if you would like a single column of tags, set this to 1.0.
91
92     - if you would like tags to be 30 characters wide, set this to 30.
93
94     - if you don't want to worry about all of this nonsense, leave
95       this set to `t`.
96
97 .. emacsvar:: notmuch-show-empty-saved-searches
98
99    |docstring::notmuch-show-empty-saved-searches|
100
101 notmuch-hello key bindings
102 --------------------------
103
104 ``<tab>``
105     Move to the next widget (button or text entry field)
106
107 ``<backtab>``
108     Move to the previous widget.
109
110 ``<return>``
111     Activate the current widget.
112
113 ``g`` ``=``
114     Refresh the buffer; mainly update the counts of messages for various
115     saved searches.
116
117 ``G``
118     Import mail, See :ref:`importing`
119
120 ``m``
121     Compose a message
122
123 ``s``
124     Search the notmuch database using :ref:`notmuch-search`
125
126 ``v``
127     Print notmuch version
128
129 ``q``
130     Quit
131
132 .. _saved-searches:
133
134 Saved Searches
135 --------------
136
137 Since notmuch is entirely search-based, it's often useful to organize
138 mail around common searches.  To facilitate this, the first section of
139 notmuch-hello presents a customizable set of saved searches.  Saved
140 searches can also be accessed from anywhere in notmuch by pressing
141 ``j`` to access :ref:`notmuch-jump`.
142
143 The saved searches default to various common searches such as
144 ``tag:inbox`` to access the inbox and ``tag:unread`` to access all
145 unread mail, but there are several options for customization:
146
147 .. emacsvar:: notmuch-saved-searches
148
149     The list of saved searches, including names, queries, and
150     additional per-query options.
151
152 .. emacsvar:: notmuch-saved-search-sort-function
153
154     This variable controls how saved searches should be sorted. A value
155     of ``nil`` displays the saved searches in the order they are stored
156     in ‘notmuch-saved-searches’.
157
158 Search Box
159 ----------
160
161 The search box lets the user enter a Notmuch query. See section
162 “Description” in Notmuch Query Syntax, for more info on Notmuch query
163 syntax. A history of recent searches is also displayed by default. The
164 latter is controlled by the variable `notmuch-hello-recent-searches-max`.
165
166 .. emacsvar:: notmuch-hello-recent-searches-max
167
168               |docstring::notmuch-hello-recent-searches-max|
169
170 Known Tags
171 ----------
172
173 One special kind of saved search provided by default is for each
174 individual tag defined in the database. This can be controlled via the
175 following variables.
176
177 .. emacsvar:: notmuch-hello-tag-list-make-query
178
179     Control how to construct a search (“virtual folder”) from a given
180     tag.
181
182 .. emacsvar:: notmuch-hello-hide-tags
183
184     Which tags not to display at all.
185
186 .. _notmuch-search:
187
188 notmuch-search
189 ==============
190
191 ``notmuch-search-mode`` is used to display the results from executing
192 a query via ``notmuch-search``. The syntax for these queries is the
193 the same as :ref:`saved-searches`. For details of this syntax see
194 info:notmuch-search-terms
195
196 By default the output approximates that of the command line See section
197 “Description” in notmuch search command.
198
199 The main purpose of the ``notmuch-search-mode`` buffer is to act as a
200 menu of results that the user can explore further by pressing
201 ``<return>`` on the appropriate line.
202
203 ``n,C-n,<down>``
204     Move to next line
205
206 ``p,C-p,<up>``
207     Move to previous line
208
209 ``<return>``
210     Open thread on current line in :ref:`notmuch-show` mode
211
212 ``g`` ``=``
213     Refresh the buffer
214
215 ``?``
216     Display full set of key bindings
217
218 The presentation of results can be controlled by the following
219 variables.
220
221 .. emacsvar:: notmuch-search-result-format
222
223    |docstring::notmuch-search-result-format|
224
225    If the car of an element in notmuch-search-result-format is a
226    function, insert the result of calling the function into the buffer.
227
228    This allows a user to generate custom fields in the output of a
229    search result. For example, with the following settings, the first
230    few characters on each line of the search result are used to show
231    information about some significant tags associated with the thread.
232
233    .. code:: lisp
234
235       (defun -notmuch-result-flags (format-string result)
236         (let ((tags-to-letters '(("flagged" . "!")
237                                  ("unread" . "u")
238                                  ("mine" . "m")
239                                  ("sent" . "s")
240                                  ("replied" . "r")))
241               (tags (plist-get result :tags)))
242           (format format-string
243                   (mapconcat (lambda (t2l)
244                                (if (member (car t2l) tags)
245                                    (cdr t2l)
246                                  " "))
247                              tags-to-letters ""))))
248
249       (setq notmuch-search-result-format '((-notmuch-result-flags . "%s ")
250                                            ("date" . "%12s ")
251                                            ("count" . "%9s ")
252                                            ("authors" . "%-30s ")
253                                            ("subject" . "%s ")
254                                            ("tags" . "(%s)")))
255
256    See also :emacsvar:`notmuch-tree-result-format` and
257    :emacsvar:`notmuch-unthreaded-result-format`.
258
259 .. emacsvar:: notmuch-search-oldest-first
260
261     Display the oldest threads at the top of the buffer
262
263 It is also possible to customize how the name of buffers containing
264 search results is formatted using the following variables:
265
266 .. emacsvar:: notmuch-search-buffer-name-format
267
268        |docstring::notmuch-search-buffer-name-format|
269
270 .. emacsvar:: notmuch-saved-search-buffer-name-format
271
272        |docstring::notmuch-saved-search-buffer-name-format|
273
274
275 .. _notmuch-show:
276
277 notmuch-show
278 ============
279
280 ``notmuch-show-mode`` is used to display a single thread of email from
281 your email archives.
282
283 By default, various components of email messages, (citations,
284 signatures, already-read messages), are hidden. You can make
285 these parts visible by clicking with the mouse button or by
286 pressing RET after positioning the cursor on a hidden part.
287
288 ``<space>``
289     Scroll the current message (if necessary),
290     advance to the next message, or advance to the next thread (if
291     already on the last message of a thread).
292
293 ``c``
294     :ref:`show-copy`
295
296 ``N``
297     Move to next message
298
299 ``P``
300     Move to previous message (or start of current message)
301
302 ``n``
303     Move to next matching message
304
305 ``p``
306     Move to previous matching message
307
308 ``+,-``
309     Add or remove arbitrary tags from the current message.
310
311 ``!``
312     |docstring::notmuch-show-toggle-elide-non-matching|
313
314 ``?``
315     Display full set of key bindings
316
317 Display of messages can be controlled by the following variables; see also :ref:`show-large`.
318
319 .. emacsvar:: notmuch-message-headers
320
321        |docstring::notmuch-message-headers|
322
323 .. emacsvar:: notmuch-message-headers-visible
324
325        |docstring::notmuch-message-headers-visible|
326
327 .. emacsvar:: notmuch-show-header-line
328
329        |docstring::notmuch-show-header-line|
330
331 .. emacsvar:: notmuch-multipart/alternative-discouraged
332
333    Which mime types to hide by default for multipart messages.
334
335    Can either be a list of mime types (as strings) or a function
336    mapping a plist representing the current message to such a list.
337    The following example function would discourage `text/html` and
338    `multipart/related` generally, but discourage `text/plain` should
339    the message be sent from `whatever@example.com`.
340
341    .. code:: lisp
342
343       (defun my--determine-discouraged (msg)
344         (let* ((headers (plist-get msg :headers))
345                (from (or (plist-get headers :From) "")))
346           (cond
347            ((string-match "whatever@example.com" from)
348             (list "text/plain"))
349            (t
350             (list "text/html" "multipart/related")))))
351
352 .. _show-large:
353
354 Dealing with large messages and threads
355 ---------------------------------------
356
357 If you are finding :ref:`notmuch-show` is annoyingly slow displaying
358 large messages, you can customize
359 :emacsvar:`notmuch-show-max-text-part-size`.  If you want to speed up the
360 display of large threads (with or without large messages), there are
361 several options.  First, you can display the same query in one of the
362 other modes. :ref:`notmuch-unthreaded` is the most robust for
363 extremely large queries, but :ref:`notmuch-tree` is also be faster
364 than :ref:`notmuch-show` in general, since it only renders a single
365 message a time. If you prefer to stay with the rendered thread
366 ("conversation") view of :ref:`notmuch-show`, you can customize the
367 variables :emacsvar:`notmuch-show-depth-limit`,
368 :emacsvar:`notmuch-show-height-limit` and
369 :emacsvar:`notmuch-show-max-text-part-size` to limit the amount of
370 rendering done initially. Note that these limits are implicitly
371 *OR*-ed together, and combinations might have surprising effects.
372
373 .. emacsvar:: notmuch-show-depth-limit
374
375        |docstring::notmuch-show-depth-limit|
376
377 .. emacsvar:: notmuch-show-height-limit
378
379        |docstring::notmuch-show-height-limit|
380
381 .. emacsvar:: notmuch-show-max-text-part-size
382
383        |docstring::notmuch-show-max-text-part-size|
384
385 .. _show-copy:
386
387 Copy to kill-ring
388 -----------------
389
390 You can use the usually Emacs ways of copying text to the kill-ring,
391 but notmuch also provides some shortcuts. These keys are available in
392 :ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available
393 in :ref:`notmuch-search`.
394
395 ``c F`` ``notmuch-show-stash-filename``
396    |docstring::notmuch-show-stash-filename|
397
398 ``c G`` ``notmuch-show-stash-git-send-email``
399    |docstring::notmuch-show-stash-git-send-email|
400
401 ``c I`` ``notmuch-show-stash-message-id-stripped``
402    |docstring::notmuch-show-stash-message-id-stripped|
403
404 ``c L`` ``notmuch-show-stash-mlarchive-link-and-go``
405    |docstring::notmuch-show-stash-mlarchive-link-and-go|
406
407 ``c T`` ``notmuch-show-stash-tags``
408    |docstring::notmuch-show-stash-tags|
409
410 ``c c`` ``notmuch-show-stash-cc``
411    |docstring::notmuch-show-stash-cc|
412
413 ``c d`` ``notmuch-show-stash-date``
414    |docstring::notmuch-show-stash-date|
415
416 ``c f`` ``notmuch-show-stash-from``
417    |docstring::notmuch-show-stash-from|
418
419 ``c i`` ``notmuch-show-stash-message-id``
420    |docstring::notmuch-show-stash-message-id|
421
422 ``c l`` ``notmuch-show-stash-mlarchive-link``
423    |docstring::notmuch-show-stash-mlarchive-link|
424
425 ``c s`` ``notmuch-show-stash-subject``
426    |docstring::notmuch-show-stash-subject|
427
428 ``c t`` ``notmuch-show-stash-to``
429    |docstring::notmuch-show-stash-to|
430
431 ``c ?``
432     Show all available copying commands
433
434 .. _emacs-show-duplicates:
435
436 Dealing with duplicates
437 -----------------------
438
439 If there are are multiple files with the same :mailheader:`Message-ID`
440 (see :any:`duplicate-files`), then :any:`notmuch-show` displays the
441 number of duplicates and identifies the current duplicate. In the
442 following example duplicate 3 of 5 is displayed.
443
444 .. code-block::
445    :emphasize-lines: 1
446
447     M. Mustermann <max@example.com> (Sat, 30 Jul 2022 10:33:10 -0300) (inbox signed)      3/5
448     Subject: Re: Multiple files per message in emacs
449     To: notmuch@notmuchmail.org
450
451 To display a different message file with the same
452 :mailheader:`Message-ID`, the user can run the command
453 :emacscmd:`notmuch-show-choose-duplicate`, by default bound to `%`.
454
455 .. emacscmd:: notmuch-show-choose-duplicate
456
457    |docstring::notmuch-show-choose-duplicate|
458
459 .. _notmuch-tree:
460
461 notmuch-tree
462 ============
463
464 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
465 email archives. Each line in the buffer represents a single
466 message giving the relative date, the author, subject, and any
467 tags.
468
469 ``c``
470     :ref:`show-copy`
471
472 ``<return>``
473    Displays that message.
474
475 ``N``
476     Move to next message
477
478 ``P``
479     Move to previous message
480
481 ``n``
482     Move to next matching message
483
484 ``p``
485     Move to previous matching message
486
487 ``o`` ``notmuch-tree-toggle-order``
488    |docstring::notmuch-tree-toggle-order|
489
490 ``l`` ``notmuch-tree-filter``
491    Filter or LIMIT the current search results based on an additional query string
492
493 ``t`` ``notmuch-tree-filter-by-tag``
494    Filter the current search results based on an additional tag
495
496
497 ``g`` ``=``
498     Refresh the buffer
499
500 ``?``
501     Display full set of key bindings
502
503 As is the case with :ref:`notmuch-search`, the presentation of results
504 can be controlled by the variable ``notmuch-search-oldest-first``.
505
506 .. emacsvar:: notmuch-tree-result-format
507
508    |docstring::notmuch-tree-result-format|
509
510    The following example shows how to optionally display recipients instead
511    of authors for sent mail (assuming the user is named Mustermann).
512
513    .. code:: lisp
514
515       (defun -notmuch-authors-or-to (format-string result)
516         (let* ((headers (plist-get result :headers))
517                (to (plist-get headers :To))
518                (author (plist-get headers :From))
519                (face (if (plist-get result :match)
520                          'notmuch-tree-match-author-face
521                        'notmuch-tree-no-match-author-face)))
522           (propertize
523            (format format-string
524                    (if (string-match "Mustermann" author)
525                        (concat "To:" (notmuch-tree-clean-address to))
526                      author))
527            'face face)))
528
529       (setq notmuch-tree-result-format
530             '(("date" . "%12s  ")
531               (-notmuch-authors-or-to . "%-20.20s")
532               ((("tree" . "%s")
533                 ("subject" . "%s"))
534                . " %-54s ")
535               ("tags" . "(%s)")))
536
537    See also :emacsvar:`notmuch-search-result-format` and
538    :emacsvar:`notmuch-unthreaded-result-format`.
539
540
541 .. _notmuch-unthreaded:
542
543 notmuch-unthreaded
544 ------------------
545
546 ``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
547 each line corresponds to a single message, but no thread information
548 is presented.
549
550 Keybindings are the same as :any:`notmuch-tree`.
551
552 .. emacsvar:: notmuch-unthreaded-result-format
553
554    |docstring::notmuch-unthreaded-result-format|
555
556    See also :emacsvar:`notmuch-search-result-format` and
557    :emacsvar:`notmuch-tree-result-format`.
558
559 Global key bindings
560 ===================
561
562 Several features are accessible from most places in notmuch through the
563 following key bindings:
564
565 ``j``
566     Jump to saved searches using :ref:`notmuch-jump`.
567
568 ``k``
569     Tagging operations using :ref:`notmuch-tag-jump`
570
571 ``C-_`` ``C-/`` ``C-x u``: Undo previous tagging operation using :ref:`notmuch-tag-undo`
572
573 .. _notmuch-jump:
574
575 notmuch-jump
576 ------------
577
578 Saved searches configured through :ref:`saved-searches` can
579 include a "shortcut key" that's accessible through notmuch-jump.
580 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
581 key of a saved search will immediately jump to that saved search.  For
582 example, in the default configuration ``j i`` jumps immediately to the
583 inbox search.  When you press ``j``, notmuch-jump shows the saved
584 searches and their shortcut keys in the mini-buffer.
585
586 .. _notmuch-tag-jump:
587
588 notmuch-tag-jump
589 ----------------
590
591 Tagging operations configured through ``notmuch-tagging-keys`` can
592 be accessed via :kbd:`k` in :ref:`notmuch-show`,
593 :ref:`notmuch-search` and :ref:`notmuch-tree`.  With a
594 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
595 operations specified in ``notmuch-tagging-keys``; i.e. each
596 ``+tag`` is replaced by ``-tag`` and vice versa.
597
598 .. emacsvar:: notmuch-tagging-keys
599
600   |docstring::notmuch-tagging-keys|
601
602 .. _notmuch-tag-undo:
603
604 notmuch-tag-undo
605 ----------------
606
607 Each notmuch buffer supporting tagging operations (i.e buffers in
608 :any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
609 :any:`notmuch-unthreaded` mode) keeps a local stack of tagging
610 operations. These can be undone via :emacscmd:`notmuch-tag-undo`. By default
611 this is bound to the usual Emacs keys for undo.
612
613 .. emacscmd:: notmuch-tag-undo
614
615    |docstring::notmuch-tag-undo|
616
617 Buffer navigation
618 =================
619
620 .. emacscmd:: notmuch-cycle-notmuch-buffers
621
622    |docstring::notmuch-cycle-notmuch-buffers|
623
624 Configuration
625 =============
626
627 .. _importing:
628
629 Importing Mail
630 --------------
631
632 .. emacscmd:: notmuch-poll
633
634    |docstring::notmuch-poll|
635
636 .. emacsvar:: notmuch-poll-script
637
638    |docstring::notmuch-poll-script|
639
640 Sending Mail
641 ------------
642
643 .. emacsvar:: mail-user-agent
644
645        Emacs consults the variable :code:`mail-user-agent` to choose a mail
646        sending package for commands like :code:`report-emacs-bug` and
647        :code:`compose-mail`.  To use ``notmuch`` for this, customize this
648        variable to the symbol :code:`notmuch-user-agent`.
649
650 .. emacsvar:: message-dont-reply-to-names
651
652        When composing mail replies, Emacs's message mode uses the
653        variable :code:`message-dont-reply-to-names` to exclude
654        recipients matching a given collection of regular expressions
655        or satisfying an arbitrary predicate.  Notmuch's MUA inherits
656        this standard mechanism and will honour your customization of
657        this variable.
658
659 Init File
660 ---------
661
662 When Notmuch is loaded, it will read the ``notmuch-init-file``
663 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
664 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
665 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
666 suffix exist it will be read instead (just one of these, chosen in this
667 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
668 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
669 options, ``notmuch-init-file`` is not read.