3 ==========================
4 Emacs Frontend for Notmuch
5 ==========================
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
17 Notmuch-emacs is highly customizable via 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.
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>``
37 | Welcome to **notmuch** You have 52 messages.
39 | Saved searches: **[edit]**
41 | 52 **inbox** 52 **unread**
43 | Search: ____________________________________
45 | All tags: **[show]**
47 | Hit \`?' for context-sensitive help in any Notmuch screen.
48 | Customize Notmuch or this page.
50 You can change the overall appearance of the notmuch-hello screen by
51 customizing the variables
53 .. el:defcustom:: notmuch-hello-sections
55 |docstring::notmuch-hello-sections|
57 .. el:defcustom:: notmuch-hello-thousands-separator
59 |docstring::notmuch-hello-thousands-separator|
61 .. el:defcustom:: notmuch-show-logo
63 |docstring::notmuch-show-logo|
65 .. el:defcustom:: notmuch-column-control
67 Controls the number of columns for saved searches/tags in notmuch view.
69 This variable has three potential types of values:
73 Automatically calculate the number of columns possible based
74 on the tags to be shown and the window width.
76 .. describe:: integer <n>
78 A lower bound on the number of characters that will
79 be used to display each column.
81 .. describe:: float <f>
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.
88 - if you would like two columns of tags, set this to 0.5.
90 - if you would like a single column of tags, set this to 1.0.
92 - if you would like tags to be 30 characters wide, set this to 30.
94 - if you don't want to worry about all of this nonsense, leave
97 .. el:defcustom:: notmuch-show-empty-saved-searches
99 |docstring::notmuch-show-empty-saved-searches|
101 notmuch-hello key bindings
102 --------------------------
104 .. el:define-key:: <tab>
106 Move to the next widget (button or text entry field)
108 .. el:define-key:: <backtab>
110 Move to the previous widget.
112 .. el:define-key:: <return>
114 Activate the current widget.
119 Refresh the buffer; mainly update the counts of messages for various
124 Import mail, See :ref:`importing`
132 Search the notmuch database using :ref:`notmuch-search`
136 Print notmuch version
147 Since notmuch is entirely search-based, it's often useful to organize
148 mail around common searches. To facilitate this, the first section of
149 notmuch-hello presents a customizable set of saved searches. Saved
150 searches can also be accessed from anywhere in notmuch by pressing
151 ``j`` to access :ref:`notmuch-jump`.
153 The saved searches default to various common searches such as
154 ``tag:inbox`` to access the inbox and ``tag:unread`` to access all
155 unread mail, but there are several options for customization:
157 .. el:defcustom:: notmuch-saved-searches
159 The list of saved searches, including names, queries, and
160 additional per-query options.
162 .. el:defcustom:: notmuch-saved-search-sort-function
164 This variable controls how saved searches should be sorted. A value
165 of ``nil`` displays the saved searches in the order they are stored
166 in ‘notmuch-saved-searches’.
171 The search box lets the user enter a Notmuch query. See section
172 “Description” in Notmuch Query Syntax, for more info on Notmuch query
173 syntax. A history of recent searches is also displayed by default. The
174 latter is controlled by the variable `notmuch-hello-recent-searches-max`.
176 .. el:defcustom:: notmuch-hello-recent-searches-max
178 |docstring::notmuch-hello-recent-searches-max|
183 One special kind of saved search provided by default is for each
184 individual tag defined in the database. This can be controlled via the
187 .. el:defcustom:: notmuch-hello-tag-list-make-query
189 Control how to construct a search (“virtual folder”) from a given
192 .. el:defcustom:: notmuch-hello-hide-tags
194 Which tags not to display at all.
201 ``notmuch-search-mode`` is used to display the results from executing
202 a query via ``notmuch-search``. The syntax for these queries is the
203 the same as :ref:`saved-searches`. For details of this syntax see
204 info:notmuch-search-terms
206 By default the output approximates that of the command line See section
207 “Description” in notmuch search command.
209 The main purpose of the ``notmuch-search-mode`` buffer is to act as a
210 menu of results that the user can explore further by pressing
211 ``<return>`` on the appropriate line.
224 Move to previous line
226 .. el:define-key:: <return>
228 Open thread on current line in :ref:`notmuch-show` mode
237 Display full set of key bindings
239 The presentation of results can be controlled by the following
242 .. el:defcustom:: notmuch-search-result-format
244 |docstring::notmuch-search-result-format|
246 If the car of an element in notmuch-search-result-format is a
247 function, insert the result of calling the function into the buffer.
249 This allows a user to generate custom fields in the output of a
250 search result. For example, with the following settings, the first
251 few characters on each line of the search result are used to show
252 information about some significant tags associated with the thread.
256 (defun -notmuch-result-flags (format-string result)
257 (let ((tags-to-letters '(("flagged" . "!")
262 (tags (plist-get result :tags)))
263 (format format-string
264 (mapconcat (lambda (t2l)
265 (if (member (car t2l) tags)
268 tags-to-letters ""))))
270 (setq notmuch-search-result-format '((-notmuch-result-flags . "%s ")
273 ("authors" . "%-30s ")
277 See also :el:defcustom:`notmuch-tree-result-format` and
278 :el:defcustom:`notmuch-unthreaded-result-format`.
280 .. el:defcustom:: notmuch-search-oldest-first
282 Display the oldest threads at the top of the buffer
284 It is also possible to customize how the name of buffers containing
285 search results is formatted using the following variables:
287 .. el:defcustom:: notmuch-search-buffer-name-format
289 |docstring::notmuch-search-buffer-name-format|
291 .. el:defcustom:: notmuch-saved-search-buffer-name-format
293 |docstring::notmuch-saved-search-buffer-name-format|
301 ``notmuch-show-mode`` is used to display a single thread of email from
304 By default, various components of email messages, (citations,
305 signatures, already-read messages), are hidden. You can make
306 these parts visible by clicking with the mouse button or by
307 pressing RET after positioning the cursor on a hidden part.
309 .. el:define-key:: <space>
311 Scroll the current message (if necessary),
312 advance to the next message, or advance to the next thread (if
313 already on the last message of a thread).
325 Move to previous message (or start of current message)
329 Move to next matching message
333 Move to previous matching message
338 Add or remove arbitrary tags from the current message.
342 |docstring::notmuch-show-toggle-elide-non-matching|
346 Display full set of key bindings
348 Display of messages can be controlled by the following variables; see also :ref:`show-large`.
350 .. el:defcustom:: notmuch-message-headers
352 |docstring::notmuch-message-headers|
354 .. el:defcustom:: notmuch-message-headers-visible
356 |docstring::notmuch-message-headers-visible|
358 .. el:defcustom:: notmuch-show-header-line
360 |docstring::notmuch-show-header-line|
362 .. el:defcustom:: notmuch-multipart/alternative-discouraged
364 Which mime types to hide by default for multipart messages.
366 Can either be a list of mime types (as strings) or a function
367 mapping a plist representing the current message to such a list.
368 The following example function would discourage `text/html` and
369 `multipart/related` generally, but discourage `text/plain` should
370 the message be sent from `whatever@example.com`.
374 (defun my--determine-discouraged (msg)
375 (let* ((headers (plist-get msg :headers))
376 (from (or (plist-get headers :From) "")))
378 ((string-match "whatever@example.com" from)
381 (list "text/html" "multipart/related")))))
385 Dealing with large messages and threads
386 ---------------------------------------
388 If you are finding :ref:`notmuch-show` is annoyingly slow displaying
389 large messages, you can customize
390 :el:defcustom:`notmuch-show-max-text-part-size`. If you want to speed up the
391 display of large threads (with or without large messages), there are
392 several options. First, you can display the same query in one of the
393 other modes. :ref:`notmuch-unthreaded` is the most robust for
394 extremely large queries, but :ref:`notmuch-tree` is also be faster
395 than :ref:`notmuch-show` in general, since it only renders a single
396 message a time. If you prefer to stay with the rendered thread
397 ("conversation") view of :ref:`notmuch-show`, you can customize the
398 variables :el:defcustom:`notmuch-show-depth-limit`,
399 :el:defcustom:`notmuch-show-height-limit` and
400 :el:defcustom:`notmuch-show-max-text-part-size` to limit the amount of
401 rendering done initially. Note that these limits are implicitly
402 *OR*-ed together, and combinations might have surprising effects.
404 .. el:defcustom:: notmuch-show-depth-limit
406 |docstring::notmuch-show-depth-limit|
408 .. el:defcustom:: notmuch-show-height-limit
410 |docstring::notmuch-show-height-limit|
412 .. el:defcustom:: notmuch-show-max-text-part-size
414 |docstring::notmuch-show-max-text-part-size|
421 You can use the usually Emacs ways of copying text to the kill-ring,
422 but notmuch also provides some shortcuts. These keys are available in
423 :ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available
424 in :ref:`notmuch-search`.
426 .. el:define-key:: c F
427 M-x notmuch-show-stash-filename
429 |docstring::notmuch-show-stash-filename|
431 .. el:define-key:: c G
432 M-x notmuch-show-stash-git-send-email
434 |docstring::notmuch-show-stash-git-send-email|
436 .. el:define-key:: c I
437 M-x notmuch-show-stash-message-id-stripped
439 |docstring::notmuch-show-stash-message-id-stripped|
441 .. el:define-key:: c L
442 M-x notmuch-show-stash-mlarchive-link-and-go
444 |docstring::notmuch-show-stash-mlarchive-link-and-go|
446 .. el:define-key:: c T
447 M-x notmuch-show-stash-tags
449 |docstring::notmuch-show-stash-tags|
451 .. el:define-key:: c c
452 M-x notmuch-show-stash-cc
454 |docstring::notmuch-show-stash-cc|
456 .. el:define-key:: c d
457 M-x notmuch-show-stash-date
459 |docstring::notmuch-show-stash-date|
461 .. el:define-key:: c f
462 M-x notmuch-show-stash-from
464 |docstring::notmuch-show-stash-from|
466 .. el:define-key:: c i
467 M-x notmuch-show-stash-message-id
469 |docstring::notmuch-show-stash-message-id|
471 .. el:define-key:: c l
472 M-x notmuch-show-stash-mlarchive-link
474 |docstring::notmuch-show-stash-mlarchive-link|
476 .. el:define-key:: c s
477 M-x notmuch-show-stash-subject
479 |docstring::notmuch-show-stash-subject|
481 .. el:define-key:: c t
482 M-x notmuch-show-stash-to
484 |docstring::notmuch-show-stash-to|
486 .. el:define-key:: c ?
487 M-x notmuch-subkeymap-help
489 Show all available copying commands
491 .. _emacs-show-duplicates:
493 Dealing with duplicates
494 -----------------------
496 If there are multiple files with the same :mailheader:`Message-ID`
497 (see :any:`duplicate-files`), then :any:`notmuch-show` displays the
498 number of duplicates and identifies the current duplicate. In the
499 following example duplicate 3 of 5 is displayed.
504 M. Mustermann <max@example.com> (Sat, 30 Jul 2022 10:33:10 -0300) (inbox signed) 3/5
505 Subject: Re: Multiple files per message in emacs
506 To: notmuch@notmuchmail.org
509 M-x notmuch-show-choose-duplicate
511 |docstring::notmuch-show-choose-duplicate|
518 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
519 email archives. Each line in the buffer represents a single
520 message giving the relative date, the author, subject, and any
527 .. el:define-key:: <return>
529 Displays that message.
537 Move to previous message
541 Move to next matching message
545 Move to previous matching message
548 M-x notmuch-tree-toggle-order
550 |docstring::notmuch-tree-toggle-order|
553 M-x notmuch-tree-filter
555 Filter or LIMIT the current search results based on an additional query string
558 M-x notmuch-tree-filter-by-tag
560 Filter the current search results based on an additional tag
570 Display full set of key bindings
572 As is the case with :ref:`notmuch-search`, the presentation of results
573 can be controlled by the variable ``notmuch-search-oldest-first``.
575 .. el:defcustom:: notmuch-tree-result-format
577 |docstring::notmuch-tree-result-format|
579 The following example shows how to optionally display recipients instead
580 of authors for sent mail (assuming the user is named Mustermann).
584 (defun -notmuch-authors-or-to (format-string result)
585 (let* ((headers (plist-get result :headers))
586 (to (plist-get headers :To))
587 (author (plist-get headers :From))
588 (face (if (plist-get result :match)
589 'notmuch-tree-match-author-face
590 'notmuch-tree-no-match-author-face)))
592 (format format-string
593 (if (string-match "Mustermann" author)
594 (concat "To:" (notmuch-tree-clean-address to))
598 (setq notmuch-tree-result-format
600 (-notmuch-authors-or-to . "%-20.20s")
606 See also :el:defcustom:`notmuch-search-result-format` and
607 :el:defcustom:`notmuch-unthreaded-result-format`.
609 .. _notmuch-tree-outline:
614 When this mode is set, each thread and subthread in the results
615 list is treated as a foldable section, with its first message as
618 The mode just makes available in the tree buffer all the
619 keybindings in info:emacs#Outline_Mode, and binds the following
622 .. el:define-key:: <tab>
624 Cycle visibility state of the current message's tree.
626 .. el:define-key:: <M-tab>
628 Cycle visibility state of all trees in the buffer.
630 The behaviour of this minor mode is affected by the following
631 customizable variables:
633 .. el:defcustom:: notmuch-tree-outline-enabled
635 |docstring::notmuch-tree-outline-enabled|
637 .. el:defcustom:: notmuch-tree-outline-visibility
639 |docstring::notmuch-tree-outline-visibility|
641 .. el:defcustom:: notmuch-tree-outline-auto-close
643 |docstring::notmuch-tree-outline-auto-close|
645 .. el:defcustom:: notmuch-tree-outline-open-on-next
647 |docstring::notmuch-tree-outline-open-on-next|
649 .. _notmuch-unthreaded:
654 ``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
655 each line corresponds to a single message, but no thread information
658 Keybindings are the same as :any:`notmuch-tree`.
660 .. el:defcustom:: notmuch-unthreaded-result-format
662 |docstring::notmuch-unthreaded-result-format|
664 See also :el:defcustom:`notmuch-search-result-format` and
665 :el:defcustom:`notmuch-tree-result-format`.
670 Several features are accessible from most places in notmuch through the
671 following key bindings:
675 Jump to saved searches using :ref:`notmuch-jump`.
679 Tagging operations using :ref:`notmuch-tag-jump`
681 .. el:define-key:: C-_
685 Undo previous tagging operation using :any:`notmuch-tag-undo`
692 Saved searches configured through :ref:`saved-searches` can
693 include a "shortcut key" that's accessible through notmuch-jump.
694 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
695 key of a saved search will immediately jump to that saved search. For
696 example, in the default configuration ``j i`` jumps immediately to the
697 inbox search. When you press ``j``, notmuch-jump shows the saved
698 searches and their shortcut keys in the mini-buffer.
700 .. _notmuch-tag-jump:
705 Tagging operations configured through ``notmuch-tagging-keys`` can
706 be accessed via :kbd:`k` in :ref:`notmuch-show`,
707 :ref:`notmuch-search` and :ref:`notmuch-tree`. With a
708 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
709 operations specified in ``notmuch-tagging-keys``; i.e. each
710 ``+tag`` is replaced by ``-tag`` and vice versa.
712 .. el:defcustom:: notmuch-tagging-keys
714 |docstring::notmuch-tagging-keys|
720 Each notmuch buffer supporting tagging operations (i.e. buffers in
721 :any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
722 :any:`notmuch-unthreaded` mode) keeps a local stack of tagging
723 operations. These can be undone via :any:`notmuch-tag-undo`. By default
724 this is bound to the usual Emacs keys for undo.
726 .. el:define-key:: C-_
731 |docstring::notmuch-tag-undo|
736 .. el:define-key:: M-x notmuch-cycle-notmuch-buffers
738 |docstring::notmuch-cycle-notmuch-buffers|
748 .. el:define-key:: M-x notmuch-poll
750 |docstring::notmuch-poll|
752 .. el:defcustom:: notmuch-poll-script
754 |docstring::notmuch-poll-script|
759 .. el:defcustom:: mail-user-agent
761 Emacs consults the variable :code:`mail-user-agent` to choose a mail
762 sending package for commands like :code:`report-emacs-bug` and
763 :code:`compose-mail`. To use ``notmuch`` for this, customize this
764 variable to the symbol :code:`notmuch-user-agent`.
766 .. el:defcustom:: message-dont-reply-to-names
768 When composing mail replies, Emacs's message mode uses the
769 variable :code:`message-dont-reply-to-names` to exclude
770 recipients matching a given collection of regular expressions
771 or satisfying an arbitrary predicate. Notmuch's MUA inherits
772 this standard mechanism and will honour your customization of
778 When Notmuch is loaded, it will read the ``notmuch-init-file``
779 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
780 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
781 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
782 suffix exist it will be read instead (just one of these, chosen in this
783 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
784 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
785 options, ``notmuch-init-file`` is not read.