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