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