8 This manual covers only the Emacs interface to Notmuch. For information
9 on the command line interface, see section “Description” in the Notmuch
10 Manual Pages. To save typing, we will sometimes use *notmuch* in this
11 manual to refer to the Emacs interface to Notmuch. When this distinction
12 is important, we’ll refer to the Emacs interface as
15 Notmuch-emacs is highly customizable via the the Emacs customization
16 framework (or just by setting the appropriate variables). We try to
17 point out relevant variables in this manual, but in order to avoid
18 duplication of information, you can usually find the most detailed
19 description in the variables' docstring.
28 ``notmuch-hello`` is the main entry point for Notmuch. You can start it
29 with ``M-x notmuch`` or ``M-x notmuch-hello``. The startup screen looks
30 something like the following. There are some hints at the bottom of the
31 screen. There are three main parts to the notmuch-hello screen,
32 discussed below. The **bold** text indicates buttons you can click with
33 a mouse or by positioning the cursor and pressing ``<return>``
35 | Welcome to **notmuch** You have 52 messages.
37 | Saved searches: **[edit]**
39 | 52 **inbox** 52 **unread**
41 | Search: ____________________________________
43 | All tags: **[show]**
45 | Hit \`?' for context-sensitive help in any Notmuch screen.
46 | Customize Notmuch or this page.
48 You can change the overall appearance of the notmuch-hello screen by
49 customizing the variables
51 :index:`notmuch-hello-sections`
52 |docstring::notmuch-hello-sections|
54 :index:`notmuch-hello-thousands-separator`
55 |docstring::notmuch-hello-thousands-separator|
57 :index:`notmuch-show-logo`
58 |docstring::notmuch-show-logo|
60 :index:`!notmuch-column-control`
61 Controls the number of columns for saved searches/tags in notmuch view.
63 This variable has three potential types of values:
67 Automatically calculate the number of columns possible based
68 on the tags to be shown and the window width.
70 .. describe:: integer <n>
72 A lower bound on the number of characters that will
73 be used to display each column.
75 .. describe:: float <f>
77 A fraction of the window width that is the lower bound on the
78 number of characters that should be used for each column.
82 - if you would like two columns of tags, set this to 0.5.
84 - if you would like a single column of tags, set this to 1.0.
86 - if you would like tags to be 30 characters wide, set this to 30.
88 - if you don't want to worry about all of this nonsense, leave
92 notmuch-hello key bindings
93 --------------------------
96 Move to the next widget (button or text entry field)
99 Move to the previous widget.
102 Activate the current widget.
105 Refresh the buffer; mainly update the counts of messages for various
109 Import mail, See :ref:`importing`
115 Search the notmuch database using :ref:`notmuch-search`
118 Print notmuch version
128 Since notmuch is entirely search-based, it's often useful to organize
129 mail around common searches. To facilitate this, the first section of
130 notmuch-hello presents a customizable set of saved searches. Saved
131 searches can also be accessed from anywhere in notmuch by pressing
132 ``j`` to access :ref:`notmuch-jump`.
134 The saved searches default to various common searches such as
135 ``tag:inbox`` to access the inbox and ``tag:unread`` to access all
136 unread mail, but there are several options for customization:
138 :index:`notmuch-saved-searches`
139 The list of saved searches, including names, queries, and
140 additional per-query options.
142 :index:`notmuch-saved-search-sort-function`
143 This variable controls how saved searches should be sorted. A value
144 of ``nil`` displays the saved searches in the order they are stored
145 in ‘notmuch-saved-searches’.
147 :index:`notmuch-column-control`
148 Controls the number of columns for displaying saved-searches/tags
153 The search box lets the user enter a Notmuch query. See section
154 “Description” in Notmuch Query Syntax, for more info on Notmuch query
155 syntax. A history of recent searches is also displayed by default. The
156 latter is controlled by the variable :index:`notmuch-hello-recent-searches-max`.
161 One special kind of saved search provided by default is for each
162 individual tag defined in the database. This can be controlled via the
165 :index:`notmuch-hello-tag-list-make-query`
166 Control how to construct a search (“virtual folder”) from a given
169 :index:`notmuch-hello-hide-tags`
170 Which tags not to display at all.
172 :index:`notmuch-column-control`
173 Controls the number of columns for displaying saved-searches/tags
180 ``notmuch-search-mode`` is used to display the results from executing
181 a query via ``notmuch-search``. The syntax for these queries is the
182 the same as :ref:`saved-searches`. For details of this syntax see
183 info:notmuch-search-terms
185 By default the output approximates that of the command line See section
186 “Description” in notmuch search command.
188 The main purpose of the ``notmuch-search-mode`` buffer is to act as a
189 menu of results that the user can explore further by pressing
190 ``<return>`` on the appropriate line.
196 Move to previous line
199 Open thread on current line in :ref:`notmuch-show` mode
205 Display full set of key bindings
207 The presentation of results can be controlled by the following
210 :index:`notmuch-search-result-format`
211 Control how each thread of messages is presented in the
212 ``notmuch-show-mode`` buffer
214 :index:`notmuch-search-oldest-first`
215 Display the oldest threads at the top of the buffer
217 It is also possible to customize how the name of buffers containing
218 search results is formatted using the following variables:
220 :index:`notmuch-search-buffer-name-format`
221 |docstring::notmuch-search-buffer-name-format|
223 :index:`notmuch-saved-search-buffer-name-format`
224 |docstring::notmuch-saved-search-buffer-name-format|
232 ``notmuch-show-mode`` is used to display a single thread of email from
235 By default, various components of email messages, (citations,
236 signatures, already-read messages), are hidden. You can make
237 these parts visible by clicking with the mouse button or by
238 pressing RET after positioning the cursor on a hidden part.
241 Scroll the current message (if necessary),
242 advance to the next message, or advance to the next thread (if
243 already on the last message of a thread).
252 Move to previous message (or start of current message)
255 Move to next matching message
258 Move to previous matching message
261 Add or remove arbitrary tags from the current message.
264 |docstring::notmuch-show-toggle-elide-non-matching|
267 Display full set of key bindings
269 Display of messages can be controlled by the following variables; see also :ref:`show-large`.
271 :index:`notmuch-message-headers`
272 |docstring::notmuch-message-headers|
274 :index:`notmuch-message-headers-visible`
275 |docstring::notmuch-message-headers-visible|
277 :index:`notmuch-show-header-line`
278 |docstring::notmuch-show-header-line|
280 :index:`notmuch-multipart/alternative-discouraged`
282 Which mime types to hide by default for multipart messages.
284 Can either be a list of mime types (as strings) or a function
285 mapping a plist representing the current message to such a list.
286 The following example function would discourage `text/html` and
287 `multipart/related` generally, but discourage `text/plain` should
288 the message be sent from `whatever@example.com`.
292 (defun my--determine-discouraged (msg)
293 (let* ((headers (plist-get msg :headers))
294 (from (or (plist-get headers :From) "")))
296 ((string-match "whatever@example.com" from)
299 (list "text/html" "multipart/related")))))
303 Dealing with large messages and threads
304 ---------------------------------------
306 If you are finding :ref:`notmuch-show` is annoyingly slow displaying
307 large messages, you can customize
308 :index:`notmuch-show-max-text-part-size`. If you want to speed up the
309 display of large threads (with or without large messages), there are
310 several options. First, you can display the same query in one of the
311 other modes. :ref:`notmuch-unthreaded` is the most robust for
312 extremely large queries, but :ref:`notmuch-tree` is also be faster
313 than :ref:`notmuch-show` in general, since it only renders a single
314 message a time. If you prefer to stay with the rendered thread
315 ("conversation") view of :ref:`notmuch-show`, you can customize the
316 variables :index:`notmuch-show-depth-limit`,
317 :index:`notmuch-show-height-limit` and
318 :index:`notmuch-show-max-text-part-size` to limit the amount of
319 rendering done initially. Note that these limits are implicitly
320 *OR*-ed together, and combinations might have surprising effects.
322 :index:`notmuch-show-depth-limit`
323 |docstring::notmuch-show-depth-limit|
325 :index:`notmuch-show-height-limit`
326 |docstring::notmuch-show-height-limit|
328 :index:`notmuch-show-max-text-part-size`
329 |docstring::notmuch-show-max-text-part-size|
336 You can use the usually Emacs ways of copying text to the kill-ring,
337 but notmuch also provides some shortcuts. These keys are available in
338 :ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available
339 in :ref:`notmuch-search`.
341 ``c F`` ``notmuch-show-stash-filename``
342 |docstring::notmuch-show-stash-filename|
344 ``c G`` ``notmuch-show-stash-git-send-email``
345 |docstring::notmuch-show-stash-git-send-email|
347 ``c I`` ``notmuch-show-stash-message-id-stripped``
348 |docstring::notmuch-show-stash-message-id-stripped|
350 ``c L`` ``notmuch-show-stash-mlarchive-link-and-go``
351 |docstring::notmuch-show-stash-mlarchive-link-and-go|
353 ``c T`` ``notmuch-show-stash-tags``
354 |docstring::notmuch-show-stash-tags|
356 ``c c`` ``notmuch-show-stash-cc``
357 |docstring::notmuch-show-stash-cc|
359 ``c d`` ``notmuch-show-stash-date``
360 |docstring::notmuch-show-stash-date|
362 ``c f`` ``notmuch-show-stash-from``
363 |docstring::notmuch-show-stash-from|
365 ``c i`` ``notmuch-show-stash-message-id``
366 |docstring::notmuch-show-stash-message-id|
368 ``c l`` ``notmuch-show-stash-mlarchive-link``
369 |docstring::notmuch-show-stash-mlarchive-link|
371 ``c s`` ``notmuch-show-stash-subject``
372 |docstring::notmuch-show-stash-subject|
374 ``c t`` ``notmuch-show-stash-to``
375 |docstring::notmuch-show-stash-to|
378 Show all available copying commands
385 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
386 email archives. Each line in the buffer represents a single
387 message giving the relative date, the author, subject, and any
394 Displays that message.
400 Move to previous message
403 Move to next matching message
406 Move to previous matching message
408 ``o`` ``notmuch-tree-toggle-order``
409 |docstring::notmuch-tree-toggle-order|
411 ``l`` ``notmuch-tree-filter``
412 Filter or LIMIT the current search results based on an additional query string
414 ``t`` ``notmuch-tree-filter-by-tag``
415 Filter the current search results based on an additional tag
422 Display full set of key bindings
424 As is the case with :ref:`notmuch-search`, the presentation of results
425 can be controlled by the variable ``notmuch-search-oldest-first``.
427 .. _notmuch-unthreaded:
432 ``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
433 each line corresponds to a single message, but no thread information
436 Keybindings are the same as :any:`notmuch-tree`.
441 Several features are accessible from most places in notmuch through the
442 following key bindings:
445 Jump to saved searches using :ref:`notmuch-jump`.
448 Tagging operations using :ref:`notmuch-tag-jump`
450 ``C-_`` ``C-/`` ``C-x u``: Undo previous tagging operation using :ref:`notmuch-tag-undo`
457 Saved searches configured through :ref:`saved-searches` can
458 include a "shortcut key" that's accessible through notmuch-jump.
459 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
460 key of a saved search will immediately jump to that saved search. For
461 example, in the default configuration ``j i`` jumps immediately to the
462 inbox search. When you press ``j``, notmuch-jump shows the saved
463 searches and their shortcut keys in the mini-buffer.
465 .. _notmuch-tag-jump:
470 Tagging operations configured through ``notmuch-tagging-keys`` can
471 be accessed via :kbd:`k` in :ref:`notmuch-show`,
472 :ref:`notmuch-search` and :ref:`notmuch-tree`. With a
473 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
474 operations specified in ``notmuch-tagging-keys``; i.e. each
475 ``+tag`` is replaced by ``-tag`` and vice versa.
477 :index:`notmuch-tagging-keys`
479 |docstring::notmuch-tagging-keys|
481 .. _notmuch-tag-undo:
486 Each notmuch buffer supporting tagging operations (i.e buffers in
487 :any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
488 :any:`notmuch-unthreaded` mode) keeps a local stack of tagging
489 operations. These can be undone via ``notmuch-tag-undo``. By default
490 this is bound to the usual Emacs keys for undo.
492 :index:`notmuch-tag-undo`
494 |docstring::notmuch-tag-undo|
499 :index:`notmuch-cycle-notmuch-buffers`
500 |docstring::notmuch-cycle-notmuch-buffers|
510 :index:`notmuch-poll`
511 |docstring::notmuch-poll|
513 :index:`notmuch-poll-script`
514 |docstring::notmuch-poll-script|
519 :index:`mail-user-agent`
521 Emacs consults the variable :code:`mail-user-agent` to choose a mail
522 sending package for commands like :code:`report-emacs-bug` and
523 :code:`compose-mail`. To use ``notmuch`` for this, customize this
524 variable to the symbol :code:`notmuch-user-agent`.
526 :index:`message-dont-reply-to-names`
528 When composing mail replies, Emacs's message mode uses the
529 variable :code:`message-dont-reply-to-names` to exclude
530 recipients matching a given collection of regular expressions
531 or satisfying an arbitrary predicate. Notmuch's MUA inherits
532 this standard mechanism and will honour your customization of
538 When Notmuch is loaded, it will read the ``notmuch-init-file``
539 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
540 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
541 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
542 suffix exist it will be read instead (just one of these, chosen in this
543 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
544 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
545 options, ``notmuch-init-file`` is not read.