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 |        Type a search query and hit RET to view matching threads.
  46 |               Edit saved searches with the ``edit`` button.
  47 | Hit RET or click on a saved search or tag name to view matching threads.
  48 |     ``=`` to refresh this screen. ``s`` to search messages. ``q`` to quit.
  49 |                   **Customize** this page.
  50
  51 You can change the overall appearance of the notmuch-hello screen by
  52 customizing the variable :index:`notmuch-hello-sections`.
  53
  54
  55
  56 notmuch-hello key bindings
  57 --------------------------
  58
  59 ``<tab>``
  60     Move to the next widget (button or text entry field)
  61
  62 ``<backspace>``
  63     Move to the previous widget.
  64
  65 ``<return>``
  66     Activate the current widget.
  67
  68 ``=``
  69     Refresh the buffer; mainly update the counts of messages for various
  70     saved searches.
  71
  72 ``G``
  73     Import mail, See :ref:`importing`
  74
  75 ``m``
  76     Compose a message
  77
  78 ``s``
  79     Search the notmuch database using :ref:`notmuch-search`
  80
  81 ``v``
  82     Print notmuch version
  83
  84 ``q``
  85     Quit
  86
  87 .. _saved-searches:
  88
  89 Saved Searches
  90 --------------
  91
  92 Since notmuch is entirely search-based, it's often useful to organize
  93 mail around common searches.  To facilitate this, the first section of
  94 notmuch-hello presents a customizable set of saved searches.  Saved
  95 searches can also be accessed from anywhere in notmuch by pressing
  96 ``j`` to access :ref:`notmuch-jump`.
  97
  98 The saved searches default to various common searches such as
  99 ``tag:inbox`` to access the inbox and ``tag:unread`` to access all
 100 unread mail, but there are several options for customization:
 101
 102 :index:`notmuch-saved-searches`
 103     The list of saved searches, including names, queries, and
 104     additional per-query options.
 105
 106 :index:`notmuch-saved-searches-sort-function`
 107     This variable controls how saved searches should be sorted. A value
 108     of ``nil`` displays the saved searches in the order they are stored
 109     in ‘notmuch-saved-searches’.
 110
 111 :index:`notmuch-column-control`
 112     Controls the number of columns for displaying saved-searches/tags
 113
 114 Search Box
 115 ----------
 116
 117 The search box lets the user enter a Notmuch query. See section
 118 “Description” in Notmuch Query Syntax, for more info on Notmuch query
 119 syntax. A history of recent searches is also displayed by default. The
 120 latter is controlled by the variable :index:`notmuch-hello-recent-searches-max`.
 121
 122 Known Tags
 123 ----------
 124
 125 One special kind of saved search provided by default is for each
 126 individual tag defined in the database. This can be controlled via the
 127 following variables.
 128
 129 :index:`notmuch-hello-tag-list-make-query`
 130     Control how to construct a search (“virtual folder”) from a given
 131     tag.
 132
 133 :index:`notmuch-hello-hide-tags`
 134     Which tags not to display at all.
 135
 136 :index:`notmuch-column-control`
 137     Controls the number of columns for displaying saved-searches/tags
 138
 139 .. _notmuch-search:
 140
 141 notmuch-search
 142 ==============
 143
 144 ``notmuch-search-mode`` is used to display the results from executing
 145 a query via ``notmuch-search``. The syntax for these queries is the
 146 the same as :ref:`saved-searches`. For details of this syntax see
 147 info:notmuch-search-terms
 148
 149 By default the output approximates that of the command line See section
 150 “Description” in notmuch search command.
 151
 152 The main purpose of the ``notmuch-search-mode`` buffer is to act as a
 153 menu of results that the user can explore further by pressing
 154 ``<return>`` on the appropriate line.
 155
 156 ``n,C-n,<down>``
 157     Move to next line
 158
 159 ``p,C-p,<up>``
 160     Move to previous line
 161
 162 ``<return>``
 163     Open thread on current line in :ref:`notmuch-show` mode
 164
 165 ``?``
 166     Display full set of key bindings
 167
 168 The presentation of results can be controlled by the following
 169 variables.
 170
 171 :index:`notmuch-search-result-format`
 172     Control how each thread of messages is presented in the
 173     ``notmuch-show-mode`` buffer
 174
 175 :index:`notmuch-search-oldest-first`
 176     Display the oldest threads at the top of the buffer
 177
 178 .. _notmuch-show:
 179
 180 notmuch-show
 181 ============
 182
 183 notmuch-tree
 184 ============
 185
 186 Global key bindings
 187 ===================
 188
 189 Several features are accessible from anywhere in notmuch through the
 190 following key bindings:
 191
 192 ``j``
 193     Jump to saved searches using :ref:`notmuch-jump`.
 194
 195 notmuch-jump
 196 ------------
 197
 198 Saved searches configured through :ref:`notmuch-saved-searches` can
 199 include a "shortcut key" that's accessible through notmuch-jump.
 200 Pressing ``j`` anywhere in notmuch followed by the configured shortcut
 201 key of a saved search will immediately jump to that saved search.  For
 202 example, in the default configuration ``j i`` jumps immediately to the
 203 inbox search.  When you press ``j``, notmuch-jump shows the saved
 204 searches and their shortcut keys in the mini-buffer.
 205
 206 Configuration
 207 =============
 208
 209 .. _importing:
 210
 211 Importing Mail
 212 --------------
 213
 214 :index:`notmuch-poll`
 215
 216 :index:`notmuch-poll-script`
 217
 218 Init File
 219 ---------
 220
 221 When Notmuch is loaded, it will read the ``notmuch-init-file``
 222 (``~/.emacs.d/notmuch-config`` by default) file. This is normal Emacs Lisp
 223 file and can be used to avoid cluttering your ``~/.emacs`` with Notmuch
 224 stuff. If the file with ``.elc``, ``.elc.gz``, ``.el`` or ``.el.gz``
 225 suffix exist it will be read instead (just one of these, chosen in this
 226 order). Most often users create ``~/.emacs.d/notmuch-config.el`` and just
 227 work with it. If Emacs was invoked with the ``-q`` or ``--no-init-file``
 228 options, ``notmuch-init-file`` is not read.