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 :index:`notmuch-hello-sections`
54 |docstring::notmuch-hello-sections|
56 :index:`notmuch-hello-thousands-separator`
57 |docstring::notmuch-hello-thousands-separator|
59 :index:`notmuch-show-logo`
60 |docstring::notmuch-show-logo|
62 :index:`!notmuch-column-control`
63 Controls the number of columns for saved searches/tags in notmuch view.
65 This variable has three potential types of values:
69 Automatically calculate the number of columns possible based
70 on the tags to be shown and the window width.
72 .. describe:: integer <n>
74 A lower bound on the number of characters that will
75 be used to display each column.
77 .. describe:: float <f>
79 A fraction of the window width that is the lower bound on the
80 number of characters that should be used for each column.
84 - if you would like two columns of tags, set this to 0.5.
86 - if you would like a single column of tags, set this to 1.0.
88 - if you would like tags to be 30 characters wide, set this to 30.
90 - if you don't want to worry about all of this nonsense, leave
94 notmuch-hello key bindings
95 --------------------------
98 Move to the next widget (button or text entry field)
101 Move to the previous widget.
104 Activate the current widget.
107 Refresh the buffer; mainly update the counts of messages for various
111 Import mail, See :ref:`importing`
117 Search the notmuch database using :ref:`notmuch-search`
120 Print notmuch version
130 Since notmuch is entirely search-based, it's often useful to organize
131 mail around common searches. To facilitate this, the first section of
132 notmuch-hello presents a customizable set of saved searches. Saved
133 searches can also be accessed from anywhere in notmuch by pressing
134 ``j`` to access :ref:`notmuch-jump`.
136 The saved searches default to various common searches such as
137 ``tag:inbox`` to access the inbox and ``tag:unread`` to access all
138 unread mail, but there are several options for customization:
140 :index:`notmuch-saved-searches`
141 The list of saved searches, including names, queries, and
142 additional per-query options.
144 :index:`notmuch-saved-search-sort-function`
145 This variable controls how saved searches should be sorted. A value
146 of ``nil`` displays the saved searches in the order they are stored
147 in ‘notmuch-saved-searches’.
149 :index:`notmuch-column-control`
150 Controls the number of columns for displaying saved-searches/tags
155 The search box lets the user enter a Notmuch query. See section
156 “Description” in Notmuch Query Syntax, for more info on Notmuch query
157 syntax. A history of recent searches is also displayed by default. The
158 latter is controlled by the variable :index:`notmuch-hello-recent-searches-max`.
163 One special kind of saved search provided by default is for each
164 individual tag defined in the database. This can be controlled via the
167 :index:`notmuch-hello-tag-list-make-query`
168 Control how to construct a search (“virtual folder”) from a given
171 :index:`notmuch-hello-hide-tags`
172 Which tags not to display at all.
174 :index:`notmuch-column-control`
175 Controls the number of columns for displaying saved-searches/tags
182 ``notmuch-search-mode`` is used to display the results from executing
183 a query via ``notmuch-search``. The syntax for these queries is the
184 the same as :ref:`saved-searches`. For details of this syntax see
185 info:notmuch-search-terms
187 By default the output approximates that of the command line See section
188 “Description” in notmuch search command.
190 The main purpose of the ``notmuch-search-mode`` buffer is to act as a
191 menu of results that the user can explore further by pressing
192 ``<return>`` on the appropriate line.
198 Move to previous line
201 Open thread on current line in :ref:`notmuch-show` mode
207 Display full set of key bindings
209 The presentation of results can be controlled by the following
212 :index:`notmuch-search-result-format`
213 Control how each thread of messages is presented in the
214 ``notmuch-show-mode`` buffer
216 :index:`notmuch-search-oldest-first`
217 Display the oldest threads at the top of the buffer
219 It is also possible to customize how the name of buffers containing
220 search results is formatted using the following variables:
222 :index:`notmuch-search-buffer-name-format`
223 |docstring::notmuch-search-buffer-name-format|
225 :index:`notmuch-saved-search-buffer-name-format`
226 |docstring::notmuch-saved-search-buffer-name-format|
234 ``notmuch-show-mode`` is used to display a single thread of email from
237 By default, various components of email messages, (citations,
238 signatures, already-read messages), are hidden. You can make
239 these parts visible by clicking with the mouse button or by
240 pressing RET after positioning the cursor on a hidden part.
243 Scroll the current message (if necessary),
244 advance to the next message, or advance to the next thread (if
245 already on the last message of a thread).
254 Move to previous message (or start of current message)
257 Move to next matching message
260 Move to previous matching message
263 Add or remove arbitrary tags from the current message.
266 |docstring::notmuch-show-toggle-elide-non-matching|
269 Display full set of key bindings
271 Display of messages can be controlled by the following variables; see also :ref:`show-large`.
273 :index:`notmuch-message-headers`
274 |docstring::notmuch-message-headers|
276 :index:`notmuch-message-headers-visible`
277 |docstring::notmuch-message-headers-visible|
279 :index:`notmuch-show-header-line`
280 |docstring::notmuch-show-header-line|
282 :index:`notmuch-multipart/alternative-discouraged`
284 Which mime types to hide by default for multipart messages.
286 Can either be a list of mime types (as strings) or a function
287 mapping a plist representing the current message to such a list.
288 The following example function would discourage `text/html` and
289 `multipart/related` generally, but discourage `text/plain` should
290 the message be sent from `whatever@example.com`.
294 (defun my--determine-discouraged (msg)
295 (let* ((headers (plist-get msg :headers))
296 (from (or (plist-get headers :From) "")))
298 ((string-match "whatever@example.com" from)
301 (list "text/html" "multipart/related")))))
305 Dealing with large messages and threads
306 ---------------------------------------
308 If you are finding :ref:`notmuch-show` is annoyingly slow displaying
309 large messages, you can customize
310 :index:`notmuch-show-max-text-part-size`. If you want to speed up the
311 display of large threads (with or without large messages), there are
312 several options. First, you can display the same query in one of the
313 other modes. :ref:`notmuch-unthreaded` is the most robust for
314 extremely large queries, but :ref:`notmuch-tree` is also be faster
315 than :ref:`notmuch-show` in general, since it only renders a single
316 message a time. If you prefer to stay with the rendered thread
317 ("conversation") view of :ref:`notmuch-show`, you can customize the
318 variables :index:`notmuch-show-depth-limit`,
319 :index:`notmuch-show-height-limit` and
320 :index:`notmuch-show-max-text-part-size` to limit the amount of
321 rendering done initially. Note that these limits are implicitly
322 *OR*-ed together, and combinations might have surprising effects.
324 :index:`notmuch-show-depth-limit`
325 |docstring::notmuch-show-depth-limit|
327 :index:`notmuch-show-height-limit`
328 |docstring::notmuch-show-height-limit|
330 :index:`notmuch-show-max-text-part-size`
331 |docstring::notmuch-show-max-text-part-size|
338 You can use the usually Emacs ways of copying text to the kill-ring,
339 but notmuch also provides some shortcuts. These keys are available in
340 :ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available
341 in :ref:`notmuch-search`.
343 ``c F`` ``notmuch-show-stash-filename``
344 |docstring::notmuch-show-stash-filename|
346 ``c G`` ``notmuch-show-stash-git-send-email``
347 |docstring::notmuch-show-stash-git-send-email|
349 ``c I`` ``notmuch-show-stash-message-id-stripped``
350 |docstring::notmuch-show-stash-message-id-stripped|
352 ``c L`` ``notmuch-show-stash-mlarchive-link-and-go``
353 |docstring::notmuch-show-stash-mlarchive-link-and-go|
355 ``c T`` ``notmuch-show-stash-tags``
356 |docstring::notmuch-show-stash-tags|
358 ``c c`` ``notmuch-show-stash-cc``
359 |docstring::notmuch-show-stash-cc|
361 ``c d`` ``notmuch-show-stash-date``
362 |docstring::notmuch-show-stash-date|
364 ``c f`` ``notmuch-show-stash-from``
365 |docstring::notmuch-show-stash-from|
367 ``c i`` ``notmuch-show-stash-message-id``
368 |docstring::notmuch-show-stash-message-id|
370 ``c l`` ``notmuch-show-stash-mlarchive-link``
371 |docstring::notmuch-show-stash-mlarchive-link|
373 ``c s`` ``notmuch-show-stash-subject``
374 |docstring::notmuch-show-stash-subject|
376 ``c t`` ``notmuch-show-stash-to``
377 |docstring::notmuch-show-stash-to|
380 Show all available copying commands
387 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
388 email archives. Each line in the buffer represents a single
389 message giving the relative date, the author, subject, and any
396 Displays that message.
402 Move to previous message
405 Move to next matching message
408 Move to previous matching message
410 ``o`` ``notmuch-tree-toggle-order``
411 |docstring::notmuch-tree-toggle-order|
413 ``l`` ``notmuch-tree-filter``
414 Filter or LIMIT the current search results based on an additional query string
416 ``t`` ``notmuch-tree-filter-by-tag``
417 Filter the current search results based on an additional tag
424 Display full set of key bindings
426 As is the case with :ref:`notmuch-search`, the presentation of results
427 can be controlled by the variable ``notmuch-search-oldest-first``.
429 .. _notmuch-unthreaded:
434 ``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
435 each line corresponds to a single message, but no thread information
438 Keybindings are the same as :any:`notmuch-tree`.
443 Several features are accessible from most places in notmuch through the
444 following key bindings:
447 Jump to saved searches using :ref:`notmuch-jump`.
450 Tagging operations using :ref:`notmuch-tag-jump`
452 ``C-_`` ``C-/`` ``C-x u``: Undo previous tagging operation using :ref:`notmuch-tag-undo`
459 Saved searches configured through :ref:`saved-searches` can
460 include a "shortcut key" that's accessible through notmuch-jump.
461 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
462 key of a saved search will immediately jump to that saved search. For
463 example, in the default configuration ``j i`` jumps immediately to the
464 inbox search. When you press ``j``, notmuch-jump shows the saved
465 searches and their shortcut keys in the mini-buffer.
467 .. _notmuch-tag-jump:
472 Tagging operations configured through ``notmuch-tagging-keys`` can
473 be accessed via :kbd:`k` in :ref:`notmuch-show`,
474 :ref:`notmuch-search` and :ref:`notmuch-tree`. With a
475 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
476 operations specified in ``notmuch-tagging-keys``; i.e. each
477 ``+tag`` is replaced by ``-tag`` and vice versa.
479 :index:`notmuch-tagging-keys`
481 |docstring::notmuch-tagging-keys|
483 .. _notmuch-tag-undo:
488 Each notmuch buffer supporting tagging operations (i.e buffers in
489 :any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
490 :any:`notmuch-unthreaded` mode) keeps a local stack of tagging
491 operations. These can be undone via ``notmuch-tag-undo``. By default
492 this is bound to the usual Emacs keys for undo.
494 :index:`notmuch-tag-undo`
496 |docstring::notmuch-tag-undo|
501 :index:`notmuch-cycle-notmuch-buffers`
502 |docstring::notmuch-cycle-notmuch-buffers|
512 :index:`notmuch-poll`
513 |docstring::notmuch-poll|
515 :index:`notmuch-poll-script`
516 |docstring::notmuch-poll-script|
521 :index:`mail-user-agent`
523 Emacs consults the variable :code:`mail-user-agent` to choose a mail
524 sending package for commands like :code:`report-emacs-bug` and
525 :code:`compose-mail`. To use ``notmuch`` for this, customize this
526 variable to the symbol :code:`notmuch-user-agent`.
528 :index:`message-dont-reply-to-names`
530 When composing mail replies, Emacs's message mode uses the
531 variable :code:`message-dont-reply-to-names` to exclude
532 recipients matching a given collection of regular expressions
533 or satisfying an arbitrary predicate. Notmuch's MUA inherits
534 this standard mechanism and will honour your customization of
540 When Notmuch is loaded, it will read the ``notmuch-init-file``
541 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
542 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
543 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
544 suffix exist it will be read instead (just one of these, chosen in this
545 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
546 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
547 options, ``notmuch-init-file`` is not read.