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 variable :index:`notmuch-hello-sections`.
53 notmuch-hello key bindings
54 --------------------------
57 Move to the next widget (button or text entry field)
60 Move to the previous widget.
63 Activate the current widget.
66 Refresh the buffer; mainly update the counts of messages for various
70 Import mail, See :ref:`importing`
76 Search the notmuch database using :ref:`notmuch-search`
89 Since notmuch is entirely search-based, it's often useful to organize
90 mail around common searches. To facilitate this, the first section of
91 notmuch-hello presents a customizable set of saved searches. Saved
92 searches can also be accessed from anywhere in notmuch by pressing
93 ``j`` to access :ref:`notmuch-jump`.
95 The saved searches default to various common searches such as
96 ``tag:inbox`` to access the inbox and ``tag:unread`` to access all
97 unread mail, but there are several options for customization:
99 :index:`notmuch-saved-searches`
100 The list of saved searches, including names, queries, and
101 additional per-query options.
103 :index:`notmuch-saved-search-sort-function`
104 This variable controls how saved searches should be sorted. A value
105 of ``nil`` displays the saved searches in the order they are stored
106 in ‘notmuch-saved-searches’.
108 :index:`notmuch-column-control`
109 Controls the number of columns for displaying saved-searches/tags
114 The search box lets the user enter a Notmuch query. See section
115 “Description” in Notmuch Query Syntax, for more info on Notmuch query
116 syntax. A history of recent searches is also displayed by default. The
117 latter is controlled by the variable :index:`notmuch-hello-recent-searches-max`.
122 One special kind of saved search provided by default is for each
123 individual tag defined in the database. This can be controlled via the
126 :index:`notmuch-hello-tag-list-make-query`
127 Control how to construct a search (“virtual folder”) from a given
130 :index:`notmuch-hello-hide-tags`
131 Which tags not to display at all.
133 :index:`notmuch-column-control`
134 Controls the number of columns for displaying saved-searches/tags
141 ``notmuch-search-mode`` is used to display the results from executing
142 a query via ``notmuch-search``. The syntax for these queries is the
143 the same as :ref:`saved-searches`. For details of this syntax see
144 info:notmuch-search-terms
146 By default the output approximates that of the command line See section
147 “Description” in notmuch search command.
149 The main purpose of the ``notmuch-search-mode`` buffer is to act as a
150 menu of results that the user can explore further by pressing
151 ``<return>`` on the appropriate line.
157 Move to previous line
160 Open thread on current line in :ref:`notmuch-show` mode
166 Display full set of key bindings
168 The presentation of results can be controlled by the following
171 :index:`notmuch-search-result-format`
172 Control how each thread of messages is presented in the
173 ``notmuch-show-mode`` buffer
175 :index:`notmuch-search-oldest-first`
176 Display the oldest threads at the top of the buffer
178 It is also possible to customize how the name of buffers containing
179 search results is formatted using the following variables:
181 :index:`notmuch-search-buffer-name-format`
182 |docstring::notmuch-search-buffer-name-format|
184 :index:`notmuch-saved-search-buffer-name-format`
185 |docstring::notmuch-saved-search-buffer-name-format|
193 ``notmuch-show-mode`` is used to display a single thread of email from
196 By default, various components of email messages, (citations,
197 signatures, already-read messages), are hidden. You can make
198 these parts visible by clicking with the mouse button or by
199 pressing RET after positioning the cursor on a hidden part.
202 Scroll the current message (if necessary),
203 advance to the next message, or advance to the next thread (if
204 already on the last message of a thread).
213 Move to previous message (or start of current message)
216 Move to next matching message
219 Move to previous matching message
222 Add or remove arbitrary tags from the current message.
225 |docstring::notmuch-show-toggle-elide-non-matching|
228 Display full set of key bindings
230 Display of messages can be controlled by the following variables
232 :index:`notmuch-message-headers`
233 |docstring::notmuch-message-headers|
235 :index:`notmuch-message-headers-visible`
236 |docstring::notmuch-message-headers-visible|
238 :index:`notmuch-show-header-line`
239 |docstring::notmuch-show-header-line|
241 :index:`notmuch-multipart/alternative-discouraged`
243 Which mime types to hide by default for multipart messages.
245 Can either be a list of mime types (as strings) or a function
246 mapping a plist representing the current message to such a list.
247 The following example function would discourage `text/html` and
248 `multipart/related` generally, but discourage `text/plain` should
249 the message be sent from `whatever@example.com`.
253 (defun my--determine-discouraged (msg)
254 (let* ((headers (plist-get msg :headers))
255 (from (or (plist-get headers :From) "")))
257 ((string-match "whatever@example.com" from)
260 (list "text/html" "multipart/related")))))
267 You can use the usually Emacs ways of copying text to the kill-ring,
268 but notmuch also provides some shortcuts. These keys are available in
269 :ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available
270 in :ref:`notmuch-search`.
272 ``c F`` ``notmuch-show-stash-filename``
273 |docstring::notmuch-show-stash-filename|
275 ``c G`` ``notmuch-show-stash-git-send-email``
276 |docstring::notmuch-show-stash-git-send-email|
278 ``c I`` ``notmuch-show-stash-message-id-stripped``
279 |docstring::notmuch-show-stash-message-id-stripped|
281 ``c L`` ``notmuch-show-stash-mlarchive-link-and-go``
282 |docstring::notmuch-show-stash-mlarchive-link-and-go|
284 ``c T`` ``notmuch-show-stash-tags``
285 |docstring::notmuch-show-stash-tags|
287 ``c c`` ``notmuch-show-stash-cc``
288 |docstring::notmuch-show-stash-cc|
290 ``c d`` ``notmuch-show-stash-date``
291 |docstring::notmuch-show-stash-date|
293 ``c f`` ``notmuch-show-stash-from``
294 |docstring::notmuch-show-stash-from|
296 ``c i`` ``notmuch-show-stash-message-id``
297 |docstring::notmuch-show-stash-message-id|
299 ``c l`` ``notmuch-show-stash-mlarchive-link``
300 |docstring::notmuch-show-stash-mlarchive-link|
302 ``c s`` ``notmuch-show-stash-subject``
303 |docstring::notmuch-show-stash-subject|
305 ``c t`` ``notmuch-show-stash-to``
306 |docstring::notmuch-show-stash-to|
309 Show all available copying commands
316 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
317 email archives. Each line in the buffer represents a single
318 message giving the relative date, the author, subject, and any
325 Displays that message.
331 Move to previous message
334 Move to next matching message
337 Move to previous matching message
339 ``o`` ``notmuch-tree-toggle-order``
340 |docstring::notmuch-tree-toggle-order|
342 ``l`` ``notmuch-tree-filter``
343 Filter or LIMIT the current search results based on an additional query string
345 ``t`` ``notmuch-tree-filter-by-tag``
346 Filter the current search results based on an additional tag
353 Display full set of key bindings
355 As is the case with :ref:`notmuch-search`, the presentation of results
356 can be controlled by the variable ``notmuch-search-oldest-first``.
358 .. _notmuch-unthreaded:
363 ``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
364 each line corresponds to a single message, but no thread information
367 Keybindings are the same as :any:`notmuch-tree`.
372 Several features are accessible from most places in notmuch through the
373 following key bindings:
376 Jump to saved searches using :ref:`notmuch-jump`.
379 Tagging operations using :ref:`notmuch-tag-jump`
381 ``C-_`` ``C-/`` ``C-x u``: Undo previous tagging operation using :ref:`notmuch-tag-undo`
388 Saved searches configured through :ref:`saved-searches` can
389 include a "shortcut key" that's accessible through notmuch-jump.
390 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
391 key of a saved search will immediately jump to that saved search. For
392 example, in the default configuration ``j i`` jumps immediately to the
393 inbox search. When you press ``j``, notmuch-jump shows the saved
394 searches and their shortcut keys in the mini-buffer.
396 .. _notmuch-tag-jump:
401 Tagging operations configured through ``notmuch-tagging-keys`` can
402 be accessed via :kbd:`k` in :ref:`notmuch-show`,
403 :ref:`notmuch-search` and :ref:`notmuch-tree`. With a
404 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
405 operations specified in ``notmuch-tagging-keys``; i.e. each
406 ``+tag`` is replaced by ``-tag`` and vice versa.
408 :index:`notmuch-tagging-keys`
410 |docstring::notmuch-tagging-keys|
412 .. _notmuch-tag-undo:
417 Each notmuch buffer supporting tagging operations (i.e buffers in
418 :any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
419 :any:`notmuch-unthreaded` mode) keeps a local stack of tagging
420 operations. These can be undone via ``notmuch-tag-undo``. By default
421 this is bound to the usual Emacs keys for undo.
423 :index:`notmuch-tag-undo`
425 |docstring::notmuch-tag-undo|
430 :index:`notmuch-cycle-notmuch-buffers`
431 |docstring::notmuch-cycle-notmuch-buffers|
441 :index:`notmuch-poll`
442 |docstring::notmuch-poll|
444 :index:`notmuch-poll-script`
445 |docstring::notmuch-poll-script|
450 :index:`mail-user-agent`
452 Emacs consults the variable :code:`mail-user-agent` to choose a mail
453 sending package for commands like :code:`report-emacs-bug` and
454 :code:`compose-mail`. To use ``notmuch`` for this, customize this
455 variable to the symbol :code:`notmuch-user-agent`.
460 When Notmuch is loaded, it will read the ``notmuch-init-file``
461 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
462 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
463 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
464 suffix exist it will be read instead (just one of these, chosen in this
465 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
466 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
467 options, ``notmuch-init-file`` is not read.