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.
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.
93 History: this configuration value was introduced in notmuch 0.32.
95 Default: For compatibility with older configurations, the value of
96 database.path is used if **database.mail\_root** is unset.
99 Notmuch will store its database here, (in
100 sub-directory named ``.notmuch`` if **database.mail\_root**
103 Default: see :ref:`database`
108 Policy for decrypting encrypted messages during indexing. Must be
109 one of: ``false``, ``auto``, ``nostash``, or ``true``.
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
120 ``nostash`` is the same as ``true`` except that it will not stash
121 newly-discovered session keys in the database.
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.
128 Here is a table that summarizes the functionality of each of these
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 +------------------------+-------+------+---------+------+
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
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.
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.
171 .. _maildir.synchronize_flags:
173 maildir.synchronize\_flags
174 If true, then the following maildir flags (in message filenames)
175 will be synchronized with the corresponding notmuch tags:
177 +--------+-----------------------------------------------+
179 +========+===============================================+
181 +--------+-----------------------------------------------+
183 +--------+-----------------------------------------------+
185 +--------+-----------------------------------------------+
187 +--------+-----------------------------------------------+
188 | S | unread (added when 'S' flag is not present) |
189 +--------+-----------------------------------------------+
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.
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
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:
212 A file or a directory name, without path, that will be ignored,
213 regardless of the location in the mail store directory hierarchy.
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".
229 A list of tags that will be added to all messages incorporated by
232 Default: ``unread;inbox``.
235 Expansion for named query called <name>. See
236 :any:`notmuch-search-terms(7)` for more information about named
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
244 Default: empty list. Note that :any:`notmuch-setup(1)` puts
245 ``deleted;spam`` here when creating new configuration file.
247 .. _show.extra_headers:
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
257 History: This configuration value was introduced in notmuch 0.35.
262 Expansion for named query called <name>, using s-expression syntax. See
263 :any:`notmuch-sexp-queries(7)` for more information about s-expression
269 Default: ``$NAME`` variable if set, otherwise read from
273 A list of other email addresses at which you receive email
274 (see also, :ref:`user.primary_email <user.primary_email>`).
278 .. _user.primary_email:
281 Your primary email address.
283 Default: ``$EMAIL`` variable if set, otherwise constructed from
284 the username and hostname of the current machine.
294 Notmuch configuration file search order:
296 1. File specified by :option:`notmuch --config` global option; see
299 2. File specified by :envvar:`NOTMUCH_CONFIG` environment variable.
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.
305 4. ``$HOME/.notmuch-config.<profile>`` where ``<profile>`` is defined
306 by :envvar:`NOTMUCH_PROFILE` environment variable if set,
307 ``$HOME/.notmuch-config`` otherwise.
314 Notmuch database search order:
316 1. Directory specified by :envvar:`NOTMUCH_DATABASE` environment variable.
318 2. Directory specified by config key ``database.path``.
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.
324 4. Directory specified by :envvar:`MAILDIR` environment variable.
331 Notmuch hook directory search order:
333 1. Directory specified by ``database.hook_dir`` configuration option.
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.
339 3. ``<database.path>/.notmuch/hooks``
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)`