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