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