git.notmuchmail.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 variable :index:`notmuch-hello-sections`.
  50
  51
  52
  53 notmuch-hello key bindings
  54 --------------------------
  55
  56 ``<tab>``
  57     Move to the next widget (button or text entry field)
  58
  59 ``<backspace>``
  60     Move to the previous widget.
  61
  62 ``<return>``
  63     Activate the current widget.
  64
  65 ``g``
  66 ``=``
  67     Refresh the buffer; mainly update the counts of messages for various
  68     saved searches.
  69
  70 ``G``
  71     Import mail, See :ref:`importing`
  72
  73 ``m``
  74     Compose a message
  75
  76 ``s``
  77     Search the notmuch database using :ref:`notmuch-search`
  78
  79 ``v``
  80     Print notmuch version
  81
  82 ``q``
  83     Quit
  84
  85 .. _saved-searches:
  86
  87 Saved Searches
  88 --------------
  89
  90 Since notmuch is entirely search-based, it's often useful to organize
  91 mail around common searches.  To facilitate this, the first section of
  92 notmuch-hello presents a customizable set of saved searches.  Saved
  93 searches can also be accessed from anywhere in notmuch by pressing
  94 ``j`` to access :ref:`notmuch-jump`.
  95
  96 The saved searches default to various common searches such as
  97 ``tag:inbox`` to access the inbox and ``tag:unread`` to access all
  98 unread mail, but there are several options for customization:
  99
 100 :index:`notmuch-saved-searches`
 101     The list of saved searches, including names, queries, and
 102     additional per-query options.
 103
 104 :index:`notmuch-saved-searches-sort-function`
 105     This variable controls how saved searches should be sorted. A value
 106     of ``nil`` displays the saved searches in the order they are stored
 107     in ‘notmuch-saved-searches’.
 108
 109 :index:`notmuch-column-control`
 110     Controls the number of columns for displaying saved-searches/tags
 111
 112 Search Box
 113 ----------
 114
 115 The search box lets the user enter a Notmuch query. See section
 116 “Description” in Notmuch Query Syntax, for more info on Notmuch query
 117 syntax. A history of recent searches is also displayed by default. The
 118 latter is controlled by the variable :index:`notmuch-hello-recent-searches-max`.
 119
 120 Known Tags
 121 ----------
 122
 123 One special kind of saved search provided by default is for each
 124 individual tag defined in the database. This can be controlled via the
 125 following variables.
 126
 127 :index:`notmuch-hello-tag-list-make-query`
 128     Control how to construct a search (“virtual folder”) from a given
 129     tag.
 130
 131 :index:`notmuch-hello-hide-tags`
 132     Which tags not to display at all.
 133
 134 :index:`notmuch-column-control`
 135     Controls the number of columns for displaying saved-searches/tags
 136
 137 .. _notmuch-search:
 138
 139 notmuch-search
 140 ==============
 141
 142 ``notmuch-search-mode`` is used to display the results from executing
 143 a query via ``notmuch-search``. The syntax for these queries is the
 144 the same as :ref:`saved-searches`. For details of this syntax see
 145 info:notmuch-search-terms
 146
 147 By default the output approximates that of the command line See section
 148 “Description” in notmuch search command.
 149
 150 The main purpose of the ``notmuch-search-mode`` buffer is to act as a
 151 menu of results that the user can explore further by pressing
 152 ``<return>`` on the appropriate line.
 153
 154 ``n,C-n,<down>``
 155     Move to next line
 156
 157 ``p,C-p,<up>``
 158     Move to previous line
 159
 160 ``<return>``
 161     Open thread on current line in :ref:`notmuch-show` mode
 162
 163 ``g``
 164 ``=``
 165     Refresh the buffer
 166
 167 ``?``
 168     Display full set of key bindings
 169
 170 The presentation of results can be controlled by the following
 171 variables.
 172
 173 :index:`notmuch-search-result-format`
 174     Control how each thread of messages is presented in the
 175     ``notmuch-show-mode`` buffer
 176
 177 :index:`notmuch-search-oldest-first`
 178     Display the oldest threads at the top of the buffer
 179
 180 .. _notmuch-show:
 181
 182 notmuch-show
 183 ============
 184
 185 ``notmuch-show-mode`` is used to display a single thread of email from
 186 your email archives.
 187
 188 By default, various components of email messages, (citations,
 189 signatures, already-read messages), are hidden. You can make
 190 these parts visible by clicking with the mouse button or by
 191 pressing RET after positioning the cursor on a hidden part.
 192
 193 ``<space>``
 194     Scroll the current message (if necessary),
 195     advance to the next message, or advance to the next thread (if
 196     already on the last message of a thread).
 197
 198 ``c``
 199     :ref:`show-copy`
 200
 201 ``N``
 202     Move to next message
 203
 204 ``P``
 205     Move to previous message (or start of current message)
 206
 207 ``n``
 208     Move to next matching message
 209
 210 ``p``
 211     Move to previous matching message
 212
 213 ``+,-``
 214     Add or remove arbitrary tags from the current message.
 215
 216 ``?``
 217     Display full set of key bindings
 218
 219 Display of messages can be controlled by the following variables
 220
 221 :index:`notmuch-message-headers`
 222        |docstring::notmuch-message-headers|
 223
 224 :index:`notmuch-message-headers-visible`
 225        |docstring::notmuch-message-headers-visible|
 226
 227 .. _show-copy:
 228
 229 Copy to kill-ring
 230 -----------------
 231
 232 You can use the usually Emacs ways of copying text to the kill-ring,
 233 but notmuch also provides some shortcuts. These keys are available in
 234 :ref:`notmuch-show`, and :ref:`notmuch-tree`. A subset are available
 235 in :ref:`notmuch-search`.
 236
 237 ``c F`` ``notmuch-show-stash-filename``
 238    |docstring::notmuch-show-stash-filename|
 239
 240 ``c G`` ``notmuch-show-stash-git-send-email``
 241    |docstring::notmuch-show-stash-git-send-email|
 242
 243 ``c I`` ``notmuch-show-stash-message-id-stripped``
 244    |docstring::notmuch-show-stash-message-id-stripped|
 245
 246 ``c L`` ``notmuch-show-stash-mlarchive-link-and-go``
 247    |docstring::notmuch-show-stash-mlarchive-link-and-go|
 248
 249 ``c T`` ``notmuch-show-stash-tags``
 250    |docstring::notmuch-show-stash-tags|
 251
 252 ``c c`` ``notmuch-show-stash-cc``
 253    |docstring::notmuch-show-stash-cc|
 254
 255 ``c d`` ``notmuch-show-stash-date``
 256    |docstring::notmuch-show-stash-date|
 257
 258 ``c f`` ``notmuch-show-stash-from``
 259    |docstring::notmuch-show-stash-from|
 260
 261 ``c i`` ``notmuch-show-stash-message-id``
 262    |docstring::notmuch-show-stash-message-id|
 263
 264 ``c l`` ``notmuch-show-stash-mlarchive-link``
 265    |docstring::notmuch-show-stash-mlarchive-link|
 266
 267 ``c s`` ``notmuch-show-stash-subject``
 268    |docstring::notmuch-show-stash-subject|
 269
 270 ``c t`` ``notmuch-show-stash-to``
 271    |docstring::notmuch-show-stash-to|
 272
 273 ``c ?``
 274     Show all available copying commands
 275
 276 .. _notmuch-tree:
 277
 278 notmuch-tree
 279 ============
 280
 281 ``notmuch-tree-mode`` displays the results of a "notmuch tree" of your
 282 email archives. Each line in the buffer represents a single
 283 message giving the relative date, the author, subject, and any
 284 tags.
 285
 286 ``c``
 287     :ref:`show-copy`
 288
 289 ``<return>``
 290    Displays that message.
 291
 292 ``N``
 293     Move to next message
 294
 295 ``P``
 296     Move to previous message
 297
 298 ``n``
 299     Move to next matching message
 300
 301 ``p``
 302     Move to previous matching message
 303
 304 ``g``
 305 ``=``
 306     Refresh the buffer
 307
 308 ``?``
 309     Display full set of key bindings
 310
 311 Global key bindings
 312 ===================
 313
 314 Several features are accessible from anywhere in notmuch through the
 315 following key bindings:
 316
 317 ``j``
 318     Jump to saved searches using :ref:`notmuch-jump`.
 319
 320 ``k``
 321     Tagging operations using :ref:`notmuch-tag-jump`
 322
 323 .. _notmuch-jump:
 324
 325 notmuch-jump
 326 ------------
 327
 328 Saved searches configured through :ref:`saved-searches` can
 329 include a "shortcut key" that's accessible through notmuch-jump.
 330 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
 331 key of a saved search will immediately jump to that saved search.  For
 332 example, in the default configuration ``j i`` jumps immediately to the
 333 inbox search.  When you press ``j``, notmuch-jump shows the saved
 334 searches and their shortcut keys in the mini-buffer.
 335
 336 .. _notmuch-tag-jump:
 337
 338 notmuch-tag-jump
 339 ----------------
 340
 341 Tagging operations configured through ``notmuch-tagging-keys`` can
 342 be accessed via :kbd:`k` in :ref:`notmuch-show`,
 343 :ref:`notmuch-search` and :ref:`notmuch-tree`.  With a
 344 prefix (:kbd:`C-u k`), notmuch displays a menu of the reverses of the
 345 operations specified in ``notmuch-tagging-keys``; i.e. each
 346 ``+tag`` is replaced by ``-tag`` and vice versa.
 347
 348 :index:`notmuch-tagging-keys`
 349
 350   |docstring::notmuch-tagging-keys|
 351
 352 Buffer navigation
 353 =================
 354
 355 :index:`notmuch-cycle-notmuch-buffers`
 356    |docstring::notmuch-cycle-notmuch-buffers|
 357
 358 Configuration
 359 =============
 360
 361 .. _importing:
 362
 363 Importing Mail
 364 --------------
 365
 366 :index:`notmuch-poll`
 367    |docstring::notmuch-poll|
 368
 369 :index:`notmuch-poll-script`
 370    |docstring::notmuch-poll-script|
 371
 372 Init File
 373 ---------
 374
 375 When Notmuch is loaded, it will read the ``notmuch-init-file``
 376 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
 377 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
 378 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
 379 suffix exist it will be read instead (just one of these, chosen in this
 380 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
 381 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
 382 options, ``notmuch-init-file`` is not read.
 383
 384 .. include:: ../emacs/rstdoc.rsti
 385
 386 .. include:: ../emacs/notmuch.rsti
 387
 388 .. include:: ../emacs/notmuch-lib.rsti
 389
 390 .. include:: ../emacs/notmuch-show.rsti
 391
 392 .. include:: ../emacs/notmuch-tag.rsti