1 <h1>NOTMUCH-CONFIG(1)</h1>
5 notmuch-config - access notmuch configuration file
10 <b>notmuch</b> <b>config</b> <b>get</b> <<u>section</u>>.<<u>item</u>>
12 <b>notmuch</b> <b>config</b> <b>set</b> [--database] <<u>section</u>>.<<u>item</u>> [<u>value</u> ...]
14 <b>notmuch</b> <b>config</b> <b>list</b>
19 The <b>config</b> command can be used to get or set settings in the notmuch
20 configuration file and corresponding database.
22 <b>get</b> The value of the specified configuration item is printed to std‐
23 out. If the item has multiple values (it is a list), each value
24 is separated by a newline character.
26 <b>set</b> The specified configuration item is set to the given value. To
27 specify a multiple-value item (a list), provide each value as a
28 separate command-line argument.
30 If no values are provided, the specified configuration item will
31 be removed from the configuration file.
33 With the <u>--database</u> option, updates configuration metadata
34 stored in the database, rather than the default (text) configu‐
37 <b>list</b> Every configuration item is printed to stdout, each on a sepa‐
38 rate line of the form:
42 No additional whitespace surrounds the dot or equals sign char‐
43 acters. In a multiple-value item (a list), the values are sepa‐
44 rated by semicolon characters.
46 The available configuration items are described below. Non-absolute
47 paths are presumed relative to <u>$HOME</u> for items in section <b>database</b>.
50 Notmuch will store its database here, (in sub-directory named
51 <b>.notmuch</b> if <b>database.mail</b>_<b>root</b> is unset).
53 Default: see <u>DATABASE</u> <u>LOCATION</u>
55 <b>database.mail</b>_<b>root</b>
56 The top-level directory where your mail currently exists and to
57 where mail will be delivered in the future. Files should be in‐
58 dividual email messages.
60 History: this configuration value was introduced in notmuch
63 Default: For compatibility with older configurations, the value
64 of database.path is used if <b>database.mail</b>_<b>root</b> is unset.
66 <b>database.backup</b>_<b>dir</b>
67 Directory to store tag dumps when upgrading database.
69 History: this configuration value was introduced in notmuch
72 Default: A sibling directory of the Xapian database called <u>back‐</u>
75 <b>database.hook</b>_<b>dir</b>
76 Directory containing hooks run by notmuch commands. See <a href='../notmuch-hooks-5/'>not‐</a>
77 <a href='../notmuch-hooks-5/'>much-hooks</a>(5).
79 History: this configuration value was introduced in notmuch
82 Default: See HOOKS, below.
84 <b>database.autocommit</b>
85 How often to commit transactions to disk. <u>0</u> means wait until command
86 completes, otherwise an integer <u>n</u> specifies to commit to disk after
87 every <u>n</u> completed transactions.
89 History: this configuration value was introduced in notmuch 0.33.
94 Default: <b>$NAME</b> variable if set, otherwise read from <b>/etc/passwd</b>.
96 <b>user.primary</b>_<b>email</b>
97 Your primary email address.
99 Default: <b>$EMAIL</b> variable if set, otherwise constructed from the
100 username and hostname of the current machine.
102 <b>user.other</b>_<b>email</b>
103 A list of other email addresses at which you receive email.
108 A list of tags that will be added to all messages incorporated
109 by <b>notmuch</b> <b>new</b>.
111 Default: <b>unread;inbox</b>.
114 A list to specify files and directories that will not be
115 searched for messages by <a href='../notmuch-new-1/'>notmuch-new</a>(1). Each entry in the list
118 A file or a directory name, without path, that will be ignored,
119 regardless of the location in the mail store directory hierar‐
124 A regular expression delimited with // that will be matched
125 against the path of the file or directory relative to the data‐
126 base path. Matching files and directories will be ignored. The
127 beginning and end of string must be explicitly anchored. For ex‐
128 ample, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but
129 not "foo" or "bar/foobar".
133 <b>search.exclude</b>_<b>tags</b>
134 A list of tags that will be excluded from search results by de‐
135 fault. Using an excluded tag in a query will override that ex‐
138 Default: empty list. Note that <b>notmuch-setup</b>(1) puts
139 <b>deleted;spam</b> here when creating new configuration file.
141 <b>show.extra_headers</b>
142 By default <a href='../notmuch-show-1/'>notmuch-show</a>(1) includes the following headers in struc‐
143 tured output if they are present in the message: <u>Subject</u>, <u>From</u>, <u>To</u>,
144 <u>Cc</u>, <u>Bcc</u>, <u>Reply-To</u>, <u>Date</u>. This option allows the specification of a
145 list of further headers to output.
147 History: This configuration value was introduced in notmuch 0.35.
151 <b>maildir.synchronize</b>_<b>flags</b>
152 If true, then the following maildir flags (in message filenames)
153 will be synchronized with the corresponding notmuch tags:
155 ┌─────┬────────────────────────────┐
157 ├─────┼────────────────────────────┤
159 ├─────┼────────────────────────────┤
161 ├─────┼────────────────────────────┤
163 ├─────┼────────────────────────────┤
165 ├─────┼────────────────────────────┤
166 │S │ unread (added when 'S' │
167 │ │ flag is not present) │
168 └─────┴────────────────────────────┘
170 The <a href='../notmuch-new-1/'>notmuch-new</a>(1) command will notice flag changes in filenames
171 and update tags, while the <a href='../notmuch-tag-1/'>notmuch-tag</a>(1) and <a href='../notmuch-restore-1/'>notmuch-restore</a>(1)
172 commands will notice tag changes and update flags in filenames.
174 If there have been any changes in the maildir (new messages
175 added, old ones removed or renamed, maildir flags changed,
176 etc.), it is advisable to run <a href='../notmuch-new-1/'>notmuch-new</a>(1) before <a href='../notmuch-tag-1/'>not‐</a>
177 <a href='../notmuch-tag-1/'>much-tag</a>(1) or <a href='../notmuch-restore-1/'>notmuch-restore</a>(1) commands to ensure the tag
178 changes are properly synchronized to the maildir flags, as the
179 commands expect the database and maildir to be in sync.
181 Default: <b>true</b>.
184 Policy for decrypting encrypted messages during indexing. Must
185 be one of: <b>false</b>, <b>auto</b>, <b>nostash</b>, or <b>true</b>.
187 When indexing an encrypted e-mail message, if this variable is
188 set to <b>true</b>, notmuch will try to decrypt the message and index
189 the cleartext, stashing a copy of any discovered session keys
190 for the message. If <b>auto</b>, it will try to index the cleartext if
191 a stashed session key is already known for the message (e.g.
192 from a previous copy), but will not try to access your secret
193 keys. Use <b>false</b> to avoid decrypting even when a stashed session
194 key is already present.
196 <b>nostash</b> is the same as <b>true</b> except that it will not stash
197 newly-discovered session keys in the database.
199 From the command line (i.e. during <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-insert-1/'>notmuch-in‐</a>
200 <a href='../notmuch-insert-1/'>sert</a>(1), or <a href='../notmuch-reindex-1/'>notmuch-reindex</a>(1)), the user can override the data‐
201 base's stored decryption policy with the <b>--decrypt=</b> option.
203 Here is a table that summarizes the functionality of each of
206 ┌──────────────┬───────┬──────┬─────────┬──────┐
207 │ │ false │ auto │ nostash │ true │
208 ├──────────────┼───────┼──────┼─────────┼──────┤
209 │Index cleart‐ │ │ X │ X │ X │
211 │stashed ses‐ │ │ │ │ │
213 ├──────────────┼───────┼──────┼─────────┼──────┤
214 │Index cleart‐ │ │ │ X │ X │
215 │ext using se‐ │ │ │ │ │
217 ├──────────────┼───────┼──────┼─────────┼──────┤
218 │Stash session │ │ │ │ X │
220 ├──────────────┼───────┼──────┼─────────┼──────┤
222 │stashed ses‐ │ │ │ │ │
223 │sion keys on │ │ │ │ │
225 └──────────────┴───────┴──────┴─────────┴──────┘
227 Stashed session keys are kept in the database as properties as‐
228 sociated with the message. See <b>session-key</b> in <a href='../notmuch-properties-7/'>notmuch-proper‐</a>
229 <a href='../notmuch-properties-7/'>ties</a>(7) for more details about how they can be useful.
231 Be aware that the notmuch index is likely sufficient (and a
232 stashed session key is certainly sufficient) to reconstruct the
233 cleartext of the message itself, so please ensure that the not‐
234 much message index is adequately protected. DO NOT USE <b>in-</b>
235 <b>dex.decrypt=true</b> or <b>index.decrypt=nostash</b> without considering
236 the security of your index.
238 Default: <b>auto</b>.
240 <b>index.header.<prefix></b>
241 Define the query prefix <prefix>, based on a mail header. For
242 example <b>index.header.List=List-Id</b> will add a probabilistic pre‐
243 fix <b>List:</b> that searches the <b>List-Id</b> field. User defined pre‐
244 fixes must not start with 'a'...'z'; in particular adding a pre‐
245 fix with same name as a predefined prefix is not supported. See
246 <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for a list of existing prefixes, and an
247 explanation of probabilistic prefixes.
249 <b>built</b>_<b>with.<name></b>
250 Compile time feature <name>. Current possibilities include
251 "retry_lock" (configure option, included by default). (since
252 notmuch 0.30, "compact" and "field_processor" are always in‐
255 <b>query.<name></b>
256 Expansion for named query called <name>. See <a href='../notmuch-search-terms-7/'>not‐</a>
257 <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7) for more information about named queries.
259 <b>squery.<name></b>
260 Expansion for named query called <name>, using s-expression syn‐
261 tax. See <a href='../notmuch-sexp-queries-7/'>notmuch-sexp-queries</a>(7) for more information about
262 s-expression queries.
267 <h3> CONFIGURATION</h3>
269 Notmuch configuration file search order:
271 1. File specified by <b>notmuch</b> <b>--config</b> global option; see <a href='../notmuch-1/'>notmuch</a>(1).
273 2. File specified by <b>NOTMUCH</b>_<b>CONFIG</b> environment variable.
275 3. <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/<profile>/config</b> where <b><profile></b> is defined
276 by <b>NOTMUCH</b>_<b>PROFILE</b> environment variable if set, <b>$XDG</b>_<b>CON-</b>
277 <b>FIG</b>_<b>HOME/notmuch/default/config</b> otherwise.
279 4. <b>$HOME/.notmuch-config.<profile></b> where <b><profile></b> is defined by <b>NOT-</b>
280 <b>MUCH</b>_<b>PROFILE</b> environment variable if set, <b>$HOME/.notmuch-config</b> oth‐
284 <h3> DATABASE LOCATION</h3>
286 Notmuch database search order:
288 1. Directory specified by <b>NOTMUCH</b>_<b>DATABASE</b> environment variable.
290 2. Directory specified by config key <b>database.path</b>.
292 3. <b>$XDG</b>_<b>DATA</b>_<b>HOME/notmuch/<profile></b> where <b><profile></b> is defined by <b>NOT-</b>
293 <b>MUCH</b>_<b>PROFILE</b> environment variable if set, <b>$XDG</b>_<b>DATA</b>_<b>HOME/notmuch/de-</b>
294 <b>fault</b> otherwise.
296 4. Directory specified by <b>MAILDIR</b> environment variable.
301 <h3> HOOKS</h3>
303 Notmuch hook directory search order:
305 1. Directory specified by <b>database.hook</b>_<b>dir</b> configuration option.
307 2. <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/<profile>/hooks</b> where <b><profile></b> is defined
308 by <b>NOTMUCH</b>_<b>PROFILE</b> environment variable if set, <b>$XDG</b>_<b>CON-</b>
309 <b>FIG</b>_<b>HOME/notmuch/default/hooks</b> otherwise.
311 3. <b><database.path>/.notmuch/hooks</b>
316 <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>notmuch-hooks</a>(5), <a href='../notmuch-insert-1/'>not‐</a>
317 <a href='../notmuch-insert-1/'>much-insert</a>(1), <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-properties-7/'>notmuch-properties</a>(7), <a href='../notmuch-reply-1/'>notmuch-re‐</a>
318 <a href='../notmuch-reply-1/'>ply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7),
319 <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
324 Carl Worth and many others
329 2009-2022, Carl Worth and many others