git.cworth.org Git - notmuch/blob - doc/notmuch-emacs.rst

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