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