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