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 Toggle whether to show messages with excluded tags in search results.
241 Display full set of key bindings
243 The presentation of results can be controlled by the following
246 .. el:defcustom:: notmuch-search-result-format
248 |docstring::notmuch-search-result-format|
250 If the car of an element in notmuch-search-result-format is a
251 function, insert the result of calling the function into the buffer.
253 This allows a user to generate custom fields in the output of a
254 search result. For example, with the following settings, the first
255 few characters on each line of the search result are used to show
256 information about some significant tags associated with the thread.
260 (defun -notmuch-result-flags (format-string result)
261 (let ((tags-to-letters '(("flagged" . "!")
266 (tags (plist-get result :tags)))
267 (format format-string
268 (mapconcat (lambda (t2l)
269 (if (member (car t2l) tags)
272 tags-to-letters ""))))
274 (setq notmuch-search-result-format '((-notmuch-result-flags . "%s ")
277 ("authors" . "%-30s ")
281 See also :el:defcustom:`notmuch-tree-result-format` and
282 :el:defcustom:`notmuch-unthreaded-result-format`.
284 .. el:defcustom:: notmuch-search-oldest-first
286 Display the oldest threads at the top of the buffer
288 It is also possible to customize how the name of buffers containing
289 search results is formatted using the following variables:
291 .. el:defcustom:: notmuch-search-buffer-name-format
293 |docstring::notmuch-search-buffer-name-format|
295 .. el:defcustom:: notmuch-saved-search-buffer-name-format
297 |docstring::notmuch-saved-search-buffer-name-format|
305 ``notmuch-show-mode`` is used to display a single thread of email from
308 By default, various components of email messages, (citations,
309 signatures, already-read messages), are hidden. You can make
310 these parts visible by clicking with the mouse button or by
311 pressing RET after positioning the cursor on a hidden part.
313 .. el:define-key:: <space>
315 Scroll the current message (if necessary),
316 advance to the next message, or advance to the next thread (if
317 already on the last message of a thread).
329 Move to previous message (or start of current message)
333 Move to next matching message
337 Move to previous matching message
342 Add or remove arbitrary tags from the current message.
346 |docstring::notmuch-show-toggle-elide-non-matching|
350 Display full set of key bindings
352 Display of messages can be controlled by the following variables; see also :ref:`show-large`.
354 .. el:defcustom:: notmuch-message-headers
356 |docstring::notmuch-message-headers|
358 .. el:defcustom:: notmuch-message-headers-visible
360 |docstring::notmuch-message-headers-visible|
362 .. el:defcustom:: notmuch-show-header-line
364 |docstring::notmuch-show-header-line|
366 .. el:defcustom:: notmuch-multipart/alternative-discouraged
368 Which mime types to hide by default for multipart messages.
370 Can either be a list of mime types (as strings) or a function
371 mapping a plist representing the current message to such a list.
372 The following example function would discourage `text/html` and
373 `multipart/related` generally, but discourage `text/plain` should
374 the message be sent from `whatever@example.com`.
378 (defun my--determine-discouraged (msg)
379 (let* ((headers (plist-get msg :headers))
380 (from (or (plist-get headers :From) "")))
382 ((string-match "whatever@example.com" from)
385 (list "text/html" "multipart/related")))))
389 Dealing with large messages and threads
390 ---------------------------------------
392 If you are finding :ref:`notmuch-show` is annoyingly slow displaying
393 large messages, you can customize
394 :el:defcustom:`notmuch-show-max-text-part-size`. If you want to speed up the
395 display of large threads (with or without large messages), there are
396 several options. First, you can display the same query in one of the
397 other modes. :ref:`notmuch-unthreaded` is the most robust for
398 extremely large queries, but :ref:`notmuch-tree` is also be faster
399 than :ref:`notmuch-show` in general, since it only renders a single
400 message a time. If you prefer to stay with the rendered thread
401 ("conversation") view of :ref:`notmuch-show`, you can customize the
402 variables :el:defcustom:`notmuch-show-depth-limit`,
403 :el:defcustom:`notmuch-show-height-limit` and
404 :el:defcustom:`notmuch-show-max-text-part-size` to limit the amount of
405 rendering done initially. Note that these limits are implicitly
406 *OR*-ed together, and combinations might have surprising effects.
408 .. el:defcustom:: notmuch-show-depth-limit
410 |docstring::notmuch-show-depth-limit|
412 .. el:defcustom:: notmuch-show-height-limit
414 |docstring::notmuch-show-height-limit|
416 .. el:defcustom:: notmuch-show-max-text-part-size
418 |docstring::notmuch-show-max-text-part-size|
425 You can use the usually Emacs ways of copying text to the kill-ring,
426 but notmuch also provides some shortcuts. These keys are available in
427 :ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available
428 in :ref:`notmuch-search`.
430 .. el:define-key:: c F
431 M-x notmuch-show-stash-filename
433 |docstring::notmuch-show-stash-filename|
435 .. el:define-key:: c G
436 M-x notmuch-show-stash-git-send-email
438 |docstring::notmuch-show-stash-git-send-email|
440 .. el:define-key:: c I
441 M-x notmuch-show-stash-message-id-stripped
443 |docstring::notmuch-show-stash-message-id-stripped|
445 .. el:define-key:: c L
446 M-x notmuch-show-stash-mlarchive-link-and-go
448 |docstring::notmuch-show-stash-mlarchive-link-and-go|
450 .. el:define-key:: c T
451 M-x notmuch-show-stash-tags
453 |docstring::notmuch-show-stash-tags|
455 .. el:define-key:: c c
456 M-x notmuch-show-stash-cc
458 |docstring::notmuch-show-stash-cc|
460 .. el:define-key:: c d
461 M-x notmuch-show-stash-date
463 |docstring::notmuch-show-stash-date|
465 .. el:define-key:: c f
466 M-x notmuch-show-stash-from
468 |docstring::notmuch-show-stash-from|
470 .. el:define-key:: c i
471 M-x notmuch-show-stash-message-id
473 |docstring::notmuch-show-stash-message-id|
475 .. el:define-key:: c l
476 M-x notmuch-show-stash-mlarchive-link
478 |docstring::notmuch-show-stash-mlarchive-link|
480 .. el:define-key:: c s
481 M-x notmuch-show-stash-subject
483 |docstring::notmuch-show-stash-subject|
485 .. el:define-key:: c t
486 M-x notmuch-show-stash-to
488 |docstring::notmuch-show-stash-to|
490 .. el:define-key:: c ?
491 M-x notmuch-subkeymap-help
493 Show all available copying commands
495 .. _emacs-show-duplicates:
497 Dealing with duplicates
498 -----------------------
500 If there are multiple files with the same :mailheader:`Message-ID`
501 (see :any:`duplicate-files`), then :any:`notmuch-show` displays the
502 number of duplicates and identifies the current duplicate. In the
503 following example duplicate 3 of 5 is displayed.
508 M. Mustermann <max@example.com> (Sat, 30 Jul 2022 10:33:10 -0300) (inbox signed) 3/5
509 Subject: Re: Multiple files per message in emacs
510 To: notmuch@notmuchmail.org
513 M-x notmuch-show-choose-duplicate
515 |docstring::notmuch-show-choose-duplicate|
522 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
523 email archives. Each line in the buffer represents a single
524 message giving the relative date, the author, subject, and any
531 .. el:define-key:: <return>
533 Displays that message.
541 Move to previous message
545 Move to next matching message
549 Move to previous matching message
552 M-x notmuch-tree-toggle-order
554 |docstring::notmuch-tree-toggle-order|
557 M-x notmuch-tree-filter
559 Filter or LIMIT the current search results based on an additional query string
562 M-x notmuch-tree-filter-by-tag
564 Filter the current search results based on an additional tag
568 Toggle whether to show messages with excluded tags in search results.
577 Display full set of key bindings
579 As is the case with :ref:`notmuch-search`, the presentation of results
580 can be controlled by the variable ``notmuch-search-oldest-first``.
582 .. el:defcustom:: notmuch-tree-result-format
584 |docstring::notmuch-tree-result-format|
586 The following example shows how to optionally display recipients instead
587 of authors for sent mail (assuming the user is named Mustermann).
591 (defun -notmuch-authors-or-to (format-string result)
592 (let* ((headers (plist-get result :headers))
593 (to (plist-get headers :To))
594 (author (plist-get headers :From))
595 (face (if (plist-get result :match)
596 'notmuch-tree-match-author-face
597 'notmuch-tree-no-match-author-face)))
599 (format format-string
600 (if (string-match "Mustermann" author)
601 (concat "To:" (notmuch-tree-clean-address to))
605 (setq notmuch-tree-result-format
607 (-notmuch-authors-or-to . "%-20.20s")
613 See also :el:defcustom:`notmuch-search-result-format` and
614 :el:defcustom:`notmuch-unthreaded-result-format`.
616 .. _notmuch-tree-outline:
621 When this mode is set, each thread and subthread in the results
622 list is treated as a foldable section, with its first message as
625 The mode just makes available in the tree buffer all the
626 keybindings in info:emacs#Outline_Mode, and binds the following
629 .. el:define-key:: <tab>
631 Cycle visibility state of the current message's tree.
633 .. el:define-key:: <M-tab>
635 Cycle visibility state of all trees in the buffer.
637 The behaviour of this minor mode is affected by the following
638 customizable variables:
640 .. el:defcustom:: notmuch-tree-outline-enabled
642 |docstring::notmuch-tree-outline-enabled|
644 .. el:defcustom:: notmuch-tree-outline-visibility
646 |docstring::notmuch-tree-outline-visibility|
648 .. el:defcustom:: notmuch-tree-outline-auto-close
650 |docstring::notmuch-tree-outline-auto-close|
652 .. el:defcustom:: notmuch-tree-outline-open-on-next
654 |docstring::notmuch-tree-outline-open-on-next|
656 .. _notmuch-unthreaded:
661 ``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
662 each line corresponds to a single message, but no thread information
665 Keybindings are the same as :any:`notmuch-tree`.
667 .. el:defcustom:: notmuch-unthreaded-result-format
669 |docstring::notmuch-unthreaded-result-format|
671 See also :el:defcustom:`notmuch-search-result-format` and
672 :el:defcustom:`notmuch-tree-result-format`.
677 Several features are accessible from most places in notmuch through the
678 following key bindings:
682 Jump to saved searches using :ref:`notmuch-jump`.
686 Tagging operations using :ref:`notmuch-tag-jump`
688 .. el:define-key:: C-_
692 Undo previous tagging operation using :any:`notmuch-tag-undo`
699 Saved searches configured through :ref:`saved-searches` can
700 include a "shortcut key" that's accessible through notmuch-jump.
701 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
702 key of a saved search will immediately jump to that saved search. For
703 example, in the default configuration ``j i`` jumps immediately to the
704 inbox search. When you press ``j``, notmuch-jump shows the saved
705 searches and their shortcut keys in the mini-buffer.
707 .. _notmuch-tag-jump:
712 Tagging operations configured through ``notmuch-tagging-keys`` can
713 be accessed via :kbd:`k` in :ref:`notmuch-show`,
714 :ref:`notmuch-search` and :ref:`notmuch-tree`. With a
715 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
716 operations specified in ``notmuch-tagging-keys``; i.e. each
717 ``+tag`` is replaced by ``-tag`` and vice versa.
719 .. el:defcustom:: notmuch-tagging-keys
721 |docstring::notmuch-tagging-keys|
727 Each notmuch buffer supporting tagging operations (i.e. buffers in
728 :any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
729 :any:`notmuch-unthreaded` mode) keeps a local stack of tagging
730 operations. These can be undone via :any:`notmuch-tag-undo`. By default
731 this is bound to the usual Emacs keys for undo.
733 .. el:define-key:: C-_
738 |docstring::notmuch-tag-undo|
743 .. el:define-key:: M-x notmuch-cycle-notmuch-buffers
745 |docstring::notmuch-cycle-notmuch-buffers|
755 .. el:define-key:: M-x notmuch-poll
757 |docstring::notmuch-poll|
759 .. el:defcustom:: notmuch-poll-script
761 |docstring::notmuch-poll-script|
766 .. el:defcustom:: mail-user-agent
768 Emacs consults the variable :code:`mail-user-agent` to choose a mail
769 sending package for commands like :code:`report-emacs-bug` and
770 :code:`compose-mail`. To use ``notmuch`` for this, customize this
771 variable to the symbol :code:`notmuch-user-agent`.
773 .. el:defcustom:: message-dont-reply-to-names
775 When composing mail replies, Emacs's message mode uses the
776 variable :code:`message-dont-reply-to-names` to exclude
777 recipients matching a given collection of regular expressions
778 or satisfying an arbitrary predicate. Notmuch's MUA inherits
779 this standard mechanism and will honour your customization of
785 When Notmuch is loaded, it will read the ``notmuch-init-file``
786 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
787 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
788 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
789 suffix exist it will be read instead (just one of these, chosen in this
790 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
791 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
792 options, ``notmuch-init-file`` is not read.