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 .. emacsvar:: notmuch-hello-sections
55 |docstring::notmuch-hello-sections|
57 .. emacsvar:: notmuch-hello-thousands-separator
59 |docstring::notmuch-hello-thousands-separator|
61 .. emacsvar:: notmuch-show-logo
63 |docstring::notmuch-show-logo|
65 .. emacsvar:: 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
98 notmuch-hello key bindings
99 --------------------------
102 Move to the next widget (button or text entry field)
105 Move to the previous widget.
108 Activate the current widget.
111 Refresh the buffer; mainly update the counts of messages for various
115 Import mail, See :ref:`importing`
121 Search the notmuch database using :ref:`notmuch-search`
124 Print notmuch version
134 Since notmuch is entirely search-based, it's often useful to organize
135 mail around common searches. To facilitate this, the first section of
136 notmuch-hello presents a customizable set of saved searches. Saved
137 searches can also be accessed from anywhere in notmuch by pressing
138 ``j`` to access :ref:`notmuch-jump`.
140 The saved searches default to various common searches such as
141 ``tag:inbox`` to access the inbox and ``tag:unread`` to access all
142 unread mail, but there are several options for customization:
144 .. emacsvar:: notmuch-saved-searches
146 The list of saved searches, including names, queries, and
147 additional per-query options.
149 .. emacsvar:: notmuch-saved-search-sort-function
151 This variable controls how saved searches should be sorted. A value
152 of ``nil`` displays the saved searches in the order they are stored
153 in ‘notmuch-saved-searches’.
158 The search box lets the user enter a Notmuch query. See section
159 “Description” in Notmuch Query Syntax, for more info on Notmuch query
160 syntax. A history of recent searches is also displayed by default. The
161 latter is controlled by the variable `notmuch-hello-recent-searches-max`.
163 .. emacsvar:: notmuch-hello-recent-searches-max
165 |docstring::notmuch-hello-recent-searches-max|
170 One special kind of saved search provided by default is for each
171 individual tag defined in the database. This can be controlled via the
174 .. emacsvar:: notmuch-hello-tag-list-make-query
176 Control how to construct a search (“virtual folder”) from a given
179 .. emacsvar:: notmuch-hello-hide-tags
181 Which tags not to display at all.
188 ``notmuch-search-mode`` is used to display the results from executing
189 a query via ``notmuch-search``. The syntax for these queries is the
190 the same as :ref:`saved-searches`. For details of this syntax see
191 info:notmuch-search-terms
193 By default the output approximates that of the command line See section
194 “Description” in notmuch search command.
196 The main purpose of the ``notmuch-search-mode`` buffer is to act as a
197 menu of results that the user can explore further by pressing
198 ``<return>`` on the appropriate line.
204 Move to previous line
207 Open thread on current line in :ref:`notmuch-show` mode
213 Display full set of key bindings
215 The presentation of results can be controlled by the following
218 .. emacsvar:: notmuch-search-result-format
220 Control how each thread of messages is presented in the
221 ``notmuch-show-mode`` buffer
223 .. emacsvar:: notmuch-search-oldest-first
225 Display the oldest threads at the top of the buffer
227 It is also possible to customize how the name of buffers containing
228 search results is formatted using the following variables:
230 .. emacsvar:: notmuch-search-buffer-name-format
232 |docstring::notmuch-search-buffer-name-format|
234 .. emacsvar:: notmuch-saved-search-buffer-name-format
236 |docstring::notmuch-saved-search-buffer-name-format|
244 ``notmuch-show-mode`` is used to display a single thread of email from
247 By default, various components of email messages, (citations,
248 signatures, already-read messages), are hidden. You can make
249 these parts visible by clicking with the mouse button or by
250 pressing RET after positioning the cursor on a hidden part.
253 Scroll the current message (if necessary),
254 advance to the next message, or advance to the next thread (if
255 already on the last message of a thread).
264 Move to previous message (or start of current message)
267 Move to next matching message
270 Move to previous matching message
273 Add or remove arbitrary tags from the current message.
276 |docstring::notmuch-show-toggle-elide-non-matching|
279 Display full set of key bindings
281 Display of messages can be controlled by the following variables; see also :ref:`show-large`.
283 .. emacsvar:: notmuch-message-headers
285 |docstring::notmuch-message-headers|
287 .. emacsvar:: notmuch-message-headers-visible
289 |docstring::notmuch-message-headers-visible|
291 .. emacsvar:: notmuch-show-header-line
293 |docstring::notmuch-show-header-line|
295 .. emacsvar:: notmuch-multipart/alternative-discouraged
297 Which mime types to hide by default for multipart messages.
299 Can either be a list of mime types (as strings) or a function
300 mapping a plist representing the current message to such a list.
301 The following example function would discourage `text/html` and
302 `multipart/related` generally, but discourage `text/plain` should
303 the message be sent from `whatever@example.com`.
307 (defun my--determine-discouraged (msg)
308 (let* ((headers (plist-get msg :headers))
309 (from (or (plist-get headers :From) "")))
311 ((string-match "whatever@example.com" from)
314 (list "text/html" "multipart/related")))))
318 Dealing with large messages and threads
319 ---------------------------------------
321 If you are finding :ref:`notmuch-show` is annoyingly slow displaying
322 large messages, you can customize
323 :emacsvar:`notmuch-show-max-text-part-size`. If you want to speed up the
324 display of large threads (with or without large messages), there are
325 several options. First, you can display the same query in one of the
326 other modes. :ref:`notmuch-unthreaded` is the most robust for
327 extremely large queries, but :ref:`notmuch-tree` is also be faster
328 than :ref:`notmuch-show` in general, since it only renders a single
329 message a time. If you prefer to stay with the rendered thread
330 ("conversation") view of :ref:`notmuch-show`, you can customize the
331 variables :emacsvar:`notmuch-show-depth-limit`,
332 :emacsvar:`notmuch-show-height-limit` and
333 :emacsvar:`notmuch-show-max-text-part-size` to limit the amount of
334 rendering done initially. Note that these limits are implicitly
335 *OR*-ed together, and combinations might have surprising effects.
337 .. emacsvar:: notmuch-show-depth-limit
339 |docstring::notmuch-show-depth-limit|
341 .. emacsvar:: notmuch-show-height-limit
343 |docstring::notmuch-show-height-limit|
345 .. emacsvar:: notmuch-show-max-text-part-size
347 |docstring::notmuch-show-max-text-part-size|
354 You can use the usually Emacs ways of copying text to the kill-ring,
355 but notmuch also provides some shortcuts. These keys are available in
356 :ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available
357 in :ref:`notmuch-search`.
359 ``c F`` ``notmuch-show-stash-filename``
360 |docstring::notmuch-show-stash-filename|
362 ``c G`` ``notmuch-show-stash-git-send-email``
363 |docstring::notmuch-show-stash-git-send-email|
365 ``c I`` ``notmuch-show-stash-message-id-stripped``
366 |docstring::notmuch-show-stash-message-id-stripped|
368 ``c L`` ``notmuch-show-stash-mlarchive-link-and-go``
369 |docstring::notmuch-show-stash-mlarchive-link-and-go|
371 ``c T`` ``notmuch-show-stash-tags``
372 |docstring::notmuch-show-stash-tags|
374 ``c c`` ``notmuch-show-stash-cc``
375 |docstring::notmuch-show-stash-cc|
377 ``c d`` ``notmuch-show-stash-date``
378 |docstring::notmuch-show-stash-date|
380 ``c f`` ``notmuch-show-stash-from``
381 |docstring::notmuch-show-stash-from|
383 ``c i`` ``notmuch-show-stash-message-id``
384 |docstring::notmuch-show-stash-message-id|
386 ``c l`` ``notmuch-show-stash-mlarchive-link``
387 |docstring::notmuch-show-stash-mlarchive-link|
389 ``c s`` ``notmuch-show-stash-subject``
390 |docstring::notmuch-show-stash-subject|
392 ``c t`` ``notmuch-show-stash-to``
393 |docstring::notmuch-show-stash-to|
396 Show all available copying commands
403 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
404 email archives. Each line in the buffer represents a single
405 message giving the relative date, the author, subject, and any
412 Displays that message.
418 Move to previous message
421 Move to next matching message
424 Move to previous matching message
426 ``o`` ``notmuch-tree-toggle-order``
427 |docstring::notmuch-tree-toggle-order|
429 ``l`` ``notmuch-tree-filter``
430 Filter or LIMIT the current search results based on an additional query string
432 ``t`` ``notmuch-tree-filter-by-tag``
433 Filter the current search results based on an additional tag
440 Display full set of key bindings
442 As is the case with :ref:`notmuch-search`, the presentation of results
443 can be controlled by the variable ``notmuch-search-oldest-first``.
445 .. _notmuch-unthreaded:
450 ``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
451 each line corresponds to a single message, but no thread information
454 Keybindings are the same as :any:`notmuch-tree`.
459 Several features are accessible from most places in notmuch through the
460 following key bindings:
463 Jump to saved searches using :ref:`notmuch-jump`.
466 Tagging operations using :ref:`notmuch-tag-jump`
468 ``C-_`` ``C-/`` ``C-x u``: Undo previous tagging operation using :ref:`notmuch-tag-undo`
475 Saved searches configured through :ref:`saved-searches` can
476 include a "shortcut key" that's accessible through notmuch-jump.
477 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
478 key of a saved search will immediately jump to that saved search. For
479 example, in the default configuration ``j i`` jumps immediately to the
480 inbox search. When you press ``j``, notmuch-jump shows the saved
481 searches and their shortcut keys in the mini-buffer.
483 .. _notmuch-tag-jump:
488 Tagging operations configured through ``notmuch-tagging-keys`` can
489 be accessed via :kbd:`k` in :ref:`notmuch-show`,
490 :ref:`notmuch-search` and :ref:`notmuch-tree`. With a
491 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
492 operations specified in ``notmuch-tagging-keys``; i.e. each
493 ``+tag`` is replaced by ``-tag`` and vice versa.
495 .. emacsvar:: notmuch-tagging-keys
497 |docstring::notmuch-tagging-keys|
499 .. _notmuch-tag-undo:
504 Each notmuch buffer supporting tagging operations (i.e buffers in
505 :any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
506 :any:`notmuch-unthreaded` mode) keeps a local stack of tagging
507 operations. These can be undone via :emacscmd:`notmuch-tag-undo`. By default
508 this is bound to the usual Emacs keys for undo.
510 .. emacscmd:: notmuch-tag-undo
512 |docstring::notmuch-tag-undo|
517 .. emacscmd:: notmuch-cycle-notmuch-buffers
519 |docstring::notmuch-cycle-notmuch-buffers|
529 .. emacscmd:: notmuch-poll
531 |docstring::notmuch-poll|
533 .. emacsvar:: notmuch-poll-script
535 |docstring::notmuch-poll-script|
540 .. emacsvar:: mail-user-agent
542 Emacs consults the variable :code:`mail-user-agent` to choose a mail
543 sending package for commands like :code:`report-emacs-bug` and
544 :code:`compose-mail`. To use ``notmuch`` for this, customize this
545 variable to the symbol :code:`notmuch-user-agent`.
547 .. emacsvar:: message-dont-reply-to-names
549 When composing mail replies, Emacs's message mode uses the
550 variable :code:`message-dont-reply-to-names` to exclude
551 recipients matching a given collection of regular expressions
552 or satisfying an arbitrary predicate. Notmuch's MUA inherits
553 this standard mechanism and will honour your customization of
559 When Notmuch is loaded, it will read the ``notmuch-init-file``
560 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
561 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
562 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
563 suffix exist it will be read instead (just one of these, chosen in this
564 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
565 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
566 options, ``notmuch-init-file`` is not read.