git.cworth.org Git - notmuch/blob - doc/notmuch-emacs.rst

   1 .. _notmuch-emacs:
   2
   3 ==========================
   4 Emacs Frontend for Notmuch
   5 ==========================
   6
   7 About this Manual
   8 =================
   9
  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
  15 *notmuch-emacs*.
  16
  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.
  22
  23 notmuch-hello
  24 =============
  25
  26 .. index::
  27    single: notmuch-hello
  28    single: notmuch
  29
  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>``
  36
  37 |   Welcome to **notmuch** You have 52 messages.
  38 |
  39 | Saved searches: **[edit]**
  40 |
  41 |         52 **inbox**           52 **unread**
  42 |
  43 | Search: ____________________________________
  44 |
  45 | All tags: **[show]**
  46 |
  47 |        Hit \`?' for context-sensitive help in any Notmuch screen.
  48 |                     Customize Notmuch or this page.
  49
  50 You can change the overall appearance of the notmuch-hello screen by
  51 customizing the variables
  52
  53 .. emacsvar:: notmuch-hello-sections
  54
  55        |docstring::notmuch-hello-sections|
  56
  57 .. emacsvar:: notmuch-hello-thousands-separator
  58
  59        |docstring::notmuch-hello-thousands-separator|
  60
  61 .. emacsvar:: notmuch-show-logo
  62
  63        |docstring::notmuch-show-logo|
  64
  65 .. emacsvar:: notmuch-column-control
  66
  67     Controls the number of columns for saved searches/tags in notmuch view.
  68
  69     This variable has three potential types of values:
  70
  71     .. describe:: t
  72
  73        Automatically calculate the number of columns possible based
  74        on the tags to be shown and the window width.
  75
  76     .. describe:: integer <n>
  77
  78        A lower bound on the number of characters that will
  79        be used to display each column.
  80
  81     .. describe:: float <f>
  82
  83        A fraction of the window width that is the lower bound on the
  84        number of characters that should be used for each column.
  85
  86     So:
  87
  88     - if you would like two columns of tags, set this to 0.5.
  89
  90     - if you would like a single column of tags, set this to 1.0.
  91
  92     - if you would like tags to be 30 characters wide, set this to 30.
  93
  94     - if you don't want to worry about all of this nonsense, leave
  95       this set to `t`.
  96
  97
  98 notmuch-hello key bindings
  99 --------------------------
 100
 101 ``<tab>``
 102     Move to the next widget (button or text entry field)
 103
 104 ``<backtab>``
 105     Move to the previous widget.
 106
 107 ``<return>``
 108     Activate the current widget.
 109
 110 ``g`` ``=``
 111     Refresh the buffer; mainly update the counts of messages for various
 112     saved searches.
 113
 114 ``G``
 115     Import mail, See :ref:`importing`
 116
 117 ``m``
 118     Compose a message
 119
 120 ``s``
 121     Search the notmuch database using :ref:`notmuch-search`
 122
 123 ``v``
 124     Print notmuch version
 125
 126 ``q``
 127     Quit
 128
 129 .. _saved-searches:
 130
 131 Saved Searches
 132 --------------
 133
 134 Since notmuch is entirely search-based, it's often useful to organize
 135 mail around common searches.  To facilitate this, the first section of
 136 notmuch-hello presents a customizable set of saved searches.  Saved
 137 searches can also be accessed from anywhere in notmuch by pressing
 138 ``j`` to access :ref:`notmuch-jump`.
 139
 140 The saved searches default to various common searches such as
 141 ``tag:inbox`` to access the inbox and ``tag:unread`` to access all
 142 unread mail, but there are several options for customization:
 143
 144 .. emacsvar:: notmuch-saved-searches
 145
 146     The list of saved searches, including names, queries, and
 147     additional per-query options.
 148
 149 .. emacsvar:: notmuch-saved-search-sort-function
 150
 151     This variable controls how saved searches should be sorted. A value
 152     of ``nil`` displays the saved searches in the order they are stored
 153     in ‘notmuch-saved-searches’.
 154
 155 Search Box
 156 ----------
 157
 158 The search box lets the user enter a Notmuch query. See section
 159 “Description” in Notmuch Query Syntax, for more info on Notmuch query
 160 syntax. A history of recent searches is also displayed by default. The
 161 latter is controlled by the variable `notmuch-hello-recent-searches-max`.
 162
 163 .. emacsvar:: notmuch-hello-recent-searches-max
 164
 165               |docstring::notmuch-hello-recent-searches-max|
 166
 167 Known Tags
 168 ----------
 169
 170 One special kind of saved search provided by default is for each
 171 individual tag defined in the database. This can be controlled via the
 172 following variables.
 173
 174 .. emacsvar:: notmuch-hello-tag-list-make-query
 175
 176     Control how to construct a search (“virtual folder”) from a given
 177     tag.
 178
 179 .. emacsvar:: notmuch-hello-hide-tags
 180
 181     Which tags not to display at all.
 182
 183 .. _notmuch-search:
 184
 185 notmuch-search
 186 ==============
 187
 188 ``notmuch-search-mode`` is used to display the results from executing
 189 a query via ``notmuch-search``. The syntax for these queries is the
 190 the same as :ref:`saved-searches`. For details of this syntax see
 191 info:notmuch-search-terms
 192
 193 By default the output approximates that of the command line See section
 194 “Description” in notmuch search command.
 195
 196 The main purpose of the ``notmuch-search-mode`` buffer is to act as a
 197 menu of results that the user can explore further by pressing
 198 ``<return>`` on the appropriate line.
 199
 200 ``n,C-n,<down>``
 201     Move to next line
 202
 203 ``p,C-p,<up>``
 204     Move to previous line
 205
 206 ``<return>``
 207     Open thread on current line in :ref:`notmuch-show` mode
 208
 209 ``g`` ``=``
 210     Refresh the buffer
 211
 212 ``?``
 213     Display full set of key bindings
 214
 215 The presentation of results can be controlled by the following
 216 variables.
 217
 218 .. emacsvar:: notmuch-search-result-format
 219
 220     Control how each thread of messages is presented in the
 221     ``notmuch-show-mode`` buffer
 222
 223 .. emacsvar:: notmuch-search-oldest-first
 224
 225     Display the oldest threads at the top of the buffer
 226
 227 It is also possible to customize how the name of buffers containing
 228 search results is formatted using the following variables:
 229
 230 .. emacsvar:: notmuch-search-buffer-name-format
 231
 232        |docstring::notmuch-search-buffer-name-format|
 233
 234 .. emacsvar:: notmuch-saved-search-buffer-name-format
 235
 236        |docstring::notmuch-saved-search-buffer-name-format|
 237
 238
 239 .. _notmuch-show:
 240
 241 notmuch-show
 242 ============
 243
 244 ``notmuch-show-mode`` is used to display a single thread of email from
 245 your email archives.
 246
 247 By default, various components of email messages, (citations,
 248 signatures, already-read messages), are hidden. You can make
 249 these parts visible by clicking with the mouse button or by
 250 pressing RET after positioning the cursor on a hidden part.
 251
 252 ``<space>``
 253     Scroll the current message (if necessary),
 254     advance to the next message, or advance to the next thread (if
 255     already on the last message of a thread).
 256
 257 ``c``
 258     :ref:`show-copy`
 259
 260 ``N``
 261     Move to next message
 262
 263 ``P``
 264     Move to previous message (or start of current message)
 265
 266 ``n``
 267     Move to next matching message
 268
 269 ``p``
 270     Move to previous matching message
 271
 272 ``+,-``
 273     Add or remove arbitrary tags from the current message.
 274
 275 ``!``
 276     |docstring::notmuch-show-toggle-elide-non-matching|
 277
 278 ``?``
 279     Display full set of key bindings
 280
 281 Display of messages can be controlled by the following variables; see also :ref:`show-large`.
 282
 283 .. emacsvar:: notmuch-message-headers
 284
 285        |docstring::notmuch-message-headers|
 286
 287 .. emacsvar:: notmuch-message-headers-visible
 288
 289        |docstring::notmuch-message-headers-visible|
 290
 291 .. emacsvar:: notmuch-show-header-line
 292
 293        |docstring::notmuch-show-header-line|
 294
 295 .. emacsvar:: notmuch-multipart/alternative-discouraged
 296
 297    Which mime types to hide by default for multipart messages.
 298
 299    Can either be a list of mime types (as strings) or a function
 300    mapping a plist representing the current message to such a list.
 301    The following example function would discourage `text/html` and
 302    `multipart/related` generally, but discourage `text/plain` should
 303    the message be sent from `whatever@example.com`.
 304
 305    .. code:: lisp
 306
 307       (defun my--determine-discouraged (msg)
 308         (let* ((headers (plist-get msg :headers))
 309                (from (or (plist-get headers :From) "")))
 310           (cond
 311            ((string-match "whatever@example.com" from)
 312             (list "text/plain"))
 313            (t
 314             (list "text/html" "multipart/related")))))
 315
 316 .. _show-large:
 317
 318 Dealing with large messages and threads
 319 ---------------------------------------
 320
 321 If you are finding :ref:`notmuch-show` is annoyingly slow displaying
 322 large messages, you can customize
 323 :emacsvar:`notmuch-show-max-text-part-size`.  If you want to speed up the
 324 display of large threads (with or without large messages), there are
 325 several options.  First, you can display the same query in one of the
 326 other modes. :ref:`notmuch-unthreaded` is the most robust for
 327 extremely large queries, but :ref:`notmuch-tree` is also be faster
 328 than :ref:`notmuch-show` in general, since it only renders a single
 329 message a time. If you prefer to stay with the rendered thread
 330 ("conversation") view of :ref:`notmuch-show`, you can customize the
 331 variables :emacsvar:`notmuch-show-depth-limit`,
 332 :emacsvar:`notmuch-show-height-limit` and
 333 :emacsvar:`notmuch-show-max-text-part-size` to limit the amount of
 334 rendering done initially. Note that these limits are implicitly
 335 *OR*-ed together, and combinations might have surprising effects.
 336
 337 .. emacsvar:: notmuch-show-depth-limit
 338
 339        |docstring::notmuch-show-depth-limit|
 340
 341 .. emacsvar:: notmuch-show-height-limit
 342
 343        |docstring::notmuch-show-height-limit|
 344
 345 .. emacsvar:: notmuch-show-max-text-part-size
 346
 347        |docstring::notmuch-show-max-text-part-size|
 348
 349 .. _show-copy:
 350
 351 Copy to kill-ring
 352 -----------------
 353
 354 You can use the usually Emacs ways of copying text to the kill-ring,
 355 but notmuch also provides some shortcuts. These keys are available in
 356 :ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available
 357 in :ref:`notmuch-search`.
 358
 359 ``c F`` ``notmuch-show-stash-filename``
 360    |docstring::notmuch-show-stash-filename|
 361
 362 ``c G`` ``notmuch-show-stash-git-send-email``
 363    |docstring::notmuch-show-stash-git-send-email|
 364
 365 ``c I`` ``notmuch-show-stash-message-id-stripped``
 366    |docstring::notmuch-show-stash-message-id-stripped|
 367
 368 ``c L`` ``notmuch-show-stash-mlarchive-link-and-go``
 369    |docstring::notmuch-show-stash-mlarchive-link-and-go|
 370
 371 ``c T`` ``notmuch-show-stash-tags``
 372    |docstring::notmuch-show-stash-tags|
 373
 374 ``c c`` ``notmuch-show-stash-cc``
 375    |docstring::notmuch-show-stash-cc|
 376
 377 ``c d`` ``notmuch-show-stash-date``
 378    |docstring::notmuch-show-stash-date|
 379
 380 ``c f`` ``notmuch-show-stash-from``
 381    |docstring::notmuch-show-stash-from|
 382
 383 ``c i`` ``notmuch-show-stash-message-id``
 384    |docstring::notmuch-show-stash-message-id|
 385
 386 ``c l`` ``notmuch-show-stash-mlarchive-link``
 387    |docstring::notmuch-show-stash-mlarchive-link|
 388
 389 ``c s`` ``notmuch-show-stash-subject``
 390    |docstring::notmuch-show-stash-subject|
 391
 392 ``c t`` ``notmuch-show-stash-to``
 393    |docstring::notmuch-show-stash-to|
 394
 395 ``c ?``
 396     Show all available copying commands
 397
 398 .. _notmuch-tree:
 399
 400 notmuch-tree
 401 ============
 402
 403 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
 404 email archives. Each line in the buffer represents a single
 405 message giving the relative date, the author, subject, and any
 406 tags.
 407
 408 ``c``
 409     :ref:`show-copy`
 410
 411 ``<return>``
 412    Displays that message.
 413
 414 ``N``
 415     Move to next message
 416
 417 ``P``
 418     Move to previous message
 419
 420 ``n``
 421     Move to next matching message
 422
 423 ``p``
 424     Move to previous matching message
 425
 426 ``o`` ``notmuch-tree-toggle-order``
 427    |docstring::notmuch-tree-toggle-order|
 428
 429 ``l`` ``notmuch-tree-filter``
 430    Filter or LIMIT the current search results based on an additional query string
 431
 432 ``t`` ``notmuch-tree-filter-by-tag``
 433    Filter the current search results based on an additional tag
 434
 435
 436 ``g`` ``=``
 437     Refresh the buffer
 438
 439 ``?``
 440     Display full set of key bindings
 441
 442 As is the case with :ref:`notmuch-search`, the presentation of results
 443 can be controlled by the variable ``notmuch-search-oldest-first``.
 444
 445 .. _notmuch-unthreaded:
 446
 447 notmuch-unthreaded
 448 ------------------
 449
 450 ``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
 451 each line corresponds to a single message, but no thread information
 452 is presented.
 453
 454 Keybindings are the same as :any:`notmuch-tree`.
 455
 456 Global key bindings
 457 ===================
 458
 459 Several features are accessible from most places in notmuch through the
 460 following key bindings:
 461
 462 ``j``
 463     Jump to saved searches using :ref:`notmuch-jump`.
 464
 465 ``k``
 466     Tagging operations using :ref:`notmuch-tag-jump`
 467
 468 ``C-_`` ``C-/`` ``C-x u``: Undo previous tagging operation using :ref:`notmuch-tag-undo`
 469
 470 .. _notmuch-jump:
 471
 472 notmuch-jump
 473 ------------
 474
 475 Saved searches configured through :ref:`saved-searches` can
 476 include a "shortcut key" that's accessible through notmuch-jump.
 477 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
 478 key of a saved search will immediately jump to that saved search.  For
 479 example, in the default configuration ``j i`` jumps immediately to the
 480 inbox search.  When you press ``j``, notmuch-jump shows the saved
 481 searches and their shortcut keys in the mini-buffer.
 482
 483 .. _notmuch-tag-jump:
 484
 485 notmuch-tag-jump
 486 ----------------
 487
 488 Tagging operations configured through ``notmuch-tagging-keys`` can
 489 be accessed via :kbd:`k` in :ref:`notmuch-show`,
 490 :ref:`notmuch-search` and :ref:`notmuch-tree`.  With a
 491 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
 492 operations specified in ``notmuch-tagging-keys``; i.e. each
 493 ``+tag`` is replaced by ``-tag`` and vice versa.
 494
 495 .. emacsvar:: notmuch-tagging-keys
 496
 497   |docstring::notmuch-tagging-keys|
 498
 499 .. _notmuch-tag-undo:
 500
 501 notmuch-tag-undo
 502 ----------------
 503
 504 Each notmuch buffer supporting tagging operations (i.e buffers in
 505 :any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
 506 :any:`notmuch-unthreaded` mode) keeps a local stack of tagging
 507 operations. These can be undone via :emacscmd:`notmuch-tag-undo`. By default
 508 this is bound to the usual Emacs keys for undo.
 509
 510 .. emacscmd:: notmuch-tag-undo
 511
 512    |docstring::notmuch-tag-undo|
 513
 514 Buffer navigation
 515 =================
 516
 517 .. emacscmd:: notmuch-cycle-notmuch-buffers
 518
 519    |docstring::notmuch-cycle-notmuch-buffers|
 520
 521 Configuration
 522 =============
 523
 524 .. _importing:
 525
 526 Importing Mail
 527 --------------
 528
 529 .. emacscmd:: notmuch-poll
 530
 531    |docstring::notmuch-poll|
 532
 533 .. emacsvar:: notmuch-poll-script
 534
 535    |docstring::notmuch-poll-script|
 536
 537 Sending Mail
 538 ------------
 539
 540 .. emacsvar:: mail-user-agent
 541
 542        Emacs consults the variable :code:`mail-user-agent` to choose a mail
 543        sending package for commands like :code:`report-emacs-bug` and
 544        :code:`compose-mail`.  To use ``notmuch`` for this, customize this
 545        variable to the symbol :code:`notmuch-user-agent`.
 546
 547 .. emacsvar:: message-dont-reply-to-names
 548
 549        When composing mail replies, Emacs's message mode uses the
 550        variable :code:`message-dont-reply-to-names` to exclude
 551        recipients matching a given collection of regular expressions
 552        or satisfying an arbitrary predicate.  Notmuch's MUA inherits
 553        this standard mechanism and will honour your customization of
 554        this variable.
 555
 556 Init File
 557 ---------
 558
 559 When Notmuch is loaded, it will read the ``notmuch-init-file``
 560 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
 561 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
 562 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
 563 suffix exist it will be read instead (just one of these, chosen in this
 564 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
 565 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
 566 options, ``notmuch-init-file`` is not read.