10 **notmuch** **config** **get** <*section*>.<*item*>
12 **notmuch** **config** **set** [--database] <*section*>.<*item*> [*value* ...]
14 **notmuch** **config** **list**
19 The **config** command can be used to get or set settings in the notmuch
20 configuration file and corresponding database.
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.
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.
36 If no values are provided, the specified configuration item will
37 be removed from the configuration file.
39 With the `--database` option, updates configuration metadata
40 stored in the database, rather than the default (text)
45 Every configuration item is printed to stdout, each on a separate
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.
54 The available configuration items are described below. Non-absolute
55 paths are presumed relative to `$HOME` for items in section
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
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.
70 History: this configuration value was introduced in notmuch 0.33.
73 Directory to store tag dumps when upgrading database.
75 History: this configuration value was introduced in notmuch 0.32.
77 Default: A sibling directory of the Xapian database called
81 Directory containing hooks run by notmuch commands. See
82 :any:`notmuch-hooks(5)`.
84 History: this configuration value was introduced in notmuch 0.32.
86 Default: See HOOKS, below.
88 .. _database.mail_root:
91 The top-level directory where your mail currently exists and to
92 where mail will be delivered in the future. Files should be
93 individual email messages.
95 History: this configuration value was introduced in notmuch 0.32.
97 Default: For compatibility with older configurations, the value of
98 database.path is used if **database.mail\_root** is unset.
101 Notmuch will store its database here, (in
102 sub-directory named ``.notmuch`` if **database.mail\_root**
105 Default: see :ref:`database`
110 Policy for decrypting encrypted messages during indexing. Must be
111 one of: ``false``, ``auto``, ``nostash``, or ``true``.
113 When indexing an encrypted e-mail message, if this variable is set
114 to ``true``, notmuch will try to decrypt the message and index the
115 cleartext, stashing a copy of any discovered session keys for the
116 message. If ``auto``, it will try to index the cleartext if a
117 stashed session key is already known for the message (e.g. from a
118 previous copy), but will not try to access your secret keys. Use
119 ``false`` to avoid decrypting even when a stashed session key is
122 ``nostash`` is the same as ``true`` except that it will not stash
123 newly-discovered session keys in the database.
125 From the command line (i.e. during :any:`notmuch-new(1)`,
126 :any:`notmuch-insert(1)`, or :any:`notmuch-reindex(1)`), the user can
127 override the database's stored decryption policy with the
128 ``--decrypt=`` option.
130 Here is a table that summarizes the functionality of each of these
133 +------------------------+-------+------+---------+------+
134 | | false | auto | nostash | true |
135 +========================+=======+======+=========+======+
136 | Index cleartext using | | X | X | X |
137 | stashed session keys | | | | |
138 +------------------------+-------+------+---------+------+
139 | Index cleartext | | | X | X |
140 | using secret keys | | | | |
141 +------------------------+-------+------+---------+------+
142 | Stash session keys | | | | X |
143 +------------------------+-------+------+---------+------+
144 | Delete stashed session | X | | | |
145 | keys on reindex | | | | |
146 +------------------------+-------+------+---------+------+
148 Stashed session keys are kept in the database as properties
149 associated with the message. See ``session-key`` in
150 :any:`notmuch-properties(7)` for more details about how they can be
153 Be aware that the notmuch index is likely sufficient (and a
154 stashed session key is certainly sufficient) to reconstruct the
155 cleartext of the message itself, so please ensure that the notmuch
156 message index is adequately protected. DO NOT USE
157 ``index.decrypt=true`` or ``index.decrypt=nostash`` without
158 considering the security of your index.
164 index.header.<prefix>
165 Define the query prefix <prefix>, based on a mail header. For
166 example ``index.header.List=List-Id`` will add a probabilistic
167 prefix ``List:`` that searches the ``List-Id`` field. User
168 defined prefixes must not start with 'a'...'z'; in particular
169 adding a prefix with same name as a predefined prefix is not
170 supported. See :any:`notmuch-search-terms(7)` for a list of existing
171 prefixes, and an explanation of probabilistic prefixes.
173 .. _maildir.synchronize_flags:
175 maildir.synchronize\_flags
176 If true, then the following maildir flags (in message filenames)
177 will be synchronized with the corresponding notmuch tags:
179 +--------+-----------------------------------------------+
181 +========+===============================================+
183 +--------+-----------------------------------------------+
185 +--------+-----------------------------------------------+
187 +--------+-----------------------------------------------+
189 +--------+-----------------------------------------------+
190 | S | unread (added when 'S' flag is not present) |
191 +--------+-----------------------------------------------+
193 The :any:`notmuch-new(1)` command will notice flag changes in
194 filenames and update tags, while the :any:`notmuch-tag(1)` and
195 :any:`notmuch-restore(1)` commands will notice tag changes and
196 update flags in filenames.
198 If there have been any changes in the maildir (new messages added,
199 old ones removed or renamed, maildir flags changed, etc.), it is
200 advisable to run :any:`notmuch-new(1)` before
201 :any:`notmuch-tag(1)` or :any:`notmuch-restore(1)` commands to
202 ensure the tag changes are properly synchronized to the maildir
203 flags, as the commands expect the database and maildir to be in
211 A list to specify files and directories that will not be searched
212 for messages by :any:`notmuch-new(1)`. Each entry in the list is either:
214 A file or a directory name, without path, that will be ignored,
215 regardless of the location in the mail store directory hierarchy.
219 A regular expression delimited with // that will be matched
220 against the path of the file or directory relative to the database
221 path. Matching files and directories will be ignored. The
222 beginning and end of string must be explicitly anchored. For
223 example, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but
224 not "foo" or "bar/foobar".
231 A list of tags that will be added to all messages incorporated by
234 Default: ``unread;inbox``.
237 Expansion for named query called <name>. See
238 :any:`notmuch-search-terms(7)` for more information about named
242 A list of tags that will be excluded from search results by
243 default. Using an excluded tag in a query will override that
246 Default: empty list. Note that :any:`notmuch-setup(1)` puts
247 ``deleted;spam`` here when creating new configuration file.
249 .. _show.extra_headers:
253 By default :any:`notmuch-show(1)` includes the following headers
254 in structured output if they are present in the message:
255 `Subject`, `From`, `To`, `Cc`, `Bcc`, `Reply-To`, `Date`. This
256 option allows the specification of a list of further
259 History: This configuration value was introduced in notmuch 0.35.
264 Expansion for named query called <name>, using s-expression syntax. See
265 :any:`notmuch-sexp-queries(7)` for more information about s-expression
271 Default: ``$NAME`` variable if set, otherwise read from
275 A list of other email addresses at which you receive email
276 (see also, :ref:`user.primary_email <user.primary_email>`).
280 .. _user.primary_email:
283 Your primary email address.
285 Default: ``$EMAIL`` variable if set, otherwise constructed from
286 the username and hostname of the current machine.
296 Notmuch configuration file search order:
298 1. File specified by :option:`notmuch --config` global option; see
301 2. File specified by :envvar:`NOTMUCH_CONFIG` environment variable.
303 3. ``$XDG_CONFIG_HOME/notmuch/<profile>/config`` where ``<profile>``
304 is defined by :envvar:`NOTMUCH_PROFILE` environment variable if
305 set, ``$XDG_CONFIG_HOME/notmuch/default/config`` otherwise.
307 4. ``$HOME/.notmuch-config.<profile>`` where ``<profile>`` is defined
308 by :envvar:`NOTMUCH_PROFILE` environment variable if set,
309 ``$HOME/.notmuch-config`` otherwise.
316 Notmuch database search order:
318 1. Directory specified by :envvar:`NOTMUCH_DATABASE` environment variable.
320 2. Directory specified by config key ``database.path``.
322 3. ``$XDG_DATA_HOME/notmuch/<profile>`` where ``<profile>``
323 is defined by :envvar:`NOTMUCH_PROFILE` environment variable if
324 set, ``$XDG_DATA_HOME/notmuch/default`` otherwise.
326 4. Directory specified by :envvar:`MAILDIR` environment variable.
333 Notmuch hook directory search order:
335 1. Directory specified by ``database.hook_dir`` configuration option.
337 2. ``$XDG_CONFIG_HOME/notmuch/<profile>/hooks`` where ``<profile>``
338 is defined by :envvar:`NOTMUCH_PROFILE` environment variable if
339 set, ``$XDG_CONFIG_HOME/notmuch/default/hooks`` otherwise.
341 3. ``<database.path>/.notmuch/hooks``
347 :any:`notmuch-count(1)`,
348 :any:`notmuch-dump(1)`,
349 :any:`notmuch-hooks(5)`,
350 :any:`notmuch-insert(1)`,
351 :any:`notmuch-new(1)`,
352 :any:`notmuch-properties(7)`,
353 :any:`notmuch-reply(1)`,
354 :any:`notmuch-restore(1)`,
355 :any:`notmuch-search(1)`,
356 :any:`notmuch-search-terms(7)`,
357 :any:`notmuch-show(1)`,
358 :any:`notmuch-tag(1)`