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 :index:`notmuch-hello-sections`
  54        |docstring::notmuch-hello-sections|
  55
  56 :index:`notmuch-hello-thousands-separator`
  57        |docstring::notmuch-hello-thousands-separator|
  58
  59 :index:`notmuch-show-logo`
  60        |docstring::notmuch-show-logo|
  61
  62 :index:`!notmuch-column-control`
  63     Controls the number of columns for saved searches/tags in notmuch view.
  64
  65     This variable has three potential types of values:
  66
  67     .. describe:: t
  68
  69        Automatically calculate the number of columns possible based
  70        on the tags to be shown and the window width.
  71
  72     .. describe:: integer <n>
  73
  74        A lower bound on the number of characters that will
  75        be used to display each column.
  76
  77     .. describe:: float <f>
  78
  79        A fraction of the window width that is the lower bound on the
  80        number of characters that should be used for each column.
  81
  82     So:
  83
  84     - if you would like two columns of tags, set this to 0.5.
  85
  86     - if you would like a single column of tags, set this to 1.0.
  87
  88     - if you would like tags to be 30 characters wide, set this to 30.
  89
  90     - if you don't want to worry about all of this nonsense, leave
  91       this set to `t`.
  92
  93
  94 notmuch-hello key bindings
  95 --------------------------
  96
  97 ``<tab>``
  98     Move to the next widget (button or text entry field)
  99
 100 ``<backtab>``
 101     Move to the previous widget.
 102
 103 ``<return>``
 104     Activate the current widget.
 105
 106 ``g`` ``=``
 107     Refresh the buffer; mainly update the counts of messages for various
 108     saved searches.
 109
 110 ``G``
 111     Import mail, See :ref:`importing`
 112
 113 ``m``
 114     Compose a message
 115
 116 ``s``
 117     Search the notmuch database using :ref:`notmuch-search`
 118
 119 ``v``
 120     Print notmuch version
 121
 122 ``q``
 123     Quit
 124
 125 .. _saved-searches:
 126
 127 Saved Searches
 128 --------------
 129
 130 Since notmuch is entirely search-based, it's often useful to organize
 131 mail around common searches.  To facilitate this, the first section of
 132 notmuch-hello presents a customizable set of saved searches.  Saved
 133 searches can also be accessed from anywhere in notmuch by pressing
 134 ``j`` to access :ref:`notmuch-jump`.
 135
 136 The saved searches default to various common searches such as
 137 ``tag:inbox`` to access the inbox and ``tag:unread`` to access all
 138 unread mail, but there are several options for customization:
 139
 140 :index:`notmuch-saved-searches`
 141     The list of saved searches, including names, queries, and
 142     additional per-query options.
 143
 144 :index:`notmuch-saved-search-sort-function`
 145     This variable controls how saved searches should be sorted. A value
 146     of ``nil`` displays the saved searches in the order they are stored
 147     in ‘notmuch-saved-searches’.
 148
 149 :index:`notmuch-column-control`
 150     Controls the number of columns for displaying saved-searches/tags
 151
 152 Search Box
 153 ----------
 154
 155 The search box lets the user enter a Notmuch query. See section
 156 “Description” in Notmuch Query Syntax, for more info on Notmuch query
 157 syntax. A history of recent searches is also displayed by default. The
 158 latter is controlled by the variable :index:`notmuch-hello-recent-searches-max`.
 159
 160 Known Tags
 161 ----------
 162
 163 One special kind of saved search provided by default is for each
 164 individual tag defined in the database. This can be controlled via the
 165 following variables.
 166
 167 :index:`notmuch-hello-tag-list-make-query`
 168     Control how to construct a search (“virtual folder”) from a given
 169     tag.
 170
 171 :index:`notmuch-hello-hide-tags`
 172     Which tags not to display at all.
 173
 174 :index:`notmuch-column-control`
 175     Controls the number of columns for displaying saved-searches/tags
 176
 177 .. _notmuch-search:
 178
 179 notmuch-search
 180 ==============
 181
 182 ``notmuch-search-mode`` is used to display the results from executing
 183 a query via ``notmuch-search``. The syntax for these queries is the
 184 the same as :ref:`saved-searches`. For details of this syntax see
 185 info:notmuch-search-terms
 186
 187 By default the output approximates that of the command line See section
 188 “Description” in notmuch search command.
 189
 190 The main purpose of the ``notmuch-search-mode`` buffer is to act as a
 191 menu of results that the user can explore further by pressing
 192 ``<return>`` on the appropriate line.
 193
 194 ``n,C-n,<down>``
 195     Move to next line
 196
 197 ``p,C-p,<up>``
 198     Move to previous line
 199
 200 ``<return>``
 201     Open thread on current line in :ref:`notmuch-show` mode
 202
 203 ``g`` ``=``
 204     Refresh the buffer
 205
 206 ``?``
 207     Display full set of key bindings
 208
 209 The presentation of results can be controlled by the following
 210 variables.
 211
 212 :index:`notmuch-search-result-format`
 213     Control how each thread of messages is presented in the
 214     ``notmuch-show-mode`` buffer
 215
 216 :index:`notmuch-search-oldest-first`
 217     Display the oldest threads at the top of the buffer
 218
 219 It is also possible to customize how the name of buffers containing
 220 search results is formatted using the following variables:
 221
 222 :index:`notmuch-search-buffer-name-format`
 223        |docstring::notmuch-search-buffer-name-format|
 224
 225 :index:`notmuch-saved-search-buffer-name-format`
 226        |docstring::notmuch-saved-search-buffer-name-format|
 227
 228
 229 .. _notmuch-show:
 230
 231 notmuch-show
 232 ============
 233
 234 ``notmuch-show-mode`` is used to display a single thread of email from
 235 your email archives.
 236
 237 By default, various components of email messages, (citations,
 238 signatures, already-read messages), are hidden. You can make
 239 these parts visible by clicking with the mouse button or by
 240 pressing RET after positioning the cursor on a hidden part.
 241
 242 ``<space>``
 243     Scroll the current message (if necessary),
 244     advance to the next message, or advance to the next thread (if
 245     already on the last message of a thread).
 246
 247 ``c``
 248     :ref:`show-copy`
 249
 250 ``N``
 251     Move to next message
 252
 253 ``P``
 254     Move to previous message (or start of current message)
 255
 256 ``n``
 257     Move to next matching message
 258
 259 ``p``
 260     Move to previous matching message
 261
 262 ``+,-``
 263     Add or remove arbitrary tags from the current message.
 264
 265 ``!``
 266     |docstring::notmuch-show-toggle-elide-non-matching|
 267
 268 ``?``
 269     Display full set of key bindings
 270
 271 Display of messages can be controlled by the following variables; see also :ref:`show-large`.
 272
 273 :index:`notmuch-message-headers`
 274        |docstring::notmuch-message-headers|
 275
 276 :index:`notmuch-message-headers-visible`
 277        |docstring::notmuch-message-headers-visible|
 278
 279 :index:`notmuch-show-header-line`
 280        |docstring::notmuch-show-header-line|
 281
 282 :index:`notmuch-multipart/alternative-discouraged`
 283
 284    Which mime types to hide by default for multipart messages.
 285
 286    Can either be a list of mime types (as strings) or a function
 287    mapping a plist representing the current message to such a list.
 288    The following example function would discourage `text/html` and
 289    `multipart/related` generally, but discourage `text/plain` should
 290    the message be sent from `whatever@example.com`.
 291
 292    .. code:: lisp
 293
 294       (defun my--determine-discouraged (msg)
 295         (let* ((headers (plist-get msg :headers))
 296                (from (or (plist-get headers :From) "")))
 297           (cond
 298            ((string-match "whatever@example.com" from)
 299             (list "text/plain"))
 300            (t
 301             (list "text/html" "multipart/related")))))
 302
 303 .. _show-large:
 304
 305 Dealing with large messages and threads
 306 ---------------------------------------
 307
 308 If you are finding :ref:`notmuch-show` is annoyingly slow displaying
 309 large messages, you can customize
 310 :index:`notmuch-show-max-text-part-size`.  If you want to speed up the
 311 display of large threads (with or without large messages), there are
 312 several options.  First, you can display the same query in one of the
 313 other modes. :ref:`notmuch-unthreaded` is the most robust for
 314 extremely large queries, but :ref:`notmuch-tree` is also be faster
 315 than :ref:`notmuch-show` in general, since it only renders a single
 316 message a time. If you prefer to stay with the rendered thread
 317 ("conversation") view of :ref:`notmuch-show`, you can customize the
 318 variables :index:`notmuch-show-depth-limit`,
 319 :index:`notmuch-show-height-limit` and
 320 :index:`notmuch-show-max-text-part-size` to limit the amount of
 321 rendering done initially. Note that these limits are implicitly
 322 *OR*-ed together, and combinations might have surprising effects.
 323
 324 :index:`notmuch-show-depth-limit`
 325        |docstring::notmuch-show-depth-limit|
 326
 327 :index:`notmuch-show-height-limit`
 328        |docstring::notmuch-show-height-limit|
 329
 330 :index:`notmuch-show-max-text-part-size`
 331        |docstring::notmuch-show-max-text-part-size|
 332
 333 .. _show-copy:
 334
 335 Copy to kill-ring
 336 -----------------
 337
 338 You can use the usually Emacs ways of copying text to the kill-ring,
 339 but notmuch also provides some shortcuts. These keys are available in
 340 :ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available
 341 in :ref:`notmuch-search`.
 342
 343 ``c F`` ``notmuch-show-stash-filename``
 344    |docstring::notmuch-show-stash-filename|
 345
 346 ``c G`` ``notmuch-show-stash-git-send-email``
 347    |docstring::notmuch-show-stash-git-send-email|
 348
 349 ``c I`` ``notmuch-show-stash-message-id-stripped``
 350    |docstring::notmuch-show-stash-message-id-stripped|
 351
 352 ``c L`` ``notmuch-show-stash-mlarchive-link-and-go``
 353    |docstring::notmuch-show-stash-mlarchive-link-and-go|
 354
 355 ``c T`` ``notmuch-show-stash-tags``
 356    |docstring::notmuch-show-stash-tags|
 357
 358 ``c c`` ``notmuch-show-stash-cc``
 359    |docstring::notmuch-show-stash-cc|
 360
 361 ``c d`` ``notmuch-show-stash-date``
 362    |docstring::notmuch-show-stash-date|
 363
 364 ``c f`` ``notmuch-show-stash-from``
 365    |docstring::notmuch-show-stash-from|
 366
 367 ``c i`` ``notmuch-show-stash-message-id``
 368    |docstring::notmuch-show-stash-message-id|
 369
 370 ``c l`` ``notmuch-show-stash-mlarchive-link``
 371    |docstring::notmuch-show-stash-mlarchive-link|
 372
 373 ``c s`` ``notmuch-show-stash-subject``
 374    |docstring::notmuch-show-stash-subject|
 375
 376 ``c t`` ``notmuch-show-stash-to``
 377    |docstring::notmuch-show-stash-to|
 378
 379 ``c ?``
 380     Show all available copying commands
 381
 382 .. _notmuch-tree:
 383
 384 notmuch-tree
 385 ============
 386
 387 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
 388 email archives. Each line in the buffer represents a single
 389 message giving the relative date, the author, subject, and any
 390 tags.
 391
 392 ``c``
 393     :ref:`show-copy`
 394
 395 ``<return>``
 396    Displays that message.
 397
 398 ``N``
 399     Move to next message
 400
 401 ``P``
 402     Move to previous message
 403
 404 ``n``
 405     Move to next matching message
 406
 407 ``p``
 408     Move to previous matching message
 409
 410 ``o`` ``notmuch-tree-toggle-order``
 411    |docstring::notmuch-tree-toggle-order|
 412
 413 ``l`` ``notmuch-tree-filter``
 414    Filter or LIMIT the current search results based on an additional query string
 415
 416 ``t`` ``notmuch-tree-filter-by-tag``
 417    Filter the current search results based on an additional tag
 418
 419
 420 ``g`` ``=``
 421     Refresh the buffer
 422
 423 ``?``
 424     Display full set of key bindings
 425
 426 As is the case with :ref:`notmuch-search`, the presentation of results
 427 can be controlled by the variable ``notmuch-search-oldest-first``.
 428
 429 .. _notmuch-unthreaded:
 430
 431 notmuch-unthreaded
 432 ------------------
 433
 434 ``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
 435 each line corresponds to a single message, but no thread information
 436 is presented.
 437
 438 Keybindings are the same as :any:`notmuch-tree`.
 439
 440 Global key bindings
 441 ===================
 442
 443 Several features are accessible from most places in notmuch through the
 444 following key bindings:
 445
 446 ``j``
 447     Jump to saved searches using :ref:`notmuch-jump`.
 448
 449 ``k``
 450     Tagging operations using :ref:`notmuch-tag-jump`
 451
 452 ``C-_`` ``C-/`` ``C-x u``: Undo previous tagging operation using :ref:`notmuch-tag-undo`
 453
 454 .. _notmuch-jump:
 455
 456 notmuch-jump
 457 ------------
 458
 459 Saved searches configured through :ref:`saved-searches` can
 460 include a "shortcut key" that's accessible through notmuch-jump.
 461 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
 462 key of a saved search will immediately jump to that saved search.  For
 463 example, in the default configuration ``j i`` jumps immediately to the
 464 inbox search.  When you press ``j``, notmuch-jump shows the saved
 465 searches and their shortcut keys in the mini-buffer.
 466
 467 .. _notmuch-tag-jump:
 468
 469 notmuch-tag-jump
 470 ----------------
 471
 472 Tagging operations configured through ``notmuch-tagging-keys`` can
 473 be accessed via :kbd:`k` in :ref:`notmuch-show`,
 474 :ref:`notmuch-search` and :ref:`notmuch-tree`.  With a
 475 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
 476 operations specified in ``notmuch-tagging-keys``; i.e. each
 477 ``+tag`` is replaced by ``-tag`` and vice versa.
 478
 479 :index:`notmuch-tagging-keys`
 480
 481   |docstring::notmuch-tagging-keys|
 482
 483 .. _notmuch-tag-undo:
 484
 485 notmuch-tag-undo
 486 ----------------
 487
 488 Each notmuch buffer supporting tagging operations (i.e buffers in
 489 :any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
 490 :any:`notmuch-unthreaded` mode) keeps a local stack of tagging
 491 operations. These can be undone via ``notmuch-tag-undo``. By default
 492 this is bound to the usual Emacs keys for undo.
 493
 494 :index:`notmuch-tag-undo`
 495
 496    |docstring::notmuch-tag-undo|
 497
 498 Buffer navigation
 499 =================
 500
 501 :index:`notmuch-cycle-notmuch-buffers`
 502    |docstring::notmuch-cycle-notmuch-buffers|
 503
 504 Configuration
 505 =============
 506
 507 .. _importing:
 508
 509 Importing Mail
 510 --------------
 511
 512 :index:`notmuch-poll`
 513    |docstring::notmuch-poll|
 514
 515 :index:`notmuch-poll-script`
 516    |docstring::notmuch-poll-script|
 517
 518 Sending Mail
 519 ------------
 520
 521 :index:`mail-user-agent`
 522
 523        Emacs consults the variable :code:`mail-user-agent` to choose a mail
 524        sending package for commands like :code:`report-emacs-bug` and
 525        :code:`compose-mail`.  To use ``notmuch`` for this, customize this
 526        variable to the symbol :code:`notmuch-user-agent`.
 527
 528 :index:`message-dont-reply-to-names`
 529
 530        When composing mail replies, Emacs's message mode uses the
 531        variable :code:`message-dont-reply-to-names` to exclude
 532        recipients matching a given collection of regular expressions
 533        or satisfying an arbitrary predicate.  Notmuch's MUA inherits
 534        this standard mechanism and will honour your customization of
 535        this variable.
 536
 537 Init File
 538 ---------
 539
 540 When Notmuch is loaded, it will read the ``notmuch-init-file``
 541 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
 542 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
 543 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
 544 suffix exist it will be read instead (just one of these, chosen in this
 545 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
 546 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
 547 options, ``notmuch-init-file`` is not read.