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.
67 Refresh the buffer; mainly update the counts of messages for various
71 Import mail, See :ref:`importing`
77 Search the notmuch database using :ref:`notmuch-search`
90 Since notmuch is entirely search-based, it's often useful to organize
91 mail around common searches. To facilitate this, the first section of
92 notmuch-hello presents a customizable set of saved searches. Saved
93 searches can also be accessed from anywhere in notmuch by pressing
94 ``j`` to access :ref:`notmuch-jump`.
96 The saved searches default to various common searches such as
97 ``tag:inbox`` to access the inbox and ``tag:unread`` to access all
98 unread mail, but there are several options for customization:
100 :index:`notmuch-saved-searches`
101 The list of saved searches, including names, queries, and
102 additional per-query options.
104 :index:`notmuch-saved-searches-sort-function`
105 This variable controls how saved searches should be sorted. A value
106 of ``nil`` displays the saved searches in the order they are stored
107 in ‘notmuch-saved-searches’.
109 :index:`notmuch-column-control`
110 Controls the number of columns for displaying saved-searches/tags
115 The search box lets the user enter a Notmuch query. See section
116 “Description” in Notmuch Query Syntax, for more info on Notmuch query
117 syntax. A history of recent searches is also displayed by default. The
118 latter is controlled by the variable :index:`notmuch-hello-recent-searches-max`.
123 One special kind of saved search provided by default is for each
124 individual tag defined in the database. This can be controlled via the
127 :index:`notmuch-hello-tag-list-make-query`
128 Control how to construct a search (“virtual folder”) from a given
131 :index:`notmuch-hello-hide-tags`
132 Which tags not to display at all.
134 :index:`notmuch-column-control`
135 Controls the number of columns for displaying saved-searches/tags
142 ``notmuch-search-mode`` is used to display the results from executing
143 a query via ``notmuch-search``. The syntax for these queries is the
144 the same as :ref:`saved-searches`. For details of this syntax see
145 info:notmuch-search-terms
147 By default the output approximates that of the command line See section
148 “Description” in notmuch search command.
150 The main purpose of the ``notmuch-search-mode`` buffer is to act as a
151 menu of results that the user can explore further by pressing
152 ``<return>`` on the appropriate line.
158 Move to previous line
161 Open thread on current line in :ref:`notmuch-show` mode
168 Display full set of key bindings
170 The presentation of results can be controlled by the following
173 :index:`notmuch-search-result-format`
174 Control how each thread of messages is presented in the
175 ``notmuch-show-mode`` buffer
177 :index:`notmuch-search-oldest-first`
178 Display the oldest threads at the top of the buffer
185 ``notmuch-show-mode`` is used to display a single thread of email from
188 By default, various components of email messages, (citations,
189 signatures, already-read messages), are hidden. You can make
190 these parts visible by clicking with the mouse button or by
191 pressing RET after positioning the cursor on a hidden part.
194 Scroll the current message (if necessary),
195 advance to the next message, or advance to the next thread (if
196 already on the last message of a thread).
205 Move to previous message (or start of current message)
208 Move to next matching message
211 Move to previous matching message
214 Add or remove arbitrary tags from the current message.
217 Display full set of key bindings
219 Display of messages can be controlled by the following variables
221 :index:`notmuch-message-headers`
222 |docstring::notmuch-message-headers|
224 :index:`notmuch-message-headers-visible`
225 |docstring::notmuch-message-headers-visible|
232 You can use the usually Emacs ways of copying text to the kill-ring,
233 but notmuch also provides some shortcuts. These keys are available in
234 :ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available
235 in :ref:`notmuch-search`.
237 ``c F`` ``notmuch-show-stash-filename``
238 |docstring::notmuch-show-stash-filename|
240 ``c G`` ``notmuch-show-stash-git-send-email``
241 |docstring::notmuch-show-stash-git-send-email|
243 ``c I`` ``notmuch-show-stash-message-id-stripped``
244 |docstring::notmuch-show-stash-message-id-stripped|
246 ``c L`` ``notmuch-show-stash-mlarchive-link-and-go``
247 |docstring::notmuch-show-stash-mlarchive-link-and-go|
249 ``c T`` ``notmuch-show-stash-tags``
250 |docstring::notmuch-show-stash-tags|
252 ``c c`` ``notmuch-show-stash-cc``
253 |docstring::notmuch-show-stash-cc|
255 ``c d`` ``notmuch-show-stash-date``
256 |docstring::notmuch-show-stash-date|
258 ``c f`` ``notmuch-show-stash-from``
259 |docstring::notmuch-show-stash-from|
261 ``c i`` ``notmuch-show-stash-message-id``
262 |docstring::notmuch-show-stash-message-id|
264 ``c l`` ``notmuch-show-stash-mlarchive-link``
265 |docstring::notmuch-show-stash-mlarchive-link|
267 ``c s`` ``notmuch-show-stash-subject``
268 |docstring::notmuch-show-stash-subject|
270 ``c t`` ``notmuch-show-stash-to``
271 |docstring::notmuch-show-stash-to|
274 Show all available copying commands
281 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
282 email archives. Each line in the buffer represents a single
283 message giving the relative date, the author, subject, and any
290 Displays that message.
296 Move to previous message
299 Move to next matching message
302 Move to previous matching message
309 Display full set of key bindings
314 Several features are accessible from anywhere in notmuch through the
315 following key bindings:
318 Jump to saved searches using :ref:`notmuch-jump`.
321 Tagging operations using :ref:`notmuch-tag-jump`
328 Saved searches configured through :ref:`saved-searches` can
329 include a "shortcut key" that's accessible through notmuch-jump.
330 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
331 key of a saved search will immediately jump to that saved search. For
332 example, in the default configuration ``j i`` jumps immediately to the
333 inbox search. When you press ``j``, notmuch-jump shows the saved
334 searches and their shortcut keys in the mini-buffer.
336 .. _notmuch-tag-jump:
341 Tagging operations configured through ``notmuch-tagging-keys`` can
342 be accessed via :kbd:`k` in :ref:`notmuch-show`,
343 :ref:`notmuch-search` and :ref:`notmuch-tree`. With a
344 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
345 operations specified in ``notmuch-tagging-keys``; i.e. each
346 ``+tag`` is replaced by ``-tag`` and vice versa.
348 :index:`notmuch-tagging-keys`
350 |docstring::notmuch-tagging-keys|
355 :index:`notmuch-cycle-notmuch-buffers`
356 |docstring::notmuch-cycle-notmuch-buffers|
366 :index:`notmuch-poll`
367 |docstring::notmuch-poll|
369 :index:`notmuch-poll-script`
370 |docstring::notmuch-poll-script|
375 When Notmuch is loaded, it will read the ``notmuch-init-file``
376 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
377 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
378 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
379 suffix exist it will be read instead (just one of these, chosen in this
380 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
381 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
382 options, ``notmuch-init-file`` is not read.
384 .. include:: ../emacs/rstdoc.rsti
386 .. include:: ../emacs/notmuch.rsti
388 .. include:: ../emacs/notmuch-lib.rsti
390 .. include:: ../emacs/notmuch-show.rsti
392 .. include:: ../emacs/notmuch-tag.rsti