test: drop use of db_ending
[notmuch] / doc / notmuch-emacs.rst
1 =============
2 notmuch-emacs
3 =============
4
5 About this Manual
6 =================
7
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
13 *notmuch-emacs*.
14
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.
20
21 notmuch-hello
22 =============
23
24 .. index::
25    single: notmuch-hello
26    single: notmuch
27
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>``
34
35 |   Welcome to **notmuch** You have 52 messages.
36 |
37 | Saved searches: **[edit]**
38 |
39 |         52 **inbox**           52 **unread**
40 |
41 | Search: ____________________________________
42 |
43 | All tags: **[show]**
44 |
45 |        Hit \`?' for context-sensitive help in any Notmuch screen.
46 |                     Customize Notmuch or this page.
47
48 You can change the overall appearance of the notmuch-hello screen by
49 customizing the variable :index:`notmuch-hello-sections`.
50
51
52
53 notmuch-hello key bindings
54 --------------------------
55
56 ``<tab>``
57     Move to the next widget (button or text entry field)
58
59 ``<backspace>``
60     Move to the previous widget.
61
62 ``<return>``
63     Activate the current widget.
64
65 ``g`` ``=``
66     Refresh the buffer; mainly update the counts of messages for various
67     saved searches.
68
69 ``G``
70     Import mail, See :ref:`importing`
71
72 ``m``
73     Compose a message
74
75 ``s``
76     Search the notmuch database using :ref:`notmuch-search`
77
78 ``v``
79     Print notmuch version
80
81 ``q``
82     Quit
83
84 .. _saved-searches:
85
86 Saved Searches
87 --------------
88
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`.
94
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:
98
99 :index:`notmuch-saved-searches`
100     The list of saved searches, including names, queries, and
101     additional per-query options.
102
103 :index:`notmuch-saved-searches-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’.
107
108 :index:`notmuch-column-control`
109     Controls the number of columns for displaying saved-searches/tags
110
111 Search Box
112 ----------
113
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`.
118
119 Known Tags
120 ----------
121
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
124 following variables.
125
126 :index:`notmuch-hello-tag-list-make-query`
127     Control how to construct a search (“virtual folder”) from a given
128     tag.
129
130 :index:`notmuch-hello-hide-tags`
131     Which tags not to display at all.
132
133 :index:`notmuch-column-control`
134     Controls the number of columns for displaying saved-searches/tags
135
136 .. _notmuch-search:
137
138 notmuch-search
139 ==============
140
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
145
146 By default the output approximates that of the command line See section
147 “Description” in notmuch search command.
148
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.
152
153 ``n,C-n,<down>``
154     Move to next line
155
156 ``p,C-p,<up>``
157     Move to previous line
158
159 ``<return>``
160     Open thread on current line in :ref:`notmuch-show` mode
161
162 ``g`` ``=``
163     Refresh the buffer
164
165 ``?``
166     Display full set of key bindings
167
168 The presentation of results can be controlled by the following
169 variables.
170
171 :index:`notmuch-search-result-format`
172     Control how each thread of messages is presented in the
173     ``notmuch-show-mode`` buffer
174
175 :index:`notmuch-search-oldest-first`
176     Display the oldest threads at the top of the buffer
177
178 .. _notmuch-show:
179
180 notmuch-show
181 ============
182
183 ``notmuch-show-mode`` is used to display a single thread of email from
184 your email archives.
185
186 By default, various components of email messages, (citations,
187 signatures, already-read messages), are hidden. You can make
188 these parts visible by clicking with the mouse button or by
189 pressing RET after positioning the cursor on a hidden part.
190
191 ``<space>``
192     Scroll the current message (if necessary),
193     advance to the next message, or advance to the next thread (if
194     already on the last message of a thread).
195
196 ``c``
197     :ref:`show-copy`
198
199 ``N``
200     Move to next message
201
202 ``P``
203     Move to previous message (or start of current message)
204
205 ``n``
206     Move to next matching message
207
208 ``p``
209     Move to previous matching message
210
211 ``+,-``
212     Add or remove arbitrary tags from the current message.
213
214 ``?``
215     Display full set of key bindings
216
217 Display of messages can be controlled by the following variables
218
219 :index:`notmuch-message-headers`
220        |docstring::notmuch-message-headers|
221
222 :index:`notmuch-message-headers-visible`
223        |docstring::notmuch-message-headers-visible|
224
225 .. _show-copy:
226
227 Copy to kill-ring
228 -----------------
229
230 You can use the usually Emacs ways of copying text to the kill-ring,
231 but notmuch also provides some shortcuts. These keys are available in
232 :ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available
233 in :ref:`notmuch-search`.
234
235 ``c F`` ``notmuch-show-stash-filename``
236    |docstring::notmuch-show-stash-filename|
237
238 ``c G`` ``notmuch-show-stash-git-send-email``
239    |docstring::notmuch-show-stash-git-send-email|
240
241 ``c I`` ``notmuch-show-stash-message-id-stripped``
242    |docstring::notmuch-show-stash-message-id-stripped|
243
244 ``c L`` ``notmuch-show-stash-mlarchive-link-and-go``
245    |docstring::notmuch-show-stash-mlarchive-link-and-go|
246
247 ``c T`` ``notmuch-show-stash-tags``
248    |docstring::notmuch-show-stash-tags|
249
250 ``c c`` ``notmuch-show-stash-cc``
251    |docstring::notmuch-show-stash-cc|
252
253 ``c d`` ``notmuch-show-stash-date``
254    |docstring::notmuch-show-stash-date|
255
256 ``c f`` ``notmuch-show-stash-from``
257    |docstring::notmuch-show-stash-from|
258
259 ``c i`` ``notmuch-show-stash-message-id``
260    |docstring::notmuch-show-stash-message-id|
261
262 ``c l`` ``notmuch-show-stash-mlarchive-link``
263    |docstring::notmuch-show-stash-mlarchive-link|
264
265 ``c s`` ``notmuch-show-stash-subject``
266    |docstring::notmuch-show-stash-subject|
267
268 ``c t`` ``notmuch-show-stash-to``
269    |docstring::notmuch-show-stash-to|
270
271 ``c ?``
272     Show all available copying commands
273
274 .. _notmuch-tree:
275
276 notmuch-tree
277 ============
278
279 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
280 email archives. Each line in the buffer represents a single
281 message giving the relative date, the author, subject, and any
282 tags.
283
284 ``c``
285     :ref:`show-copy`
286
287 ``<return>``
288    Displays that message.
289
290 ``N``
291     Move to next message
292
293 ``P``
294     Move to previous message
295
296 ``n``
297     Move to next matching message
298
299 ``p``
300     Move to previous matching message
301
302 ``g`` ``=``
303     Refresh the buffer
304
305 ``?``
306     Display full set of key bindings
307
308 Global key bindings
309 ===================
310
311 Several features are accessible from anywhere in notmuch through the
312 following key bindings:
313
314 ``j``
315     Jump to saved searches using :ref:`notmuch-jump`.
316
317 ``k``
318     Tagging operations using :ref:`notmuch-tag-jump`
319
320 .. _notmuch-jump:
321
322 notmuch-jump
323 ------------
324
325 Saved searches configured through :ref:`saved-searches` can
326 include a "shortcut key" that's accessible through notmuch-jump.
327 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
328 key of a saved search will immediately jump to that saved search.  For
329 example, in the default configuration ``j i`` jumps immediately to the
330 inbox search.  When you press ``j``, notmuch-jump shows the saved
331 searches and their shortcut keys in the mini-buffer.
332
333 .. _notmuch-tag-jump:
334
335 notmuch-tag-jump
336 ----------------
337
338 Tagging operations configured through ``notmuch-tagging-keys`` can
339 be accessed via :kbd:`k` in :ref:`notmuch-show`,
340 :ref:`notmuch-search` and :ref:`notmuch-tree`.  With a
341 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
342 operations specified in ``notmuch-tagging-keys``; i.e. each
343 ``+tag`` is replaced by ``-tag`` and vice versa.
344
345 :index:`notmuch-tagging-keys`
346
347   |docstring::notmuch-tagging-keys|
348
349 Buffer navigation
350 =================
351
352 :index:`notmuch-cycle-notmuch-buffers`
353    |docstring::notmuch-cycle-notmuch-buffers|
354
355 Configuration
356 =============
357
358 .. _importing:
359
360 Importing Mail
361 --------------
362
363 :index:`notmuch-poll`
364    |docstring::notmuch-poll|
365
366 :index:`notmuch-poll-script`
367    |docstring::notmuch-poll-script|
368
369 Init File
370 ---------
371
372 When Notmuch is loaded, it will read the ``notmuch-init-file``
373 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
374 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
375 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
376 suffix exist it will be read instead (just one of these, chosen in this
377 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
378 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
379 options, ``notmuch-init-file`` is not read.
380
381 .. include:: ../emacs/rstdoc.rsti
382
383 .. include:: ../emacs/notmuch.rsti
384
385 .. include:: ../emacs/notmuch-lib.rsti
386
387 .. include:: ../emacs/notmuch-show.rsti
388
389 .. include:: ../emacs/notmuch-tag.rsti