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>maildir.synchronize</b>_<b>flags</b>
142 If true, then the following maildir flags (in message filenames)
143 will be synchronized with the corresponding notmuch tags:
145 ┌─────┬────────────────────────────┐
147 ├─────┼────────────────────────────┤
149 ├─────┼────────────────────────────┤
151 ├─────┼────────────────────────────┤
153 ├─────┼────────────────────────────┤
155 ├─────┼────────────────────────────┤
156 │S │ unread (added when 'S' │
157 │ │ flag is not present) │
158 └─────┴────────────────────────────┘
160 The <a href='../notmuch-new-1/'>notmuch-new</a>(1) command will notice flag changes in filenames
161 and update tags, while the <a href='../notmuch-tag-1/'>notmuch-tag</a>(1) and <a href='../notmuch-restore-1/'>notmuch-restore</a>(1)
162 commands will notice tag changes and update flags in filenames.
164 If there have been any changes in the maildir (new messages
165 added, old ones removed or renamed, maildir flags changed,
166 etc.), it is advisable to run <a href='../notmuch-new-1/'>notmuch-new</a>(1) before <a href='../notmuch-tag-1/'>not‐</a>
167 <a href='../notmuch-tag-1/'>much-tag</a>(1) or <a href='../notmuch-restore-1/'>notmuch-restore</a>(1) commands to ensure the tag
168 changes are properly synchronized to the maildir flags, as the
169 commands expect the database and maildir to be in sync.
171 Default: <b>true</b>.
174 Policy for decrypting encrypted messages during indexing. Must
175 be one of: <b>false</b>, <b>auto</b>, <b>nostash</b>, or <b>true</b>.
177 When indexing an encrypted e-mail message, if this variable is
178 set to <b>true</b>, notmuch will try to decrypt the message and index
179 the cleartext, stashing a copy of any discovered session keys
180 for the message. If <b>auto</b>, it will try to index the cleartext if
181 a stashed session key is already known for the message (e.g.
182 from a previous copy), but will not try to access your secret
183 keys. Use <b>false</b> to avoid decrypting even when a stashed session
184 key is already present.
186 <b>nostash</b> is the same as <b>true</b> except that it will not stash
187 newly-discovered session keys in the database.
189 From the command line (i.e. during <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-insert-1/'>notmuch-in‐</a>
190 <a href='../notmuch-insert-1/'>sert</a>(1), or <a href='../notmuch-reindex-1/'>notmuch-reindex</a>(1)), the user can override the data‐
191 base's stored decryption policy with the <b>--decrypt=</b> option.
193 Here is a table that summarizes the functionality of each of
196 ┌──────────────┬───────┬──────┬─────────┬──────┐
197 │ │ false │ auto │ nostash │ true │
198 └──────────────┴───────┴──────┴─────────┴──────┘
200 │Index cleart‐ │ │ X │ X │ X │
202 │stashed ses‐ │ │ │ │ │
204 ├──────────────┼───────┼──────┼─────────┼──────┤
205 │Index cleart‐ │ │ │ X │ X │
206 │ext using se‐ │ │ │ │ │
208 ├──────────────┼───────┼──────┼─────────┼──────┤
209 │Stash session │ │ │ │ X │
211 ├──────────────┼───────┼──────┼─────────┼──────┤
213 │stashed ses‐ │ │ │ │ │
214 │sion keys on │ │ │ │ │
216 └──────────────┴───────┴──────┴─────────┴──────┘
218 Stashed session keys are kept in the database as properties as‐
219 sociated with the message. See <b>session-key</b> in <a href='../notmuch-properties-7/'>notmuch-proper‐</a>
220 <a href='../notmuch-properties-7/'>ties</a>(7) for more details about how they can be useful.
222 Be aware that the notmuch index is likely sufficient (and a
223 stashed session key is certainly sufficient) to reconstruct the
224 cleartext of the message itself, so please ensure that the not‐
225 much message index is adequately protected. DO NOT USE <b>in-</b>
226 <b>dex.decrypt=true</b> or <b>index.decrypt=nostash</b> without considering
227 the security of your index.
229 Default: <b>auto</b>.
231 <b>index.header.<prefix></b>
232 Define the query prefix <prefix>, based on a mail header. For
233 example <b>index.header.List=List-Id</b> will add a probabilistic pre‐
234 fix <b>List:</b> that searches the <b>List-Id</b> field. User defined pre‐
235 fixes must not start with 'a'...'z'; in particular adding a pre‐
236 fix with same name as a predefined prefix is not supported. See
237 <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for a list of existing prefixes, and an
238 explanation of probabilistic prefixes.
240 <b>built</b>_<b>with.<name></b>
241 Compile time feature <name>. Current possibilities include
242 "retry_lock" (configure option, included by default). (since
243 notmuch 0.30, "compact" and "field_processor" are always in‐
246 <b>query.<name></b>
247 Expansion for named query called <name>. See <a href='../notmuch-search-terms-7/'>not‐</a>
248 <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7) for more information about named queries.
250 <b>squery.<name></b>
251 Expansion for named query called <name>, using s-expression syn‐
252 tax. See <a href='../notmuch-sexp-queries-7/'>notmuch-sexp-queries</a>(7) for more information about
253 s-expression queries.
258 <h3> CONFIGURATION</h3>
260 Notmuch configuration file search order:
262 1. File specified by <b>notmuch</b> <b>--config</b> global option; see <a href='../notmuch-1/'>notmuch</a>(1).
264 2. File specified by <b>NOTMUCH</b>_<b>CONFIG</b> environment variable.
266 3. <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/<profile>/config</b> where <b><profile></b> is defined
267 by <b>NOTMUCH</b>_<b>PROFILE</b> environment variable if set, <b>$XDG</b>_<b>CON-</b>
268 <b>FIG</b>_<b>HOME/notmuch/default/config</b> otherwise.
270 4. <b>$HOME/.notmuch-config.<profile></b> where <b><profile></b> is defined by <b>NOT-</b>
271 <b>MUCH</b>_<b>PROFILE</b> environment variable if set, <b>$HOME/.notmuch-config</b> oth‐
275 <h3> DATABASE LOCATION</h3>
277 Notmuch database search order:
279 1. Directory specified by <b>NOTMUCH</b>_<b>DATABASE</b> environment variable.
281 2. Directory specified by config key <b>database.path</b>.
283 3. <b>$XDG</b>_<b>DATA</b>_<b>HOME/notmuch/<profile></b> where <b><profile></b> is defined by <b>NOT-</b>
284 <b>MUCH</b>_<b>PROFILE</b> environment variable if set, <b>$XDG</b>_<b>DATA</b>_<b>HOME/notmuch/de-</b>
285 <b>fault</b> otherwise.
287 4. Directory specified by <b>MAILDIR</b> environment variable.
292 <h3> HOOKS</h3>
294 Notmuch hook directory search order:
296 1. Directory specified by <b>database.hook</b>_<b>dir</b> configuration option.
298 2. <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/<profile>/hooks</b> where <b><profile></b> is defined
299 by <b>NOTMUCH</b>_<b>PROFILE</b> environment variable if set, <b>$XDG</b>_<b>CON-</b>
300 <b>FIG</b>_<b>HOME/notmuch/default/hooks</b> otherwise.
302 3. <b><database.path>/.notmuch/hooks</b>
307 <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>
308 <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>
309 <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),
310 <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
315 Carl Worth and many others
320 2009-2021, Carl Worth and many others