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 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 --------------------------
105 Move to the next widget (button or text entry field)
108 Move to the previous widget.
111 Activate the current widget.
114 Refresh the buffer; mainly update the counts of messages for various
118 Import mail, See :ref:`importing`
124 Search the notmuch database using :ref:`notmuch-search`
127 Print notmuch version
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`.
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:
147 .. el:defcustom:: notmuch-saved-searches
149 The list of saved searches, including names, queries, and
150 additional per-query options.
152 .. el:defcustom:: notmuch-saved-search-sort-function
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’.
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`.
166 .. el:defcustom:: notmuch-hello-recent-searches-max
168 |docstring::notmuch-hello-recent-searches-max|
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
177 .. el:defcustom:: notmuch-hello-tag-list-make-query
179 Control how to construct a search (“virtual folder”) from a given
182 .. el:defcustom:: notmuch-hello-hide-tags
184 Which tags not to display at all.
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
196 By default the output approximates that of the command line See section
197 “Description” in notmuch search command.
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.
207 Move to previous line
210 Open thread on current line in :ref:`notmuch-show` mode
216 Display full set of key bindings
218 The presentation of results can be controlled by the following
221 .. el:defcustom:: notmuch-search-result-format
223 |docstring::notmuch-search-result-format|
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.
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.
235 (defun -notmuch-result-flags (format-string result)
236 (let ((tags-to-letters '(("flagged" . "!")
241 (tags (plist-get result :tags)))
242 (format format-string
243 (mapconcat (lambda (t2l)
244 (if (member (car t2l) tags)
247 tags-to-letters ""))))
249 (setq notmuch-search-result-format '((-notmuch-result-flags . "%s ")
252 ("authors" . "%-30s ")
256 See also :el:defcustom:`notmuch-tree-result-format` and
257 :el:defcustom:`notmuch-unthreaded-result-format`.
259 .. el:defcustom:: notmuch-search-oldest-first
261 Display the oldest threads at the top of the buffer
263 It is also possible to customize how the name of buffers containing
264 search results is formatted using the following variables:
266 .. el:defcustom:: notmuch-search-buffer-name-format
268 |docstring::notmuch-search-buffer-name-format|
270 .. el:defcustom:: notmuch-saved-search-buffer-name-format
272 |docstring::notmuch-saved-search-buffer-name-format|
280 ``notmuch-show-mode`` is used to display a single thread of email from
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.
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).
300 Move to previous message (or start of current message)
303 Move to next matching message
306 Move to previous matching message
309 Add or remove arbitrary tags from the current message.
312 |docstring::notmuch-show-toggle-elide-non-matching|
315 Display full set of key bindings
317 Display of messages can be controlled by the following variables; see also :ref:`show-large`.
319 .. el:defcustom:: notmuch-message-headers
321 |docstring::notmuch-message-headers|
323 .. el:defcustom:: notmuch-message-headers-visible
325 |docstring::notmuch-message-headers-visible|
327 .. el:defcustom:: notmuch-show-header-line
329 |docstring::notmuch-show-header-line|
331 .. el:defcustom:: notmuch-multipart/alternative-discouraged
333 Which mime types to hide by default for multipart messages.
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`.
343 (defun my--determine-discouraged (msg)
344 (let* ((headers (plist-get msg :headers))
345 (from (or (plist-get headers :From) "")))
347 ((string-match "whatever@example.com" from)
350 (list "text/html" "multipart/related")))))
354 Dealing with large messages and threads
355 ---------------------------------------
357 If you are finding :ref:`notmuch-show` is annoyingly slow displaying
358 large messages, you can customize
359 :el:defcustom:`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 :el:defcustom:`notmuch-show-depth-limit`,
368 :el:defcustom:`notmuch-show-height-limit` and
369 :el:defcustom:`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.
373 .. el:defcustom:: notmuch-show-depth-limit
375 |docstring::notmuch-show-depth-limit|
377 .. el:defcustom:: notmuch-show-height-limit
379 |docstring::notmuch-show-height-limit|
381 .. el:defcustom:: notmuch-show-max-text-part-size
383 |docstring::notmuch-show-max-text-part-size|
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`.
395 ``c F`` ``notmuch-show-stash-filename``
396 |docstring::notmuch-show-stash-filename|
398 ``c G`` ``notmuch-show-stash-git-send-email``
399 |docstring::notmuch-show-stash-git-send-email|
401 ``c I`` ``notmuch-show-stash-message-id-stripped``
402 |docstring::notmuch-show-stash-message-id-stripped|
404 ``c L`` ``notmuch-show-stash-mlarchive-link-and-go``
405 |docstring::notmuch-show-stash-mlarchive-link-and-go|
407 ``c T`` ``notmuch-show-stash-tags``
408 |docstring::notmuch-show-stash-tags|
410 ``c c`` ``notmuch-show-stash-cc``
411 |docstring::notmuch-show-stash-cc|
413 ``c d`` ``notmuch-show-stash-date``
414 |docstring::notmuch-show-stash-date|
416 ``c f`` ``notmuch-show-stash-from``
417 |docstring::notmuch-show-stash-from|
419 ``c i`` ``notmuch-show-stash-message-id``
420 |docstring::notmuch-show-stash-message-id|
422 ``c l`` ``notmuch-show-stash-mlarchive-link``
423 |docstring::notmuch-show-stash-mlarchive-link|
425 ``c s`` ``notmuch-show-stash-subject``
426 |docstring::notmuch-show-stash-subject|
428 ``c t`` ``notmuch-show-stash-to``
429 |docstring::notmuch-show-stash-to|
432 Show all available copying commands
434 .. _emacs-show-duplicates:
436 Dealing with duplicates
437 -----------------------
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.
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
452 M-x notmuch-show-choose-duplicate
454 |docstring::notmuch-show-choose-duplicate|
461 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
462 email archives. Each line in the buffer represents a single
463 message giving the relative date, the author, subject, and any
470 Displays that message.
476 Move to previous message
479 Move to next matching message
482 Move to previous matching message
484 ``o`` ``notmuch-tree-toggle-order``
485 |docstring::notmuch-tree-toggle-order|
487 ``l`` ``notmuch-tree-filter``
488 Filter or LIMIT the current search results based on an additional query string
490 ``t`` ``notmuch-tree-filter-by-tag``
491 Filter the current search results based on an additional tag
498 Display full set of key bindings
500 As is the case with :ref:`notmuch-search`, the presentation of results
501 can be controlled by the variable ``notmuch-search-oldest-first``.
503 .. el:defcustom:: notmuch-tree-result-format
505 |docstring::notmuch-tree-result-format|
507 The following example shows how to optionally display recipients instead
508 of authors for sent mail (assuming the user is named Mustermann).
512 (defun -notmuch-authors-or-to (format-string result)
513 (let* ((headers (plist-get result :headers))
514 (to (plist-get headers :To))
515 (author (plist-get headers :From))
516 (face (if (plist-get result :match)
517 'notmuch-tree-match-author-face
518 'notmuch-tree-no-match-author-face)))
520 (format format-string
521 (if (string-match "Mustermann" author)
522 (concat "To:" (notmuch-tree-clean-address to))
526 (setq notmuch-tree-result-format
528 (-notmuch-authors-or-to . "%-20.20s")
534 See also :el:defcustom:`notmuch-search-result-format` and
535 :el:defcustom:`notmuch-unthreaded-result-format`.
538 .. _notmuch-unthreaded:
543 ``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
544 each line corresponds to a single message, but no thread information
547 Keybindings are the same as :any:`notmuch-tree`.
549 .. el:defcustom:: notmuch-unthreaded-result-format
551 |docstring::notmuch-unthreaded-result-format|
553 See also :el:defcustom:`notmuch-search-result-format` and
554 :el:defcustom:`notmuch-tree-result-format`.
559 Several features are accessible from most places in notmuch through the
560 following key bindings:
563 Jump to saved searches using :ref:`notmuch-jump`.
566 Tagging operations using :ref:`notmuch-tag-jump`
568 ``C-_`` ``C-/`` ``C-x u``: Undo previous tagging operation using :any:`notmuch-tag-undo`
575 Saved searches configured through :ref:`saved-searches` can
576 include a "shortcut key" that's accessible through notmuch-jump.
577 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
578 key of a saved search will immediately jump to that saved search. For
579 example, in the default configuration ``j i`` jumps immediately to the
580 inbox search. When you press ``j``, notmuch-jump shows the saved
581 searches and their shortcut keys in the mini-buffer.
583 .. _notmuch-tag-jump:
588 Tagging operations configured through ``notmuch-tagging-keys`` can
589 be accessed via :kbd:`k` in :ref:`notmuch-show`,
590 :ref:`notmuch-search` and :ref:`notmuch-tree`. With a
591 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
592 operations specified in ``notmuch-tagging-keys``; i.e. each
593 ``+tag`` is replaced by ``-tag`` and vice versa.
595 .. el:defcustom:: notmuch-tagging-keys
597 |docstring::notmuch-tagging-keys|
603 Each notmuch buffer supporting tagging operations (i.e buffers in
604 :any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
605 :any:`notmuch-unthreaded` mode) keeps a local stack of tagging
606 operations. These can be undone via :any:`notmuch-tag-undo`. By default
607 this is bound to the usual Emacs keys for undo.
609 .. el:define-key:: C-_
614 |docstring::notmuch-tag-undo|
619 .. el:define-key:: M-x notmuch-cycle-notmuch-buffers
621 |docstring::notmuch-cycle-notmuch-buffers|
631 .. el:define-key:: M-x notmuch-poll
633 |docstring::notmuch-poll|
635 .. el:defcustom:: notmuch-poll-script
637 |docstring::notmuch-poll-script|
642 .. el:defcustom:: mail-user-agent
644 Emacs consults the variable :code:`mail-user-agent` to choose a mail
645 sending package for commands like :code:`report-emacs-bug` and
646 :code:`compose-mail`. To use ``notmuch`` for this, customize this
647 variable to the symbol :code:`notmuch-user-agent`.
649 .. el:defcustom:: message-dont-reply-to-names
651 When composing mail replies, Emacs's message mode uses the
652 variable :code:`message-dont-reply-to-names` to exclude
653 recipients matching a given collection of regular expressions
654 or satisfying an arbitrary predicate. Notmuch's MUA inherits
655 this standard mechanism and will honour your customization of
661 When Notmuch is loaded, it will read the ``notmuch-init-file``
662 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
663 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
664 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
665 suffix exist it will be read instead (just one of these, chosen in this
666 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
667 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
668 options, ``notmuch-init-file`` is not read.