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