git.cworth.org Git - notmuch/blob - doc/man1/notmuch-config.rst

   1 .. _notmuch-config(1):
   2
   3 ==============
   4 notmuch-config
   5 ==============
   6
   7 SYNOPSIS
   8 ========
   9
  10 **notmuch** **config** **get** <*section*>.<*item*>
  11
  12 **notmuch** **config** **set** [--database] <*section*>.<*item*> [*value* ...]
  13
  14 **notmuch** **config** **list**
  15
  16 DESCRIPTION
  17 ===========
  18
  19 The **config** command can be used to get or set settings in the notmuch
  20 configuration file and corresponding database.
  21
  22 .. program:: config
  23
  24 .. option:: get
  25
  26    The value of the specified configuration item is printed to
  27    stdout. If the item has multiple values (it is a list), each value
  28    is separated by a newline character.
  29
  30 .. option:: set
  31
  32    The specified configuration item is set to the given value. To
  33    specify a multiple-value item (a list), provide each value as a
  34    separate command-line argument.
  35
  36    If no values are provided, the specified configuration item will
  37    be removed from the configuration file.
  38
  39    With the `--database` option, updates configuration metadata
  40    stored in the database, rather than the default (text)
  41    configuration file.
  42
  43 .. option:: list
  44
  45    Every configuration item is printed to stdout, each on a separate
  46    line of the form::
  47
  48      section.item=value
  49
  50    No additional whitespace surrounds the dot or equals sign
  51    characters. In a multiple-value item (a list), the values are
  52    separated by semicolon characters.
  53
  54 The available configuration items are described below. Non-absolute
  55 paths are presumed relative to `$HOME` for items in section
  56 **database**.
  57
  58 built_with.<name>
  59     Compile time feature <name>. Current possibilities include
  60     "retry_lock" (configure option, included by default).
  61     (since notmuch 0.30, "compact" and "field_processor" are
  62     always included.)
  63
  64 database.autocommit
  65
  66     How often to commit transactions to disk. `0` means wait until
  67     command completes, otherwise an integer `n` specifies to commit to
  68     disk after every `n` completed transactions.
  69
  70     History: this configuration value was introduced in notmuch 0.33.
  71
  72 database.backup_dir
  73     Directory to store tag dumps when upgrading database.
  74
  75     History: this configuration value was introduced in notmuch 0.32.
  76
  77     Default: A sibling directory of the Xapian database called
  78     `backups`.
  79
  80 database.hook_dir
  81     Directory containing hooks run by notmuch commands. See
  82     :any:`notmuch-hooks(5)`.
  83
  84     History: this configuration value was introduced in notmuch 0.32.
  85
  86     Default: See HOOKS, below.
  87
  88 database.mail_root
  89     The top-level directory where your mail currently exists and to
  90     where mail will be delivered in the future. Files should be
  91     individual email messages.
  92
  93     History: this configuration value was introduced in notmuch 0.32.
  94
  95     Default: For compatibility with older configurations, the value of
  96     database.path is used if **database.mail\_root** is unset.
  97
  98 database.path
  99     Notmuch will store its database here, (in
 100     sub-directory named ``.notmuch`` if **database.mail\_root**
 101     is unset).
 102
 103     Default: see :ref:`database`
 104
 105 .. _index.decrypt:
 106
 107 index.decrypt
 108     Policy for decrypting encrypted messages during indexing.  Must be
 109     one of: ``false``, ``auto``, ``nostash``, or ``true``.
 110
 111     When indexing an encrypted e-mail message, if this variable is set
 112     to ``true``, notmuch will try to decrypt the message and index the
 113     cleartext, stashing a copy of any discovered session keys for the
 114     message.  If ``auto``, it will try to index the cleartext if a
 115     stashed session key is already known for the message (e.g. from a
 116     previous copy), but will not try to access your secret keys.  Use
 117     ``false`` to avoid decrypting even when a stashed session key is
 118     already present.
 119
 120     ``nostash`` is the same as ``true`` except that it will not stash
 121     newly-discovered session keys in the database.
 122
 123     From the command line (i.e. during :any:`notmuch-new(1)`,
 124     :any:`notmuch-insert(1)`, or :any:`notmuch-reindex(1)`), the user can
 125     override the database's stored decryption policy with the
 126     ``--decrypt=`` option.
 127
 128     Here is a table that summarizes the functionality of each of these
 129     policies:
 130
 131     +------------------------+-------+------+---------+------+
 132     |                        | false | auto | nostash | true |
 133     +========================+=======+======+=========+======+
 134     | Index cleartext using  |       |  X   |    X    |  X   |
 135     | stashed session keys   |       |      |         |      |
 136     +------------------------+-------+------+---------+------+
 137     | Index cleartext        |       |      |    X    |  X   |
 138     | using secret keys      |       |      |         |      |
 139     +------------------------+-------+------+---------+------+
 140     | Stash session keys     |       |      |         |  X   |
 141     +------------------------+-------+------+---------+------+
 142     | Delete stashed session |   X   |      |         |      |
 143     | keys on reindex        |       |      |         |      |
 144     +------------------------+-------+------+---------+------+
 145
 146     Stashed session keys are kept in the database as properties
 147     associated with the message.  See ``session-key`` in
 148     :any:`notmuch-properties(7)` for more details about how they can be
 149     useful.
 150
 151     Be aware that the notmuch index is likely sufficient (and a
 152     stashed session key is certainly sufficient) to reconstruct the
 153     cleartext of the message itself, so please ensure that the notmuch
 154     message index is adequately protected.  DO NOT USE
 155     ``index.decrypt=true`` or ``index.decrypt=nostash`` without
 156     considering the security of your index.
 157
 158     Default: ``auto``.
 159
 160 .. _index.header:
 161
 162 index.header.<prefix>
 163     Define the query prefix <prefix>, based on a mail header. For
 164     example ``index.header.List=List-Id`` will add a probabilistic
 165     prefix ``List:`` that searches the ``List-Id`` field.  User
 166     defined prefixes must not start with 'a'...'z'; in particular
 167     adding a prefix with same name as a predefined prefix is not
 168     supported. See :any:`notmuch-search-terms(7)` for a list of existing
 169     prefixes, and an explanation of probabilistic prefixes.
 170
 171 .. _maildir.synchronize_flags:
 172
 173 maildir.synchronize\_flags
 174     If true, then the following maildir flags (in message filenames)
 175     will be synchronized with the corresponding notmuch tags:
 176
 177     +--------+-----------------------------------------------+
 178     | Flag   | Tag                                           |
 179     +========+===============================================+
 180     | D      | draft                                         |
 181     +--------+-----------------------------------------------+
 182     | F      | flagged                                       |
 183     +--------+-----------------------------------------------+
 184     | P      | passed                                        |
 185     +--------+-----------------------------------------------+
 186     | R      | replied                                       |
 187     +--------+-----------------------------------------------+
 188     | S      | unread (added when 'S' flag is not present)   |
 189     +--------+-----------------------------------------------+
 190
 191     The :any:`notmuch-new(1)` command will notice flag changes in
 192     filenames and update tags, while the :any:`notmuch-tag(1)` and
 193     :any:`notmuch-restore(1)` commands will notice tag changes and
 194     update flags in filenames.
 195
 196     If there have been any changes in the maildir (new messages added,
 197     old ones removed or renamed, maildir flags changed, etc.), it is
 198     advisable to run :any:`notmuch-new(1)` before
 199     :any:`notmuch-tag(1)` or :any:`notmuch-restore(1)` commands to
 200     ensure the tag changes are properly synchronized to the maildir
 201     flags, as the commands expect the database and maildir to be in
 202     sync.
 203
 204     Default: ``true``.
 205
 206 .. _new.ignore:
 207
 208 new.ignore
 209     A list to specify files and directories that will not be searched
 210     for messages by :any:`notmuch-new(1)`. Each entry in the list is either:
 211
 212     A file or a directory name, without path, that will be ignored,
 213     regardless of the location in the mail store directory hierarchy.
 214
 215     Or:
 216
 217     A regular expression delimited with // that will be matched
 218     against the path of the file or directory relative to the database
 219     path. Matching files and directories will be ignored. The
 220     beginning and end of string must be explicitly anchored. For
 221     example, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but
 222     not "foo" or "bar/foobar".
 223
 224     Default: empty list.
 225
 226 .. _new.tags:
 227
 228 new.tags
 229     A list of tags that will be added to all messages incorporated by
 230     **notmuch new**.
 231
 232     Default: ``unread;inbox``.
 233
 234 query.<name>
 235     Expansion for named query called <name>. See
 236     :any:`notmuch-search-terms(7)` for more information about named
 237     queries.
 238
 239 search.exclude\_tags
 240     A list of tags that will be excluded from search results by
 241     default. Using an excluded tag in a query will override that
 242     exclusion.
 243
 244     Default: empty list. Note that :any:`notmuch-setup(1)` puts
 245     ``deleted;spam`` here when creating new configuration file.
 246
 247 .. _show.extra_headers:
 248
 249 show.extra\_headers
 250
 251     By default :any:`notmuch-show(1)` includes the following headers
 252     in structured output if they are present in the message:
 253     `Subject`, `From`, `To`, `Cc`, `Bcc`, `Reply-To`, `Date`. This
 254     option allows the specification of a list of further
 255     headers to output.
 256
 257     History: This configuration value was introduced in notmuch 0.35.
 258
 259     Default: empty list.
 260
 261 squery.<name>
 262     Expansion for named query called <name>, using s-expression syntax. See
 263     :any:`notmuch-sexp-queries(7)` for more information about s-expression
 264     queries.
 265
 266 user.name
 267     Your full name.
 268
 269     Default: ``$NAME`` variable if set, otherwise read from
 270     ``/etc/passwd``.
 271
 272 user.other\_email
 273     A list of other email addresses at which you receive email
 274     (see also, :ref:`user.primary_email <user.primary_email>`).
 275
 276     Default: not set.
 277
 278 .. _user.primary_email:
 279
 280 user.primary\_email
 281     Your primary email address.
 282
 283     Default: ``$EMAIL`` variable if set, otherwise constructed from
 284     the username and hostname of the current machine.
 285
 286 FILES
 287 =====
 288
 289 .. _config_search:
 290
 291 CONFIGURATION
 292 -------------
 293
 294 Notmuch configuration file search order:
 295
 296 1. File specified by :option:`notmuch --config` global option; see
 297    :any:`notmuch(1)`.
 298
 299 2. File specified by :envvar:`NOTMUCH_CONFIG` environment variable.
 300
 301 3. ``$XDG_CONFIG_HOME/notmuch/<profile>/config`` where ``<profile>``
 302    is defined by :envvar:`NOTMUCH_PROFILE` environment variable if
 303    set, ``$XDG_CONFIG_HOME/notmuch/default/config`` otherwise.
 304
 305 4. ``$HOME/.notmuch-config.<profile>`` where ``<profile>`` is defined
 306    by :envvar:`NOTMUCH_PROFILE` environment variable if set,
 307    ``$HOME/.notmuch-config`` otherwise.
 308
 309 .. _database:
 310
 311 DATABASE LOCATION
 312 -----------------
 313
 314 Notmuch database search order:
 315
 316 1. Directory specified by :envvar:`NOTMUCH_DATABASE` environment variable.
 317
 318 2. Directory specified by config key ``database.path``.
 319
 320 3. ``$XDG_DATA_HOME/notmuch/<profile>`` where ``<profile>``
 321    is defined by :envvar:`NOTMUCH_PROFILE` environment variable if
 322    set, ``$XDG_DATA_HOME/notmuch/default`` otherwise.
 323
 324 4. Directory specified by :envvar:`MAILDIR` environment variable.
 325
 326 5. ``$HOME/mail``
 327
 328 HOOKS
 329 -----
 330
 331 Notmuch hook directory search order:
 332
 333 1. Directory specified by ``database.hook_dir`` configuration option.
 334
 335 2. ``$XDG_CONFIG_HOME/notmuch/<profile>/hooks`` where ``<profile>``
 336    is defined by :envvar:`NOTMUCH_PROFILE` environment variable if
 337    set, ``$XDG_CONFIG_HOME/notmuch/default/hooks`` otherwise.
 338
 339 3. ``<database.path>/.notmuch/hooks``
 340
 341 SEE ALSO
 342 ========
 343
 344 :any:`notmuch(1)`,
 345 :any:`notmuch-count(1)`,
 346 :any:`notmuch-dump(1)`,
 347 :any:`notmuch-hooks(5)`,
 348 :any:`notmuch-insert(1)`,
 349 :any:`notmuch-new(1)`,
 350 :any:`notmuch-properties(7)`,
 351 :any:`notmuch-reply(1)`,
 352 :any:`notmuch-restore(1)`,
 353 :any:`notmuch-search(1)`,
 354 :any:`notmuch-search-terms(7)`,
 355 :any:`notmuch-show(1)`,
 356 :any:`notmuch-tag(1)`