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.
49 Notmuch will store its database here, (in sub-directory named
50 <b>.notmuch</b> if <b>database.mail</b>_<b>root</b> is unset).
52 Default: <b>$MAILDIR</b> variable if set, otherwise <b>$HOME/mail</b>.
54 <b>database.mail</b>_<b>root</b>
55 The top-level directory where your mail currently exists and to
56 where mail will be delivered in the future. Files should be in‐
57 dividual email messages.
59 History: this configuration value was introduced in notmuch
62 Default: For compatibility with older configurations, the value
63 of database.path is used if <b>database.mail</b>_<b>root</b> is unset.
65 <b>database.hook</b>_<b>dir</b>
66 Directory containing hooks run by notmuch commands. See <a href='../notmuch-hooks-5/'>not‐</a>
67 <a href='../notmuch-hooks-5/'>much-hooks</a>(5).
72 Default: <b>$NAME</b> variable if set, otherwise read from <b>/etc/passwd</b>.
74 <b>user.primary</b>_<b>email</b>
75 Your primary email address.
77 Default: <b>$EMAIL</b> variable if set, otherwise constructed from the
78 username and hostname of the current machine.
80 <b>user.other</b>_<b>email</b>
81 A list of other email addresses at which you receive email.
86 A list of tags that will be added to all messages incorporated
87 by <b>notmuch</b> <b>new</b>.
89 Default: <b>unread;inbox</b>.
92 A list to specify files and directories that will not be
93 searched for messages by <b>notmuch</b> <b>new</b>. Each entry in the list is
96 A file or a directory name, without path, that will be ignored,
97 regardless of the location in the mail store directory hierar‐
102 A regular expression delimited with // that will be matched
103 against the path of the file or directory relative to the data‐
104 base path. Matching files and directories will be ignored. The
105 beginning and end of string must be explicitly anchored. For ex‐
106 ample, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but
107 not "foo" or "bar/foobar".
111 <b>search.exclude</b>_<b>tags</b>
112 A list of tags that will be excluded from search results by de‐
113 fault. Using an excluded tag in a query will override that ex‐
116 Default: empty list. Note that <b>notmuch-setup</b>(1) puts
117 <b>deleted;spam</b> here when creating new configuration file.
119 <b>maildir.synchronize</b>_<b>flags</b>
120 If true, then the following maildir flags (in message filenames)
121 will be synchronized with the corresponding notmuch tags:
123 ┌─────┬────────────────────────────┐
125 ├─────┼────────────────────────────┤
127 ├─────┼────────────────────────────┤
129 ├─────┼────────────────────────────┤
131 ├─────┼────────────────────────────┤
133 ├─────┼────────────────────────────┤
134 │S │ unread (added when 'S' │
135 │ │ flag is not present) │
136 └─────┴────────────────────────────┘
138 The <b>notmuch</b> <b>new</b> command will notice flag changes in filenames
139 and update tags, while the <b>notmuch</b> <b>tag</b> and <b>notmuch</b> <b>restore</b> com‐
140 mands will notice tag changes and update flags in filenames.
142 If there have been any changes in the maildir (new messages
143 added, old ones removed or renamed, maildir flags changed,
144 etc.), it is advisable to run <b>notmuch</b> <b>new</b> before <b>notmuch</b> <b>tag</b> or
145 <b>notmuch</b> <b>restore</b> commands to ensure the tag changes are properly
146 synchronized to the maildir flags, as the commands expect the
147 database and maildir to be in sync.
149 Default: <b>true</b>.
152 Policy for decrypting encrypted messages during indexing. Must
153 be one of: <b>false</b>, <b>auto</b>, <b>nostash</b>, or <b>true</b>.
155 When indexing an encrypted e-mail message, if this variable is
156 set to <b>true</b>, notmuch will try to decrypt the message and index
157 the cleartext, stashing a copy of any discovered session keys
158 for the message. If <b>auto</b>, it will try to index the cleartext if
159 a stashed session key is already known for the message (e.g.
160 from a previous copy), but will not try to access your secret
161 keys. Use <b>false</b> to avoid decrypting even when a stashed session
162 key is already present.
164 <b>nostash</b> is the same as <b>true</b> except that it will not stash
165 newly-discovered session keys in the database.
167 From the command line (i.e. during <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-insert-1/'>notmuch-in‐</a>
168 <a href='../notmuch-insert-1/'>sert</a>(1), or <a href='../notmuch-reindex-1/'>notmuch-reindex</a>(1)), the user can override the data‐
169 base's stored decryption policy with the <b>--decrypt=</b> option.
171 Here is a table that summarizes the functionality of each of
174 ┌──────────────┬───────┬──────┬─────────┬──────┐
175 │ │ false │ auto │ nostash │ true │
176 ├──────────────┼───────┼──────┼─────────┼──────┤
177 │Index cleart‐ │ │ X │ X │ X │
179 │stashed ses‐ │ │ │ │ │
181 ├──────────────┼───────┼──────┼─────────┼──────┤
182 │Index cleart‐ │ │ │ X │ X │
183 │ext using se‐ │ │ │ │ │
185 ├──────────────┼───────┼──────┼─────────┼──────┤
186 │Stash session │ │ │ │ X │
188 ├──────────────┼───────┼──────┼─────────┼──────┤
190 │stashed ses‐ │ │ │ │ │
191 │sion keys on │ │ │ │ │
193 └──────────────┴───────┴──────┴─────────┴──────┘
195 Stashed session keys are kept in the database as properties as‐
196 sociated with the message. See <b>session-key</b> in <a href='../notmuch-properties-7/'>notmuch-proper‐</a>
197 <a href='../notmuch-properties-7/'>ties</a>(7) for more details about how they can be useful.
199 Be aware that the notmuch index is likely sufficient (and a
200 stashed session key is certainly sufficient) to reconstruct the
201 cleartext of the message itself, so please ensure that the not‐
202 much message index is adequately protected. DO NOT USE <b>in-</b>
203 <b>dex.decrypt=true</b> or <b>index.decrypt=nostash</b> without considering
204 the security of your index.
206 Default: <b>auto</b>.
208 <b>index.header.<prefix></b>
209 Define the query prefix <prefix>, based on a mail header. For
210 example <b>index.header.List=List-Id</b> will add a probabilistic pre‐
211 fix <b>List:</b> that searches the <b>List-Id</b> field. User defined pre‐
212 fixes must not start with 'a'...'z'; in particular adding a pre‐
213 fix with same name as a predefined prefix is not supported. See
214 <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for a list of existing prefixes, and an
215 explanation of probabilistic prefixes.
217 <b>built</b>_<b>with.<name></b>
218 Compile time feature <name>. Current possibilities include
219 "retry_lock" (configure option, included by default). (since
220 notmuch 0.30, "compact" and "field_processor" are always in‐
223 <b>query.<name></b>
224 Expansion for named query called <name>. See <a href='../notmuch-search-terms-7/'>not‐</a>
225 <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7) for more information about named queries.
230 The following environment variables can be used to control the behavior
233 <b>NOTMUCH</b>_<b>CONFIG</b>
234 Specifies the location of the notmuch configuration file.
236 <b>NOTMUCH</b>_<b>PROFILE</b>
237 Selects among notmuch configurations.
242 <h3> CONFIGURATION</h3>
244 If <b>NOTMUCH</b>_<b>CONFIG</b> is unset, notmuch tries (in order)
246 • <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/<profile>/config</b> where <b><profile></b> is defined
247 by <b>$NOTMUCH</b>_<b>PROFILE</b> or "default"
249 • <b>${HOME}/.notmuch-config<profile></b> where <b><profile></b> is <b>.$NOTMUCH</b>_<b>PROFILE</b>
253 <h3> Hooks</h3>
255 If <b>database.hook</b>_<b>dir</b> is unset, notmuch tries (in order)
257 • <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/<profile>/hooks</b> where <b><profile></b> is defined
258 by <b>$NOTMUCH</b>_<b>PROFILE</b> or "default"
260 • <b><database.path>/.notmuch/hooks</b>
265 <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>
266 <a href='../notmuch-insert-1/'>much-insert</a>(1), <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-reply-1/'>notmuch-reply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1),
267 <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-properties-7/'>notmuch-properties</a>(7), <a href='../notmuch-show-1/'>not‐</a>
268 <a href='../notmuch-show-1/'>much-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
273 Carl Worth and many others
278 2009-2021, Carl Worth and many others