git.notmuchmail.org Git - notmuch/blob - 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 ``<backtab>``
  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-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’.
 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 It is also possible to customize how the name of buffers containing
 179 search results is formatted using the following variables:
 180
 181 :index:`notmuch-search-buffer-name-format`
 182        |docstring::notmuch-search-buffer-name-format|
 183
 184 :index:`notmuch-saved-search-buffer-name-format`
 185        |docstring::notmuch-saved-search-buffer-name-format|
 186
 187
 188 .. _notmuch-show:
 189
 190 notmuch-show
 191 ============
 192
 193 ``notmuch-show-mode`` is used to display a single thread of email from
 194 your email archives.
 195
 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.
 200
 201 ``<space>``
 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).
 205
 206 ``c``
 207     :ref:`show-copy`
 208
 209 ``N``
 210     Move to next message
 211
 212 ``P``
 213     Move to previous message (or start of current message)
 214
 215 ``n``
 216     Move to next matching message
 217
 218 ``p``
 219     Move to previous matching message
 220
 221 ``+,-``
 222     Add or remove arbitrary tags from the current message.
 223
 224 ``!``
 225     |docstring::notmuch-show-toggle-elide-non-matching|
 226
 227 ``?``
 228     Display full set of key bindings
 229
 230 Display of messages can be controlled by the following variables
 231
 232 :index:`notmuch-message-headers`
 233        |docstring::notmuch-message-headers|
 234
 235 :index:`notmuch-message-headers-visible`
 236        |docstring::notmuch-message-headers-visible|
 237
 238 :index:`notmuch-show-header-line`
 239        |docstring::notmuch-show-header-line|
 240
 241 :index:`notmuch-multipart/alternative-discouraged`
 242
 243    Which mime types to hide by default for multipart messages.
 244
 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`.
 250
 251    .. code:: lisp
 252
 253       (defun my--determine-discouraged (msg)
 254         (let* ((headers (plist-get msg :headers))
 255                (from (or (plist-get headers :From) "")))
 256           (cond
 257            ((string-match "whatever@example.com" from)
 258             (list "text/plain"))
 259            (t
 260             (list "text/html" "multipart/related")))))
 261
 262 .. _show-copy:
 263
 264 Copy to kill-ring
 265 -----------------
 266
 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`.
 271
 272 ``c F`` ``notmuch-show-stash-filename``
 273    |docstring::notmuch-show-stash-filename|
 274
 275 ``c G`` ``notmuch-show-stash-git-send-email``
 276    |docstring::notmuch-show-stash-git-send-email|
 277
 278 ``c I`` ``notmuch-show-stash-message-id-stripped``
 279    |docstring::notmuch-show-stash-message-id-stripped|
 280
 281 ``c L`` ``notmuch-show-stash-mlarchive-link-and-go``
 282    |docstring::notmuch-show-stash-mlarchive-link-and-go|
 283
 284 ``c T`` ``notmuch-show-stash-tags``
 285    |docstring::notmuch-show-stash-tags|
 286
 287 ``c c`` ``notmuch-show-stash-cc``
 288    |docstring::notmuch-show-stash-cc|
 289
 290 ``c d`` ``notmuch-show-stash-date``
 291    |docstring::notmuch-show-stash-date|
 292
 293 ``c f`` ``notmuch-show-stash-from``
 294    |docstring::notmuch-show-stash-from|
 295
 296 ``c i`` ``notmuch-show-stash-message-id``
 297    |docstring::notmuch-show-stash-message-id|
 298
 299 ``c l`` ``notmuch-show-stash-mlarchive-link``
 300    |docstring::notmuch-show-stash-mlarchive-link|
 301
 302 ``c s`` ``notmuch-show-stash-subject``
 303    |docstring::notmuch-show-stash-subject|
 304
 305 ``c t`` ``notmuch-show-stash-to``
 306    |docstring::notmuch-show-stash-to|
 307
 308 ``c ?``
 309     Show all available copying commands
 310
 311 .. _notmuch-tree:
 312
 313 notmuch-tree
 314 ============
 315
 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
 319 tags.
 320
 321 ``c``
 322     :ref:`show-copy`
 323
 324 ``<return>``
 325    Displays that message.
 326
 327 ``N``
 328     Move to next message
 329
 330 ``P``
 331     Move to previous message
 332
 333 ``n``
 334     Move to next matching message
 335
 336 ``p``
 337     Move to previous matching message
 338
 339 ``o`` ``notmuch-tree-toggle-order``
 340    |docstring::notmuch-tree-toggle-order|
 341
 342 ``l`` ``notmuch-tree-filter``
 343    Filter or LIMIT the current search results based on an additional query string
 344
 345 ``t`` ``notmuch-tree-filter-by-tag``
 346    Filter the current search results based on an additional tag
 347
 348
 349 ``g`` ``=``
 350     Refresh the buffer
 351
 352 ``?``
 353     Display full set of key bindings
 354
 355 As is the case with :ref:`notmuch-search`, the presentation of results
 356 can be controlled by the variable ``notmuch-search-oldest-first``.
 357
 358 .. _notmuch-unthreaded:
 359
 360 notmuch-unthreaded
 361 ------------------
 362
 363 ``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
 364 each line corresponds to a single message, but no thread information
 365 is presented.
 366
 367 Keybindings are the same as :any:`notmuch-tree`.
 368
 369 Global key bindings
 370 ===================
 371
 372 Several features are accessible from most places in notmuch through the
 373 following key bindings:
 374
 375 ``j``
 376     Jump to saved searches using :ref:`notmuch-jump`.
 377
 378 ``k``
 379     Tagging operations using :ref:`notmuch-tag-jump`
 380
 381 ``C-_`` ``C-/`` ``C-x u``: Undo previous tagging operation using :ref:`notmuch-tag-undo`
 382
 383 .. _notmuch-jump:
 384
 385 notmuch-jump
 386 ------------
 387
 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.
 395
 396 .. _notmuch-tag-jump:
 397
 398 notmuch-tag-jump
 399 ----------------
 400
 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.
 407
 408 :index:`notmuch-tagging-keys`
 409
 410   |docstring::notmuch-tagging-keys|
 411
 412 .. _notmuch-tag-undo:
 413
 414 notmuch-tag-undo
 415 ----------------
 416
 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.
 422
 423 :index:`notmuch-tag-undo`
 424
 425    |docstring::notmuch-tag-undo|
 426
 427 Buffer navigation
 428 =================
 429
 430 :index:`notmuch-cycle-notmuch-buffers`
 431    |docstring::notmuch-cycle-notmuch-buffers|
 432
 433 Configuration
 434 =============
 435
 436 .. _importing:
 437
 438 Importing Mail
 439 --------------
 440
 441 :index:`notmuch-poll`
 442    |docstring::notmuch-poll|
 443
 444 :index:`notmuch-poll-script`
 445    |docstring::notmuch-poll-script|
 446
 447 Sending Mail
 448 ------------
 449
 450 :index:`mail-user-agent`
 451
 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`.
 456
 457 Init File
 458 ---------
 459
 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.