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

   1 .. _notmuch-emacs:
   2
   3 ==========================
   4 Emacs Frontend for Notmuch
   5 ==========================
   6
   7 About this Manual
   8 =================
   9
  10 This manual covers only the Emacs interface to Notmuch. For information
  11 on the command line interface, see section “Description” in the Notmuch
  12 Manual Pages. To save typing, we will sometimes use *notmuch* in this
  13 manual to refer to the Emacs interface to Notmuch. When this distinction
  14 is important, we’ll refer to the Emacs interface as
  15 *notmuch-emacs*.
  16
  17 Notmuch-emacs is highly customizable via the Emacs customization
  18 framework (or just by setting the appropriate variables). We try to
  19 point out relevant variables in this manual, but in order to avoid
  20 duplication of information, you can usually find the most detailed
  21 description in the variables' docstring.
  22
  23 notmuch-hello
  24 =============
  25
  26 .. index::
  27    single: notmuch-hello
  28    single: notmuch
  29
  30 ``notmuch-hello`` is the main entry point for Notmuch. You can start it
  31 with ``M-x notmuch`` or ``M-x notmuch-hello``. The startup screen looks
  32 something like the following. There are some hints at the bottom of the
  33 screen. There are three main parts to the notmuch-hello screen,
  34 discussed below. The **bold** text indicates buttons you can click with
  35 a mouse or by positioning the cursor and pressing ``<return>``
  36
  37 |   Welcome to **notmuch** You have 52 messages.
  38 |
  39 | Saved searches: **[edit]**
  40 |
  41 |         52 **inbox**           52 **unread**
  42 |
  43 | Search: ____________________________________
  44 |
  45 | All tags: **[show]**
  46 |
  47 |        Hit \`?' for context-sensitive help in any Notmuch screen.
  48 |                     Customize Notmuch or this page.
  49
  50 You can change the overall appearance of the notmuch-hello screen by
  51 customizing the variables
  52
  53 .. el:defcustom:: notmuch-hello-sections
  54
  55        |docstring::notmuch-hello-sections|
  56
  57 .. el:defcustom:: notmuch-hello-thousands-separator
  58
  59        |docstring::notmuch-hello-thousands-separator|
  60
  61 .. el:defcustom:: notmuch-show-logo
  62
  63        |docstring::notmuch-show-logo|
  64
  65 .. el:defcustom:: notmuch-column-control
  66
  67     Controls the number of columns for saved searches/tags in notmuch view.
  68
  69     This variable has three potential types of values:
  70
  71     .. describe:: t
  72
  73        Automatically calculate the number of columns possible based
  74        on the tags to be shown and the window width.
  75
  76     .. describe:: integer <n>
  77
  78        A lower bound on the number of characters that will
  79        be used to display each column.
  80
  81     .. describe:: float <f>
  82
  83        A fraction of the window width that is the lower bound on the
  84        number of characters that should be used for each column.
  85
  86     So:
  87
  88     - if you would like two columns of tags, set this to 0.5.
  89
  90     - if you would like a single column of tags, set this to 1.0.
  91
  92     - if you would like tags to be 30 characters wide, set this to 30.
  93
  94     - if you don't want to worry about all of this nonsense, leave
  95       this set to `t`.
  96
  97 .. el:defcustom:: notmuch-show-empty-saved-searches
  98
  99    |docstring::notmuch-show-empty-saved-searches|
 100
 101 notmuch-hello key bindings
 102 --------------------------
 103
 104 .. el:define-key:: <tab>
 105
 106     Move to the next widget (button or text entry field)
 107
 108 .. el:define-key:: <backtab>
 109
 110     Move to the previous widget.
 111
 112 .. el:define-key:: <return>
 113
 114     Activate the current widget.
 115
 116 .. el:define-key:: g
 117                    =
 118
 119     Refresh the buffer; mainly update the counts of messages for various
 120     saved searches.
 121
 122 .. el:define-key:: G
 123
 124     Import mail, See :ref:`importing`
 125
 126 .. el:define-key:: m
 127
 128     Compose a message
 129
 130 .. el:define-key:: s
 131
 132     Search the notmuch database using :ref:`notmuch-search`
 133
 134 .. el:define-key:: v
 135
 136     Print notmuch version
 137
 138 .. el:define-key:: q
 139
 140     Quit
 141
 142 .. _saved-searches:
 143
 144 Saved Searches
 145 --------------
 146
 147 Since notmuch is entirely search-based, it's often useful to organize
 148 mail around common searches.  To facilitate this, the first section of
 149 notmuch-hello presents a customizable set of saved searches.  Saved
 150 searches can also be accessed from anywhere in notmuch by pressing
 151 ``j`` to access :ref:`notmuch-jump`.
 152
 153 The saved searches default to various common searches such as
 154 ``tag:inbox`` to access the inbox and ``tag:unread`` to access all
 155 unread mail, but there are several options for customization:
 156
 157 .. el:defcustom:: notmuch-saved-searches
 158
 159     The list of saved searches, including names, queries, and
 160     additional per-query options.
 161
 162 .. el:defcustom:: notmuch-saved-search-sort-function
 163
 164     This variable controls how saved searches should be sorted. A value
 165     of ``nil`` displays the saved searches in the order they are stored
 166     in ‘notmuch-saved-searches’.
 167
 168 Search Box
 169 ----------
 170
 171 The search box lets the user enter a Notmuch query. See section
 172 “Description” in Notmuch Query Syntax, for more info on Notmuch query
 173 syntax. A history of recent searches is also displayed by default. The
 174 latter is controlled by the variable `notmuch-hello-recent-searches-max`.
 175
 176 .. el:defcustom:: notmuch-hello-recent-searches-max
 177
 178               |docstring::notmuch-hello-recent-searches-max|
 179
 180 Known Tags
 181 ----------
 182
 183 One special kind of saved search provided by default is for each
 184 individual tag defined in the database. This can be controlled via the
 185 following variables.
 186
 187 .. el:defcustom:: notmuch-hello-tag-list-make-query
 188
 189     Control how to construct a search (“virtual folder”) from a given
 190     tag.
 191
 192 .. el:defcustom:: notmuch-hello-hide-tags
 193
 194     Which tags not to display at all.
 195
 196 .. _notmuch-search:
 197
 198 notmuch-search
 199 ==============
 200
 201 ``notmuch-search-mode`` is used to display the results from executing
 202 a query via ``notmuch-search``. The syntax for these queries is the
 203 the same as :ref:`saved-searches`. For details of this syntax see
 204 info:notmuch-search-terms
 205
 206 By default the output approximates that of the command line See section
 207 “Description” in notmuch search command.
 208
 209 The main purpose of the ``notmuch-search-mode`` buffer is to act as a
 210 menu of results that the user can explore further by pressing
 211 ``<return>`` on the appropriate line.
 212
 213 .. el:define-key:: n
 214    C-n
 215    <down>
 216
 217     Move to next line
 218
 219 .. el:define-key::
 220    p
 221    C-p
 222    <up>
 223
 224     Move to previous line
 225
 226 .. el:define-key:: <return>
 227
 228     Open thread on current line in :ref:`notmuch-show` mode
 229
 230 .. el:define-key:: g
 231    =
 232
 233     Refresh the buffer
 234
 235 .. el:define-key:: ?
 236
 237     Display full set of key bindings
 238
 239 The presentation of results can be controlled by the following
 240 variables.
 241
 242 .. el:defcustom:: notmuch-search-result-format
 243
 244    |docstring::notmuch-search-result-format|
 245
 246    If the car of an element in notmuch-search-result-format is a
 247    function, insert the result of calling the function into the buffer.
 248
 249    This allows a user to generate custom fields in the output of a
 250    search result. For example, with the following settings, the first
 251    few characters on each line of the search result are used to show
 252    information about some significant tags associated with the thread.
 253
 254    .. code:: lisp
 255
 256       (defun -notmuch-result-flags (format-string result)
 257         (let ((tags-to-letters '(("flagged" . "!")
 258                                  ("unread" . "u")
 259                                  ("mine" . "m")
 260                                  ("sent" . "s")
 261                                  ("replied" . "r")))
 262               (tags (plist-get result :tags)))
 263           (format format-string
 264                   (mapconcat (lambda (t2l)
 265                                (if (member (car t2l) tags)
 266                                    (cdr t2l)
 267                                  " "))
 268                              tags-to-letters ""))))
 269
 270       (setq notmuch-search-result-format '((-notmuch-result-flags . "%s ")
 271                                            ("date" . "%12s ")
 272                                            ("count" . "%9s ")
 273                                            ("authors" . "%-30s ")
 274                                            ("subject" . "%s ")
 275                                            ("tags" . "(%s)")))
 276
 277    See also :el:defcustom:`notmuch-tree-result-format` and
 278    :el:defcustom:`notmuch-unthreaded-result-format`.
 279
 280 .. el:defcustom:: notmuch-search-oldest-first
 281
 282     Display the oldest threads at the top of the buffer
 283
 284 It is also possible to customize how the name of buffers containing
 285 search results is formatted using the following variables:
 286
 287 .. el:defcustom:: notmuch-search-buffer-name-format
 288
 289        |docstring::notmuch-search-buffer-name-format|
 290
 291 .. el:defcustom:: notmuch-saved-search-buffer-name-format
 292
 293        |docstring::notmuch-saved-search-buffer-name-format|
 294
 295
 296 .. _notmuch-show:
 297
 298 notmuch-show
 299 ============
 300
 301 ``notmuch-show-mode`` is used to display a single thread of email from
 302 your email archives.
 303
 304 By default, various components of email messages, (citations,
 305 signatures, already-read messages), are hidden. You can make
 306 these parts visible by clicking with the mouse button or by
 307 pressing RET after positioning the cursor on a hidden part.
 308
 309 .. el:define-key:: <space>
 310
 311     Scroll the current message (if necessary),
 312     advance to the next message, or advance to the next thread (if
 313     already on the last message of a thread).
 314
 315 .. el:define-key:: c
 316
 317     :ref:`show-copy`
 318
 319 .. el:define-key:: N
 320
 321     Move to next message
 322
 323 .. el:define-key:: P
 324
 325     Move to previous message (or start of current message)
 326
 327 .. el:define-key:: n
 328
 329     Move to next matching message
 330
 331 .. el:define-key:: p
 332
 333     Move to previous matching message
 334
 335 .. el:define-key:: +
 336                    -
 337
 338     Add or remove arbitrary tags from the current message.
 339
 340 .. el:define-key:: !
 341
 342     |docstring::notmuch-show-toggle-elide-non-matching|
 343
 344 .. el:define-key:: ?
 345
 346     Display full set of key bindings
 347
 348 Display of messages can be controlled by the following variables; see also :ref:`show-large`.
 349
 350 .. el:defcustom:: notmuch-message-headers
 351
 352        |docstring::notmuch-message-headers|
 353
 354 .. el:defcustom:: notmuch-message-headers-visible
 355
 356        |docstring::notmuch-message-headers-visible|
 357
 358 .. el:defcustom:: notmuch-show-header-line
 359
 360        |docstring::notmuch-show-header-line|
 361
 362 .. el:defcustom:: notmuch-multipart/alternative-discouraged
 363
 364    Which mime types to hide by default for multipart messages.
 365
 366    Can either be a list of mime types (as strings) or a function
 367    mapping a plist representing the current message to such a list.
 368    The following example function would discourage `text/html` and
 369    `multipart/related` generally, but discourage `text/plain` should
 370    the message be sent from `whatever@example.com`.
 371
 372    .. code:: lisp
 373
 374       (defun my--determine-discouraged (msg)
 375         (let* ((headers (plist-get msg :headers))
 376                (from (or (plist-get headers :From) "")))
 377           (cond
 378            ((string-match "whatever@example.com" from)
 379             (list "text/plain"))
 380            (t
 381             (list "text/html" "multipart/related")))))
 382
 383 .. _show-large:
 384
 385 Dealing with large messages and threads
 386 ---------------------------------------
 387
 388 If you are finding :ref:`notmuch-show` is annoyingly slow displaying
 389 large messages, you can customize
 390 :el:defcustom:`notmuch-show-max-text-part-size`.  If you want to speed up the
 391 display of large threads (with or without large messages), there are
 392 several options.  First, you can display the same query in one of the
 393 other modes. :ref:`notmuch-unthreaded` is the most robust for
 394 extremely large queries, but :ref:`notmuch-tree` is also be faster
 395 than :ref:`notmuch-show` in general, since it only renders a single
 396 message a time. If you prefer to stay with the rendered thread
 397 ("conversation") view of :ref:`notmuch-show`, you can customize the
 398 variables :el:defcustom:`notmuch-show-depth-limit`,
 399 :el:defcustom:`notmuch-show-height-limit` and
 400 :el:defcustom:`notmuch-show-max-text-part-size` to limit the amount of
 401 rendering done initially. Note that these limits are implicitly
 402 *OR*-ed together, and combinations might have surprising effects.
 403
 404 .. el:defcustom:: notmuch-show-depth-limit
 405
 406        |docstring::notmuch-show-depth-limit|
 407
 408 .. el:defcustom:: notmuch-show-height-limit
 409
 410        |docstring::notmuch-show-height-limit|
 411
 412 .. el:defcustom:: notmuch-show-max-text-part-size
 413
 414        |docstring::notmuch-show-max-text-part-size|
 415
 416 .. _show-copy:
 417
 418 Copy to kill-ring
 419 -----------------
 420
 421 You can use the usually Emacs ways of copying text to the kill-ring,
 422 but notmuch also provides some shortcuts. These keys are available in
 423 :ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available
 424 in :ref:`notmuch-search`.
 425
 426 .. el:define-key:: c F
 427    M-x notmuch-show-stash-filename
 428
 429    |docstring::notmuch-show-stash-filename|
 430
 431 .. el:define-key:: c G
 432    M-x notmuch-show-stash-git-send-email
 433
 434    |docstring::notmuch-show-stash-git-send-email|
 435
 436 .. el:define-key:: c I
 437    M-x notmuch-show-stash-message-id-stripped
 438
 439    |docstring::notmuch-show-stash-message-id-stripped|
 440
 441 .. el:define-key:: c L
 442    M-x notmuch-show-stash-mlarchive-link-and-go
 443
 444    |docstring::notmuch-show-stash-mlarchive-link-and-go|
 445
 446 .. el:define-key:: c T
 447    M-x notmuch-show-stash-tags
 448
 449    |docstring::notmuch-show-stash-tags|
 450
 451 .. el:define-key:: c c
 452    M-x notmuch-show-stash-cc
 453
 454    |docstring::notmuch-show-stash-cc|
 455
 456 .. el:define-key:: c d
 457    M-x notmuch-show-stash-date
 458
 459    |docstring::notmuch-show-stash-date|
 460
 461 .. el:define-key:: c f
 462    M-x notmuch-show-stash-from
 463
 464    |docstring::notmuch-show-stash-from|
 465
 466 .. el:define-key:: c i
 467    M-x notmuch-show-stash-message-id
 468
 469    |docstring::notmuch-show-stash-message-id|
 470
 471 .. el:define-key:: c l
 472    M-x notmuch-show-stash-mlarchive-link
 473
 474    |docstring::notmuch-show-stash-mlarchive-link|
 475
 476 .. el:define-key:: c s
 477    M-x notmuch-show-stash-subject
 478
 479    |docstring::notmuch-show-stash-subject|
 480
 481 .. el:define-key:: c t
 482    M-x notmuch-show-stash-to
 483
 484    |docstring::notmuch-show-stash-to|
 485
 486 .. el:define-key:: c ?
 487    M-x notmuch-subkeymap-help
 488
 489    Show all available copying commands
 490
 491 .. _emacs-show-duplicates:
 492
 493 Dealing with duplicates
 494 -----------------------
 495
 496 If there are multiple files with the same :mailheader:`Message-ID`
 497 (see :any:`duplicate-files`), then :any:`notmuch-show` displays the
 498 number of duplicates and identifies the current duplicate. In the
 499 following example duplicate 3 of 5 is displayed.
 500
 501 .. code-block::
 502    :emphasize-lines: 1
 503
 504     M. Mustermann <max@example.com> (Sat, 30 Jul 2022 10:33:10 -0300) (inbox signed)      3/5
 505     Subject: Re: Multiple files per message in emacs
 506     To: notmuch@notmuchmail.org
 507
 508 .. el:define-key:: %
 509    M-x notmuch-show-choose-duplicate
 510
 511    |docstring::notmuch-show-choose-duplicate|
 512
 513 .. _notmuch-tree:
 514
 515 notmuch-tree
 516 ============
 517
 518 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
 519 email archives. Each line in the buffer represents a single
 520 message giving the relative date, the author, subject, and any
 521 tags.
 522
 523 .. el:define-key:: c
 524
 525     :ref:`show-copy`
 526
 527 .. el:define-key:: <return>
 528
 529    Displays that message.
 530
 531 .. el:define-key:: N
 532
 533     Move to next message
 534
 535 .. el:define-key:: P
 536
 537     Move to previous message
 538
 539 .. el:define-key:: n
 540
 541     Move to next matching message
 542
 543 .. el:define-key:: p
 544
 545     Move to previous matching message
 546
 547 .. el:define-key:: o
 548    M-x notmuch-tree-toggle-order
 549
 550    |docstring::notmuch-tree-toggle-order|
 551
 552 .. el:define-key:: l
 553    M-x notmuch-tree-filter
 554
 555    Filter or LIMIT the current search results based on an additional query string
 556
 557 .. el:define-key:: t
 558    M-x notmuch-tree-filter-by-tag
 559
 560    Filter the current search results based on an additional tag
 561
 562
 563 .. el:define-key:: g
 564    =
 565
 566     Refresh the buffer
 567
 568 .. el:define-key:: ?
 569
 570     Display full set of key bindings
 571
 572 As is the case with :ref:`notmuch-search`, the presentation of results
 573 can be controlled by the variable ``notmuch-search-oldest-first``.
 574
 575 .. el:defcustom:: notmuch-tree-result-format
 576
 577    |docstring::notmuch-tree-result-format|
 578
 579    The following example shows how to optionally display recipients instead
 580    of authors for sent mail (assuming the user is named Mustermann).
 581
 582    .. code:: lisp
 583
 584       (defun -notmuch-authors-or-to (format-string result)
 585         (let* ((headers (plist-get result :headers))
 586                (to (plist-get headers :To))
 587                (author (plist-get headers :From))
 588                (face (if (plist-get result :match)
 589                          'notmuch-tree-match-author-face
 590                        'notmuch-tree-no-match-author-face)))
 591           (propertize
 592            (format format-string
 593                    (if (string-match "Mustermann" author)
 594                        (concat "To:" (notmuch-tree-clean-address to))
 595                      author))
 596            'face face)))
 597
 598       (setq notmuch-tree-result-format
 599             '(("date" . "%12s  ")
 600               (-notmuch-authors-or-to . "%-20.20s")
 601               ((("tree" . "%s")
 602                 ("subject" . "%s"))
 603                . " %-54s ")
 604               ("tags" . "(%s)")))
 605
 606    See also :el:defcustom:`notmuch-search-result-format` and
 607    :el:defcustom:`notmuch-unthreaded-result-format`.
 608
 609 .. _notmuch-tree-outline:
 610
 611 notmuch-tree-outline
 612 --------------------
 613
 614 When this mode is set, each thread and subthread in the results
 615 list is treated as a foldable section, with its first message as
 616 its header.
 617
 618 The mode just makes available in the tree buffer all the
 619 keybindings in info:emacs#Outline_Mode, and binds the following
 620 additional keys:
 621
 622 .. el:define-key:: <tab>
 623
 624    Cycle visibility state of the current message's tree.
 625
 626 .. el:define-key:: <M-tab>
 627
 628    Cycle visibility state of all trees in the buffer.
 629
 630 The behaviour of this minor mode is affected by the following
 631 customizable variables:
 632
 633 .. el:defcustom:: notmuch-tree-outline-enabled
 634
 635    |docstring::notmuch-tree-outline-enabled|
 636
 637 .. el:defcustom:: notmuch-tree-outline-visibility
 638
 639    |docstring::notmuch-tree-outline-visibility|
 640
 641 .. el:defcustom:: notmuch-tree-outline-auto-close
 642
 643    |docstring::notmuch-tree-outline-auto-close|
 644
 645 .. el:defcustom:: notmuch-tree-outline-open-on-next
 646
 647    |docstring::notmuch-tree-outline-open-on-next|
 648
 649 .. _notmuch-unthreaded:
 650
 651 notmuch-unthreaded
 652 ------------------
 653
 654 ``notmuch-unthreaded-mode`` is similar to :any:`notmuch-tree` in that
 655 each line corresponds to a single message, but no thread information
 656 is presented.
 657
 658 Keybindings are the same as :any:`notmuch-tree`.
 659
 660 .. el:defcustom:: notmuch-unthreaded-result-format
 661
 662    |docstring::notmuch-unthreaded-result-format|
 663
 664    See also :el:defcustom:`notmuch-search-result-format` and
 665    :el:defcustom:`notmuch-tree-result-format`.
 666
 667 Global key bindings
 668 ===================
 669
 670 Several features are accessible from most places in notmuch through the
 671 following key bindings:
 672
 673 .. el:define-key:: j
 674
 675     Jump to saved searches using :ref:`notmuch-jump`.
 676
 677 .. el:define-key:: k
 678
 679     Tagging operations using :ref:`notmuch-tag-jump`
 680
 681 .. el:define-key:: C-_
 682    C-/
 683    C-x u
 684
 685    Undo previous tagging operation using :any:`notmuch-tag-undo`
 686
 687 .. _notmuch-jump:
 688
 689 notmuch-jump
 690 ------------
 691
 692 Saved searches configured through :ref:`saved-searches` can
 693 include a "shortcut key" that's accessible through notmuch-jump.
 694 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
 695 key of a saved search will immediately jump to that saved search.  For
 696 example, in the default configuration ``j i`` jumps immediately to the
 697 inbox search.  When you press ``j``, notmuch-jump shows the saved
 698 searches and their shortcut keys in the mini-buffer.
 699
 700 .. _notmuch-tag-jump:
 701
 702 notmuch-tag-jump
 703 ----------------
 704
 705 Tagging operations configured through ``notmuch-tagging-keys`` can
 706 be accessed via :kbd:`k` in :ref:`notmuch-show`,
 707 :ref:`notmuch-search` and :ref:`notmuch-tree`.  With a
 708 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
 709 operations specified in ``notmuch-tagging-keys``; i.e. each
 710 ``+tag`` is replaced by ``-tag`` and vice versa.
 711
 712 .. el:defcustom:: notmuch-tagging-keys
 713
 714   |docstring::notmuch-tagging-keys|
 715
 716
 717 notmuch-tag-undo
 718 ----------------
 719
 720 Each notmuch buffer supporting tagging operations (i.e. buffers in
 721 :any:`notmuch-show`, :any:`notmuch-search`, :any:`notmuch-tree`, and
 722 :any:`notmuch-unthreaded` mode) keeps a local stack of tagging
 723 operations. These can be undone via :any:`notmuch-tag-undo`. By default
 724 this is bound to the usual Emacs keys for undo.
 725
 726 .. el:define-key::  C-_
 727    C-/
 728    C-x u
 729    M-x notmuch-tag-undo
 730
 731    |docstring::notmuch-tag-undo|
 732
 733 Buffer navigation
 734 =================
 735
 736 .. el:define-key:: M-x notmuch-cycle-notmuch-buffers
 737
 738    |docstring::notmuch-cycle-notmuch-buffers|
 739
 740 Configuration
 741 =============
 742
 743 .. _importing:
 744
 745 Importing Mail
 746 --------------
 747
 748 .. el:define-key:: M-x notmuch-poll
 749
 750    |docstring::notmuch-poll|
 751
 752 .. el:defcustom:: notmuch-poll-script
 753
 754    |docstring::notmuch-poll-script|
 755
 756 Sending Mail
 757 ------------
 758
 759 .. el:defcustom:: mail-user-agent
 760
 761        Emacs consults the variable :code:`mail-user-agent` to choose a mail
 762        sending package for commands like :code:`report-emacs-bug` and
 763        :code:`compose-mail`.  To use ``notmuch`` for this, customize this
 764        variable to the symbol :code:`notmuch-user-agent`.
 765
 766 .. el:defcustom:: message-dont-reply-to-names
 767
 768        When composing mail replies, Emacs's message mode uses the
 769        variable :code:`message-dont-reply-to-names` to exclude
 770        recipients matching a given collection of regular expressions
 771        or satisfying an arbitrary predicate.  Notmuch's MUA inherits
 772        this standard mechanism and will honour your customization of
 773        this variable.
 774
 775 Init File
 776 ---------
 777
 778 When Notmuch is loaded, it will read the ``notmuch-init-file``
 779 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
 780 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
 781 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
 782 suffix exist it will be read instead (just one of these, chosen in this
 783 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
 784 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
 785 options, ``notmuch-init-file`` is not read.