git.cworth.org Git - notmuch-old/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` and
 257    :emacsvar:`notmuch-unthreaded-result-format`.
 258
 259 .. emacsvar:: notmuch-search-oldest-first
 260
 261     Display the oldest threads at the top of the buffer
 262
 263 It is also possible to customize how the name of buffers containing
 264 search results is formatted using the following variables:
 265
 266 .. emacsvar:: notmuch-search-buffer-name-format
 267
 268        |docstring::notmuch-search-buffer-name-format|
 269
 270 .. emacsvar:: notmuch-saved-search-buffer-name-format
 271
 272        |docstring::notmuch-saved-search-buffer-name-format|
 273
 274
 275 .. _notmuch-show:
 276
 277 notmuch-show
 278 ============
 279
 280 ``notmuch-show-mode`` is used to display a single thread of email from
 281 your email archives.
 282
 283 By default, various components of email messages, (citations,
 284 signatures, already-read messages), are hidden. You can make
 285 these parts visible by clicking with the mouse button or by
 286 pressing RET after positioning the cursor on a hidden part.
 287
 288 ``<space>``
 289     Scroll the current message (if necessary),
 290     advance to the next message, or advance to the next thread (if
 291     already on the last message of a thread).
 292
 293 ``c``
 294     :ref:`show-copy`
 295
 296 ``N``
 297     Move to next message
 298
 299 ``P``
 300     Move to previous message (or start of current message)
 301
 302 ``n``
 303     Move to next matching message
 304
 305 ``p``
 306     Move to previous matching message
 307
 308 ``+,-``
 309     Add or remove arbitrary tags from the current message.
 310
 311 ``!``
 312     |docstring::notmuch-show-toggle-elide-non-matching|
 313
 314 ``?``
 315     Display full set of key bindings
 316
 317 Display of messages can be controlled by the following variables; see also :ref:`show-large`.
 318
 319 .. emacsvar:: notmuch-message-headers
 320
 321        |docstring::notmuch-message-headers|
 322
 323 .. emacsvar:: notmuch-message-headers-visible
 324
 325        |docstring::notmuch-message-headers-visible|
 326
 327 .. emacsvar:: notmuch-show-header-line
 328
 329        |docstring::notmuch-show-header-line|
 330
 331 .. emacsvar:: notmuch-multipart/alternative-discouraged
 332
 333    Which mime types to hide by default for multipart messages.
 334
 335    Can either be a list of mime types (as strings) or a function
 336    mapping a plist representing the current message to such a list.
 337    The following example function would discourage `text/html` and
 338    `multipart/related` generally, but discourage `text/plain` should
 339    the message be sent from `whatever@example.com`.
 340
 341    .. code:: lisp
 342
 343       (defun my--determine-discouraged (msg)
 344         (let* ((headers (plist-get msg :headers))
 345                (from (or (plist-get headers :From) "")))
 346           (cond
 347            ((string-match "whatever@example.com" from)
 348             (list "text/plain"))
 349            (t
 350             (list "text/html" "multipart/related")))))
 351
 352 .. _show-large:
 353
 354 Dealing with large messages and threads
 355 ---------------------------------------
 356
 357 If you are finding :ref:`notmuch-show` is annoyingly slow displaying
 358 large messages, you can customize
 359 :emacsvar:`notmuch-show-max-text-part-size`.  If you want to speed up the
 360 display of large threads (with or without large messages), there are
 361 several options.  First, you can display the same query in one of the
 362 other modes. :ref:`notmuch-unthreaded` is the most robust for
 363 extremely large queries, but :ref:`notmuch-tree` is also be faster
 364 than :ref:`notmuch-show` in general, since it only renders a single
 365 message a time. If you prefer to stay with the rendered thread
 366 ("conversation") view of :ref:`notmuch-show`, you can customize the
 367 variables :emacsvar:`notmuch-show-depth-limit`,
 368 :emacsvar:`notmuch-show-height-limit` and
 369 :emacsvar:`notmuch-show-max-text-part-size` to limit the amount of
 370 rendering done initially. Note that these limits are implicitly
 371 *OR*-ed together, and combinations might have surprising effects.
 372
 373 .. emacsvar:: notmuch-show-depth-limit
 374
 375        |docstring::notmuch-show-depth-limit|
 376
 377 .. emacsvar:: notmuch-show-height-limit
 378
 379        |docstring::notmuch-show-height-limit|
 380
 381 .. emacsvar:: notmuch-show-max-text-part-size
 382
 383        |docstring::notmuch-show-max-text-part-size|
 384
 385 .. _show-copy:
 386
 387 Copy to kill-ring
 388 -----------------
 389
 390 You can use the usually Emacs ways of copying text to the kill-ring,
 391 but notmuch also provides some shortcuts. These keys are available in
 392 :ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available
 393 in :ref:`notmuch-search`.
 394
 395 ``c F`` ``notmuch-show-stash-filename``
 396    |docstring::notmuch-show-stash-filename|
 397
 398 ``c G`` ``notmuch-show-stash-git-send-email``
 399    |docstring::notmuch-show-stash-git-send-email|
 400
 401 ``c I`` ``notmuch-show-stash-message-id-stripped``
 402    |docstring::notmuch-show-stash-message-id-stripped|
 403
 404 ``c L`` ``notmuch-show-stash-mlarchive-link-and-go``
 405    |docstring::notmuch-show-stash-mlarchive-link-and-go|
 406
 407 ``c T`` ``notmuch-show-stash-tags``
 408    |docstring::notmuch-show-stash-tags|
 409
 410 ``c c`` ``notmuch-show-stash-cc``
 411    |docstring::notmuch-show-stash-cc|
 412
 413 ``c d`` ``notmuch-show-stash-date``
 414    |docstring::notmuch-show-stash-date|
 415
 416 ``c f`` ``notmuch-show-stash-from``
 417    |docstring::notmuch-show-stash-from|
 418
 419 ``c i`` ``notmuch-show-stash-message-id``
 420    |docstring::notmuch-show-stash-message-id|
 421
 422 ``c l`` ``notmuch-show-stash-mlarchive-link``
 423    |docstring::notmuch-show-stash-mlarchive-link|
 424
 425 ``c s`` ``notmuch-show-stash-subject``
 426    |docstring::notmuch-show-stash-subject|
 427
 428 ``c t`` ``notmuch-show-stash-to``
 429    |docstring::notmuch-show-stash-to|
 430
 431 ``c ?``
 432     Show all available copying commands
 433
 434 .. _emacs-show-duplicates:
 435
 436 Dealing with duplicates
 437 -----------------------
 438
 439 If there are are multiple files with the same :mailheader:`Message-ID`
 440 (see :any:`duplicate-files`), then :any:`notmuch-show` displays the
 441 number of duplicates and identifies the current duplicate. In the
 442 following example duplicate 3 of 5 is displayed.
 443
 444 .. code-block::
 445    :emphasize-lines: 1
 446
 447     M. Mustermann <max@example.com> (Sat, 30 Jul 2022 10:33:10 -0300) (inbox signed)      3/5
 448     Subject: Re: Multiple files per message in emacs
 449     To: notmuch@notmuchmail.org
 450
 451 To display a different message file with the same
 452 :mailheader:`Message-ID`, the user can run the command
 453 :emacscmd:`notmuch-show-choose-duplicate`, by default bound to `%`.
 454
 455 .. emacscmd:: notmuch-show-choose-duplicate
 456
 457    |docstring::notmuch-show-choose-duplicate|
 458
 459 .. _notmuch-tree:
 460
 461 notmuch-tree
 462 ============
 463
 464 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
 465 email archives. Each line in the buffer represents a single
 466 message giving the relative date, the author, subject, and any
 467 tags.
 468
 469 ``c``
 470     :ref:`show-copy`
 471
 472 ``<return>``
 473    Displays that message.
 474
 475 ``N``
 476     Move to next message
 477
 478 ``P``
 479     Move to previous message
 480
 481 ``n``
 482     Move to next matching message
 483
 484 ``p``
 485     Move to previous matching message
 486
 487 ``o`` ``notmuch-tree-toggle-order``
 488    |docstring::notmuch-tree-toggle-order|
 489
 490 ``l`` ``notmuch-tree-filter``
 491    Filter or LIMIT the current search results based on an additional query string
 492
 493 ``t`` ``notmuch-tree-filter-by-tag``
 494    Filter the current search results based on an additional tag
 495
 496
 497 ``g`` ``=``
 498     Refresh the buffer
 499
 500 ``?``
 501     Display full set of key bindings
 502
 503 As is the case with :ref:`notmuch-search`, the presentation of results
 504 can be controlled by the variable ``notmuch-search-oldest-first``.
 505
 506 .. emacsvar:: notmuch-tree-result-format
 507
 508    |docstring::notmuch-tree-result-format|
 509
 510    The following example shows how to optionally display recipients instead
 511    of authors for sent mail (assuming the user is named Mustermann).
 512
 513    .. code:: lisp
 514
 515       (defun -notmuch-authors-or-to (format-string result)
 516         (let* ((headers (plist-get result :headers))
 517                (to (plist-get headers :To))
 518                (author (plist-get headers :From))
 519                (face (if (plist-get result :match)
 520                          'notmuch-tree-match-author-face
 521                        'notmuch-tree-no-match-author-face)))
 522           (propertize
 523            (format format-string
 524                    (if (string-match "Mustermann" author)
 525                        (concat "To:" (notmuch-tree-clean-address to))
 526                      author))
 527            'face face)))
 528
 529       (setq notmuch-tree-result-format
 530             '(("date" . "%12s  ")
 531               (-notmuch-authors-or-to . "%-20.20s")
 532               ((("tree" . "%s")
 533                 ("subject" . "%s"))
 534                . " %-54s ")
 535               ("tags" . "(%s)")))
 536
 537    See also :emacsvar:`notmuch-search-result-format` and
 538    :emacsvar:`notmuch-unthreaded-result-format`.
 539
 540
 541 .. _notmuch-unthreaded:
 542
 543 notmuch-unthreaded
 544 ------------------
 545
 546 ``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
 547 each line corresponds to a single message, but no thread information
 548 is presented.
 549
 550 Keybindings are the same as :any:`notmuch-tree`.
 551
 552 .. emacsvar:: notmuch-unthreaded-result-format
 553
 554    |docstring::notmuch-unthreaded-result-format|
 555
 556    See also :emacsvar:`notmuch-search-result-format` and
 557    :emacsvar:`notmuch-tree-result-format`.
 558
 559 Global key bindings
 560 ===================
 561
 562 Several features are accessible from most places in notmuch through the
 563 following key bindings:
 564
 565 ``j``
 566     Jump to saved searches using :ref:`notmuch-jump`.
 567
 568 ``k``
 569     Tagging operations using :ref:`notmuch-tag-jump`
 570
 571 ``C-_`` ``C-/`` ``C-x u``: Undo previous tagging operation using :ref:`notmuch-tag-undo`
 572
 573 .. _notmuch-jump:
 574
 575 notmuch-jump
 576 ------------
 577
 578 Saved searches configured through :ref:`saved-searches` can
 579 include a "shortcut key" that's accessible through notmuch-jump.
 580 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
 581 key of a saved search will immediately jump to that saved search.  For
 582 example, in the default configuration ``j i`` jumps immediately to the
 583 inbox search.  When you press ``j``, notmuch-jump shows the saved
 584 searches and their shortcut keys in the mini-buffer.
 585
 586 .. _notmuch-tag-jump:
 587
 588 notmuch-tag-jump
 589 ----------------
 590
 591 Tagging operations configured through ``notmuch-tagging-keys`` can
 592 be accessed via :kbd:`k` in :ref:`notmuch-show`,
 593 :ref:`notmuch-search` and :ref:`notmuch-tree`.  With a
 594 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
 595 operations specified in ``notmuch-tagging-keys``; i.e. each
 596 ``+tag`` is replaced by ``-tag`` and vice versa.
 597
 598 .. emacsvar:: notmuch-tagging-keys
 599
 600   |docstring::notmuch-tagging-keys|
 601
 602 .. _notmuch-tag-undo:
 603
 604 notmuch-tag-undo
 605 ----------------
 606
 607 Each notmuch buffer supporting tagging operations (i.e buffers in
 608 :any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
 609 :any:`notmuch-unthreaded` mode) keeps a local stack of tagging
 610 operations. These can be undone via :emacscmd:`notmuch-tag-undo`. By default
 611 this is bound to the usual Emacs keys for undo.
 612
 613 .. emacscmd:: notmuch-tag-undo
 614
 615    |docstring::notmuch-tag-undo|
 616
 617 Buffer navigation
 618 =================
 619
 620 .. emacscmd:: notmuch-cycle-notmuch-buffers
 621
 622    |docstring::notmuch-cycle-notmuch-buffers|
 623
 624 Configuration
 625 =============
 626
 627 .. _importing:
 628
 629 Importing Mail
 630 --------------
 631
 632 .. emacscmd:: notmuch-poll
 633
 634    |docstring::notmuch-poll|
 635
 636 .. emacsvar:: notmuch-poll-script
 637
 638    |docstring::notmuch-poll-script|
 639
 640 Sending Mail
 641 ------------
 642
 643 .. emacsvar:: mail-user-agent
 644
 645        Emacs consults the variable :code:`mail-user-agent` to choose a mail
 646        sending package for commands like :code:`report-emacs-bug` and
 647        :code:`compose-mail`.  To use ``notmuch`` for this, customize this
 648        variable to the symbol :code:`notmuch-user-agent`.
 649
 650 .. emacsvar:: message-dont-reply-to-names
 651
 652        When composing mail replies, Emacs's message mode uses the
 653        variable :code:`message-dont-reply-to-names` to exclude
 654        recipients matching a given collection of regular expressions
 655        or satisfying an arbitrary predicate.  Notmuch's MUA inherits
 656        this standard mechanism and will honour your customization of
 657        this variable.
 658
 659 Init File
 660 ---------
 661
 662 When Notmuch is loaded, it will read the ``notmuch-init-file``
 663 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
 664 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
 665 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
 666 suffix exist it will be read instead (just one of these, chosen in this
 667 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
 668 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
 669 options, ``notmuch-init-file`` is not read.