1NOTMUCH-CONFIG(1) notmuch NOTMUCH-CONFIG(1)
2
6 notmuch-config - access notmuch configuration file
7
9 notmuch config get <section>.<item>
10 notmuch config set [--database] <section>.<item> [value ...]
12 notmuch config list
14
16 The config command can be used to get or set settings in the notmuch
17 configuration file and corresponding database.
18 get The value of the specified configuration item is printed to std‐
20 out. If the item has multiple values (it is a list), each value
21 is separated by a newline character.
22 set The specified configuration item is set to the given value. To
24 specify a multiple-value item (a list), provide each value as a
25 separate command-line argument.
26 If no values are provided, the specified configuration item will
28 be removed from the configuration file.
29 With the --database option, updates configuration metadata
31 stored in the database, rather than the default (text) configu‐
32 ration file.
33 list Every configuration item is printed to stdout, each on a sepa‐
35 rate line of the form:
36 section.item=value
38 No additional whitespace surrounds the dot or equals sign char‐
40 acters. In a multiple-value item (a list), the values are sepa‐
41 rated by semicolon characters.
42 The available configuration items are described below. Non-absolute
44 paths are presumed relative to $HOME for items in section database.
45 built_with.<name>
47 Compile time feature <name>. Current possibilities include
48 "retry_lock" (configure option, included by default). (since
49 notmuch 0.30, "compact" and "field_processor" are always in‐
50 cluded.)
51 database.autocommit
53 How often to commit transactions to disk. 0 means wait until command
54 completes, otherwise an integer n specifies to commit to disk after
55 every n completed transactions.
56 History: this configuration value was introduced in notmuch 0.33.
58 database.backup_dir
60 Directory to store tag dumps when upgrading database.
61 History: this configuration value was introduced in notmuch
63 0.32.
64 Default: A sibling directory of the Xapian database called back‐
66 ups.
67 database.hook_dir
69 Directory containing hooks run by notmuch commands. See not‐
70 much-hooks(5).
71 History: this configuration value was introduced in notmuch
73 0.32.
74 Default: See HOOKS, below.
76 database.mail_root
78 The top-level directory where your mail currently exists and to
79 where mail will be delivered in the future. Files should be in‐
80 dividual email messages.
81 History: this configuration value was introduced in notmuch
83 0.32.
84 Default: For compatibility with older configurations, the value
86 of database.path is used if database.mail_root is unset.
87 database.path
89 Notmuch will store its database here, (in sub-directory named
90 .notmuch if database.mail_root is unset).
91 Default: see DATABASE LOCATION
93 index.decrypt
95 Policy for decrypting encrypted messages during indexing. Must
96 be one of: false, auto, nostash, or true.
97 When indexing an encrypted e-mail message, if this variable is
99 set to true, notmuch will try to decrypt the message and index
100 the cleartext, stashing a copy of any discovered session keys
101 for the message. If auto, it will try to index the cleartext if
102 a stashed session key is already known for the message (e.g.
103 from a previous copy), but will not try to access your secret
104 keys. Use false to avoid decrypting even when a stashed session
105 key is already present.
106 nostash is the same as true except that it will not stash
108 newly-discovered session keys in the database.
109 From the command line (i.e. during notmuch-new(1), notmuch-in‐
111 sert(1), or notmuch-reindex(1)), the user can override the data‐
112 base's stored decryption policy with the --decrypt= option.
113 Here is a table that summarizes the functionality of each of
115 these policies:
116 ┌──────────────┬───────┬──────┬─────────┬──────┐
118 │ │ false │ auto │ nostash │ true │
119 ├──────────────┼───────┼──────┼─────────┼──────┤
120 │Index cleart‐ │ │ X │ X │ X │
121 │ext using │ │ │ │ │
122 │stashed ses‐ │ │ │ │ │
123 │sion keys │ │ │ │ │
124 ├──────────────┼───────┼──────┼─────────┼──────┤
125 │Index cleart‐ │ │ │ X │ X │
126 │ext using se‐ │ │ │ │ │
127 │cret keys │ │ │ │ │
128 ├──────────────┼───────┼──────┼─────────┼──────┤
129 │Stash session │ │ │ │ X │
130 │keys │ │ │ │ │
131 └──────────────┴───────┴──────┴─────────┴──────┘
132 │Delete │ X │ │ │ │
134 │stashed ses‐ │ │ │ │ │
135 │sion keys on │ │ │ │ │
136 │reindex │ │ │ │ │
137 └──────────────┴───────┴──────┴─────────┴──────┘
138 Stashed session keys are kept in the database as properties as‐
140 sociated with the message. See session-key in notmuch-proper‐
141 ties(7) for more details about how they can be useful.
142 Be aware that the notmuch index is likely sufficient (and a
144 stashed session key is certainly sufficient) to reconstruct the
145 cleartext of the message itself, so please ensure that the not‐
146 much message index is adequately protected. DO NOT USE in‐
147 dex.decrypt=true or index.decrypt=nostash without considering
148 the security of your index.
149 Default: auto.
151 index.header.<prefix>
153 Define the query prefix <prefix>, based on a mail header. For
154 example index.header.List=List-Id will add a probabilistic pre‐
155 fix List: that searches the List-Id field. User defined pre‐
156 fixes must not start with 'a'...'z'; in particular adding a pre‐
157 fix with same name as a predefined prefix is not supported. See
158 notmuch-search-terms(7) for a list of existing prefixes, and an
159 explanation of probabilistic prefixes.
160 maildir.synchronize_flags
162 If true, then the following maildir flags (in message filenames)
163 will be synchronized with the corresponding notmuch tags:
164 ┌─────┬────────────────────────────┐
166 │Flag │ Tag │
167 ├─────┼────────────────────────────┤
168 │D │ draft │
169 ├─────┼────────────────────────────┤
170 │F │ flagged │
171 ├─────┼────────────────────────────┤
172 │P │ passed │
173 ├─────┼────────────────────────────┤
174 │R │ replied │
175 ├─────┼────────────────────────────┤
176 │S │ unread (added when 'S' │
177 │ │ flag is not present) │
178 └─────┴────────────────────────────┘
179 The notmuch-new(1) command will notice flag changes in filenames
181 and update tags, while the notmuch-tag(1) and notmuch-restore(1)
182 commands will notice tag changes and update flags in filenames.
183 If there have been any changes in the maildir (new messages
185 added, old ones removed or renamed, maildir flags changed,
186 etc.), it is advisable to run notmuch-new(1) before not‐
187 much-tag(1) or notmuch-restore(1) commands to ensure the tag
188 changes are properly synchronized to the maildir flags, as the
189 commands expect the database and maildir to be in sync.
190 Default: true.
192 new.ignore
194 A list to specify files and directories that will not be
195 searched for messages by notmuch-new(1). Each entry in the list
196 is either:
197 A file or a directory name, without path, that will be ignored,
199 regardless of the location in the mail store directory hierar‐
200 chy.
201 Or:
203 A regular expression delimited with // that will be matched
205 against the path of the file or directory relative to the data‐
206 base path. Matching files and directories will be ignored. The
207 beginning and end of string must be explicitly anchored. For ex‐
208 ample, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but
209 not "foo" or "bar/foobar".
210 Default: empty list.
212 new.tags
214 A list of tags that will be added to all messages incorporated
215 by notmuch new.
216 Default: unread;inbox.
218 query.<name>
220 Expansion for named query called <name>. See not‐
221 much-search-terms(7) for more information about named queries.
222 search.exclude_tags
224 A list of tags that will be excluded from search results by de‐
225 fault. Using an excluded tag in a query will override that ex‐
226 clusion.
227 Default: empty list. Note that notmuch-setup(1) puts
229 deleted;spam here when creating new configuration file.
230 show.extra_headers
232 By default notmuch-show(1) includes the following headers in struc‐
233 tured output if they are present in the message: Subject, From, To,
234 Cc, Bcc, Reply-To, Date. This option allows the specification of a
235 list of further headers to output.
236 History: This configuration value was introduced in notmuch 0.35.
238 Default: empty list.
240 squery.<name>
242 Expansion for named query called <name>, using s-expression syn‐
243 tax. See notmuch-sexp-queries(7) for more information about
244 s-expression queries.
245 user.name
247 Your full name.
248 Default: $NAME variable if set, otherwise read from /etc/passwd.
250 user.other_email
252 A list of other email addresses at which you receive email (see
253 also, user.primary_email).
254 Default: not set.
256 user.primary_email
258 Your primary email address.
259 Default: $EMAIL variable if set, otherwise constructed from the
261 username and hostname of the current machine.
262
264 CONFIGURATION
265 Notmuch configuration file search order:
266 1. File specified by notmuch --config global option; see notmuch(1).
268 2. File specified by NOTMUCH_CONFIG environment variable.
270 3. $XDG_CONFIG_HOME/notmuch/<profile>/config where <profile> is defined
272 by NOTMUCH_PROFILE environment variable if set, $XDG_CON‐
273 FIG_HOME/notmuch/default/config otherwise.
274 4. $HOME/.notmuch-config.<profile> where <profile> is defined by NOT‐
276 MUCH_PROFILE environment variable if set, $HOME/.notmuch-config oth‐
277 erwise.
278 DATABASE LOCATION
280 Notmuch database search order:
281 1. Directory specified by NOTMUCH_DATABASE environment variable.
283 2. Directory specified by config key database.path.
285 3. $XDG_DATA_HOME/notmuch/<profile> where <profile> is defined by NOT‐
287 MUCH_PROFILE environment variable if set, $XDG_DATA_HOME/notmuch/de‐
288 fault otherwise.
289 4. Directory specified by MAILDIR environment variable.
291 5. $HOME/mail
293 HOOKS
295 Notmuch hook directory search order:
296 1. Directory specified by database.hook_dir configuration option.
298 2. $XDG_CONFIG_HOME/notmuch/<profile>/hooks where <profile> is defined
300 by NOTMUCH_PROFILE environment variable if set, $XDG_CON‐
301 FIG_HOME/notmuch/default/hooks otherwise.
302 3. <database.path>/.notmuch/hooks
304
306 notmuch(1), notmuch-count(1), notmuch-dump(1), notmuch-hooks(5), not‐
307 much-insert(1), notmuch-new(1), notmuch-properties(7), notmuch-re‐
308 ply(1), notmuch-restore(1), notmuch-search(1), notmuch-search-terms(7),
309 notmuch-show(1), notmuch-tag(1)
310
312 Carl Worth and many others
313
315 2009-2022, Carl Worth and many others
3160.36 Jun 25, 2022 NOTMUCH-CONFIG(1)