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