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
 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-show-depth-limit`
 281        |docstring::notmuch-show-depth-limit|
 282
 283 :index:`notmuch-show-height-limit`
 284        |docstring::notmuch-show-height-limit|
 285
 286 :index:`notmuch-show-max-text-part-size`
 287        |docstring::notmuch-show-max-text-part-size|
 288
 289 :index:`notmuch-multipart/alternative-discouraged`
 290
 291    Which mime types to hide by default for multipart messages.
 292
 293    Can either be a list of mime types (as strings) or a function
 294    mapping a plist representing the current message to such a list.
 295    The following example function would discourage `text/html` and
 296    `multipart/related` generally, but discourage `text/plain` should
 297    the message be sent from `whatever@example.com`.
 298
 299    .. code:: lisp
 300
 301       (defun my--determine-discouraged (msg)
 302         (let* ((headers (plist-get msg :headers))
 303                (from (or (plist-get headers :From) "")))
 304           (cond
 305            ((string-match "whatever@example.com" from)
 306             (list "text/plain"))
 307            (t
 308             (list "text/html" "multipart/related")))))
 309
 310 .. _show-copy:
 311
 312 Copy to kill-ring
 313 -----------------
 314
 315 You can use the usually Emacs ways of copying text to the kill-ring,
 316 but notmuch also provides some shortcuts. These keys are available in
 317 :ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available
 318 in :ref:`notmuch-search`.
 319
 320 ``c F`` ``notmuch-show-stash-filename``
 321    |docstring::notmuch-show-stash-filename|
 322
 323 ``c G`` ``notmuch-show-stash-git-send-email``
 324    |docstring::notmuch-show-stash-git-send-email|
 325
 326 ``c I`` ``notmuch-show-stash-message-id-stripped``
 327    |docstring::notmuch-show-stash-message-id-stripped|
 328
 329 ``c L`` ``notmuch-show-stash-mlarchive-link-and-go``
 330    |docstring::notmuch-show-stash-mlarchive-link-and-go|
 331
 332 ``c T`` ``notmuch-show-stash-tags``
 333    |docstring::notmuch-show-stash-tags|
 334
 335 ``c c`` ``notmuch-show-stash-cc``
 336    |docstring::notmuch-show-stash-cc|
 337
 338 ``c d`` ``notmuch-show-stash-date``
 339    |docstring::notmuch-show-stash-date|
 340
 341 ``c f`` ``notmuch-show-stash-from``
 342    |docstring::notmuch-show-stash-from|
 343
 344 ``c i`` ``notmuch-show-stash-message-id``
 345    |docstring::notmuch-show-stash-message-id|
 346
 347 ``c l`` ``notmuch-show-stash-mlarchive-link``
 348    |docstring::notmuch-show-stash-mlarchive-link|
 349
 350 ``c s`` ``notmuch-show-stash-subject``
 351    |docstring::notmuch-show-stash-subject|
 352
 353 ``c t`` ``notmuch-show-stash-to``
 354    |docstring::notmuch-show-stash-to|
 355
 356 ``c ?``
 357     Show all available copying commands
 358
 359 .. _notmuch-tree:
 360
 361 notmuch-tree
 362 ============
 363
 364 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
 365 email archives. Each line in the buffer represents a single
 366 message giving the relative date, the author, subject, and any
 367 tags.
 368
 369 ``c``
 370     :ref:`show-copy`
 371
 372 ``<return>``
 373    Displays that message.
 374
 375 ``N``
 376     Move to next message
 377
 378 ``P``
 379     Move to previous message
 380
 381 ``n``
 382     Move to next matching message
 383
 384 ``p``
 385     Move to previous matching message
 386
 387 ``o`` ``notmuch-tree-toggle-order``
 388    |docstring::notmuch-tree-toggle-order|
 389
 390 ``l`` ``notmuch-tree-filter``
 391    Filter or LIMIT the current search results based on an additional query string
 392
 393 ``t`` ``notmuch-tree-filter-by-tag``
 394    Filter the current search results based on an additional tag
 395
 396
 397 ``g`` ``=``
 398     Refresh the buffer
 399
 400 ``?``
 401     Display full set of key bindings
 402
 403 As is the case with :ref:`notmuch-search`, the presentation of results
 404 can be controlled by the variable ``notmuch-search-oldest-first``.
 405
 406 .. _notmuch-unthreaded:
 407
 408 notmuch-unthreaded
 409 ------------------
 410
 411 ``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
 412 each line corresponds to a single message, but no thread information
 413 is presented.
 414
 415 Keybindings are the same as :any:`notmuch-tree`.
 416
 417 Global key bindings
 418 ===================
 419
 420 Several features are accessible from most places in notmuch through the
 421 following key bindings:
 422
 423 ``j``
 424     Jump to saved searches using :ref:`notmuch-jump`.
 425
 426 ``k``
 427     Tagging operations using :ref:`notmuch-tag-jump`
 428
 429 ``C-_`` ``C-/`` ``C-x u``: Undo previous tagging operation using :ref:`notmuch-tag-undo`
 430
 431 .. _notmuch-jump:
 432
 433 notmuch-jump
 434 ------------
 435
 436 Saved searches configured through :ref:`saved-searches` can
 437 include a "shortcut key" that's accessible through notmuch-jump.
 438 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
 439 key of a saved search will immediately jump to that saved search.  For
 440 example, in the default configuration ``j i`` jumps immediately to the
 441 inbox search.  When you press ``j``, notmuch-jump shows the saved
 442 searches and their shortcut keys in the mini-buffer.
 443
 444 .. _notmuch-tag-jump:
 445
 446 notmuch-tag-jump
 447 ----------------
 448
 449 Tagging operations configured through ``notmuch-tagging-keys`` can
 450 be accessed via :kbd:`k` in :ref:`notmuch-show`,
 451 :ref:`notmuch-search` and :ref:`notmuch-tree`.  With a
 452 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
 453 operations specified in ``notmuch-tagging-keys``; i.e. each
 454 ``+tag`` is replaced by ``-tag`` and vice versa.
 455
 456 :index:`notmuch-tagging-keys`
 457
 458   |docstring::notmuch-tagging-keys|
 459
 460 .. _notmuch-tag-undo:
 461
 462 notmuch-tag-undo
 463 ----------------
 464
 465 Each notmuch buffer supporting tagging operations (i.e buffers in
 466 :any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
 467 :any:`notmuch-unthreaded` mode) keeps a local stack of tagging
 468 operations. These can be undone via ``notmuch-tag-undo``. By default
 469 this is bound to the usual Emacs keys for undo.
 470
 471 :index:`notmuch-tag-undo`
 472
 473    |docstring::notmuch-tag-undo|
 474
 475 Buffer navigation
 476 =================
 477
 478 :index:`notmuch-cycle-notmuch-buffers`
 479    |docstring::notmuch-cycle-notmuch-buffers|
 480
 481 Configuration
 482 =============
 483
 484 .. _importing:
 485
 486 Importing Mail
 487 --------------
 488
 489 :index:`notmuch-poll`
 490    |docstring::notmuch-poll|
 491
 492 :index:`notmuch-poll-script`
 493    |docstring::notmuch-poll-script|
 494
 495 Sending Mail
 496 ------------
 497
 498 :index:`mail-user-agent`
 499
 500        Emacs consults the variable :code:`mail-user-agent` to choose a mail
 501        sending package for commands like :code:`report-emacs-bug` and
 502        :code:`compose-mail`.  To use ``notmuch`` for this, customize this
 503        variable to the symbol :code:`notmuch-user-agent`.
 504
 505 :index:`message-dont-reply-to-names`
 506
 507        When composing mail replies, Emacs's message mode uses the
 508        variable :code:`message-dont-reply-to-names` to exclude
 509        recipients matching a given collection of regular expressions
 510        or satisfying an arbitrary predicate.  Notmuch's MUA inherits
 511        this standard mechanism and will honour your customization of
 512        this variable.
 513
 514 Init File
 515 ---------
 516
 517 When Notmuch is loaded, it will read the ``notmuch-init-file``
 518 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
 519 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
 520 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
 521 suffix exist it will be read instead (just one of these, chosen in this
 522 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
 523 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
 524 options, ``notmuch-init-file`` is not read.