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` 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 .. el:define-key:: %
 452    M-x notmuch-show-choose-duplicate
 453
 454    |docstring::notmuch-show-choose-duplicate|
 455
 456 .. _notmuch-tree:
 457
 458 notmuch-tree
 459 ============
 460
 461 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
 462 email archives. Each line in the buffer represents a single
 463 message giving the relative date, the author, subject, and any
 464 tags.
 465
 466 ``c``
 467     :ref:`show-copy`
 468
 469 ``<return>``
 470    Displays that message.
 471
 472 ``N``
 473     Move to next message
 474
 475 ``P``
 476     Move to previous message
 477
 478 ``n``
 479     Move to next matching message
 480
 481 ``p``
 482     Move to previous matching message
 483
 484 ``o`` ``notmuch-tree-toggle-order``
 485    |docstring::notmuch-tree-toggle-order|
 486
 487 ``l`` ``notmuch-tree-filter``
 488    Filter or LIMIT the current search results based on an additional query string
 489
 490 ``t`` ``notmuch-tree-filter-by-tag``
 491    Filter the current search results based on an additional tag
 492
 493
 494 ``g`` ``=``
 495     Refresh the buffer
 496
 497 ``?``
 498     Display full set of key bindings
 499
 500 As is the case with :ref:`notmuch-search`, the presentation of results
 501 can be controlled by the variable ``notmuch-search-oldest-first``.
 502
 503 .. emacsvar:: notmuch-tree-result-format
 504
 505    |docstring::notmuch-tree-result-format|
 506
 507    The following example shows how to optionally display recipients instead
 508    of authors for sent mail (assuming the user is named Mustermann).
 509
 510    .. code:: lisp
 511
 512       (defun -notmuch-authors-or-to (format-string result)
 513         (let* ((headers (plist-get result :headers))
 514                (to (plist-get headers :To))
 515                (author (plist-get headers :From))
 516                (face (if (plist-get result :match)
 517                          'notmuch-tree-match-author-face
 518                        'notmuch-tree-no-match-author-face)))
 519           (propertize
 520            (format format-string
 521                    (if (string-match "Mustermann" author)
 522                        (concat "To:" (notmuch-tree-clean-address to))
 523                      author))
 524            'face face)))
 525
 526       (setq notmuch-tree-result-format
 527             '(("date" . "%12s  ")
 528               (-notmuch-authors-or-to . "%-20.20s")
 529               ((("tree" . "%s")
 530                 ("subject" . "%s"))
 531                . " %-54s ")
 532               ("tags" . "(%s)")))
 533
 534    See also :emacsvar:`notmuch-search-result-format` and
 535    :emacsvar:`notmuch-unthreaded-result-format`.
 536
 537
 538 .. _notmuch-unthreaded:
 539
 540 notmuch-unthreaded
 541 ------------------
 542
 543 ``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
 544 each line corresponds to a single message, but no thread information
 545 is presented.
 546
 547 Keybindings are the same as :any:`notmuch-tree`.
 548
 549 .. emacsvar:: notmuch-unthreaded-result-format
 550
 551    |docstring::notmuch-unthreaded-result-format|
 552
 553    See also :emacsvar:`notmuch-search-result-format` and
 554    :emacsvar:`notmuch-tree-result-format`.
 555
 556 Global key bindings
 557 ===================
 558
 559 Several features are accessible from most places in notmuch through the
 560 following key bindings:
 561
 562 ``j``
 563     Jump to saved searches using :ref:`notmuch-jump`.
 564
 565 ``k``
 566     Tagging operations using :ref:`notmuch-tag-jump`
 567
 568 ``C-_`` ``C-/`` ``C-x u``: Undo previous tagging operation using :any:`notmuch-tag-undo`
 569
 570 .. _notmuch-jump:
 571
 572 notmuch-jump
 573 ------------
 574
 575 Saved searches configured through :ref:`saved-searches` can
 576 include a "shortcut key" that's accessible through notmuch-jump.
 577 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
 578 key of a saved search will immediately jump to that saved search.  For
 579 example, in the default configuration ``j i`` jumps immediately to the
 580 inbox search.  When you press ``j``, notmuch-jump shows the saved
 581 searches and their shortcut keys in the mini-buffer.
 582
 583 .. _notmuch-tag-jump:
 584
 585 notmuch-tag-jump
 586 ----------------
 587
 588 Tagging operations configured through ``notmuch-tagging-keys`` can
 589 be accessed via :kbd:`k` in :ref:`notmuch-show`,
 590 :ref:`notmuch-search` and :ref:`notmuch-tree`.  With a
 591 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
 592 operations specified in ``notmuch-tagging-keys``; i.e. each
 593 ``+tag`` is replaced by ``-tag`` and vice versa.
 594
 595 .. emacsvar:: notmuch-tagging-keys
 596
 597   |docstring::notmuch-tagging-keys|
 598
 599
 600 notmuch-tag-undo
 601 ----------------
 602
 603 Each notmuch buffer supporting tagging operations (i.e buffers in
 604 :any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
 605 :any:`notmuch-unthreaded` mode) keeps a local stack of tagging
 606 operations. These can be undone via :any:`notmuch-tag-undo`. By default
 607 this is bound to the usual Emacs keys for undo.
 608
 609 .. el:define-key::  C-_
 610    C-/
 611    C-x u
 612    M-x notmuch-tag-undo
 613
 614    |docstring::notmuch-tag-undo|
 615
 616 Buffer navigation
 617 =================
 618
 619 .. el:define-key:: M-x notmuch-cycle-notmuch-buffers
 620
 621    |docstring::notmuch-cycle-notmuch-buffers|
 622
 623 Configuration
 624 =============
 625
 626 .. _importing:
 627
 628 Importing Mail
 629 --------------
 630
 631 .. el:define-key:: M-x notmuch-poll
 632
 633    |docstring::notmuch-poll|
 634
 635 .. emacsvar:: notmuch-poll-script
 636
 637    |docstring::notmuch-poll-script|
 638
 639 Sending Mail
 640 ------------
 641
 642 .. emacsvar:: mail-user-agent
 643
 644        Emacs consults the variable :code:`mail-user-agent` to choose a mail
 645        sending package for commands like :code:`report-emacs-bug` and
 646        :code:`compose-mail`.  To use ``notmuch`` for this, customize this
 647        variable to the symbol :code:`notmuch-user-agent`.
 648
 649 .. emacsvar:: message-dont-reply-to-names
 650
 651        When composing mail replies, Emacs's message mode uses the
 652        variable :code:`message-dont-reply-to-names` to exclude
 653        recipients matching a given collection of regular expressions
 654        or satisfying an arbitrary predicate.  Notmuch's MUA inherits
 655        this standard mechanism and will honour your customization of
 656        this variable.
 657
 658 Init File
 659 ---------
 660
 661 When Notmuch is loaded, it will read the ``notmuch-init-file``
 662 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
 663 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
 664 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
 665 suffix exist it will be read instead (just one of these, chosen in this
 666 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
 667 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
 668 options, ``notmuch-init-file`` is not read.