1NOTMUCH-CONFIG(1)                   notmuch                  NOTMUCH-CONFIG(1)
2
3
4

NAME

6       notmuch-config - access notmuch configuration file
7

SYNOPSIS

9       notmuch config get <section>.<item>
10
11       notmuch config set [--database] <section>.<item> [value ...]
12
13       notmuch config list
14

DESCRIPTION

16       The  config  command  can be used to get or set settings in the notmuch
17       configuration file and corresponding database.
18
19       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
23       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
27              If no values are provided, the specified configuration item will
28              be removed from the configuration file.
29
30              With  the  --database  option,  updates  configuration  metadata
31              stored in the database, rather than the default (text)  configu‐
32              ration file.
33
34       list   Every  configuration  item is printed to stdout, each on a sepa‐
35              rate line of the form:
36
37                 section.item=value
38
39              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
43       The available configuration items  are  described  below.  Non-absolute
44       paths are presumed relative to $HOME for items in section database.
45
46       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
52       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
57          History: this configuration value was introduced in notmuch 0.33.
58
59       database.backup_dir
60              Directory to store tag dumps when upgrading database.
61
62              History: this configuration  value  was  introduced  in  notmuch
63              0.32.
64
65              Default: A sibling directory of the Xapian database called back‐
66              ups.
67
68       database.hook_dir
69              Directory containing hooks run by  notmuch  commands.  See  not‐
70              much-hooks(5).
71
72              History:  this  configuration  value  was  introduced in notmuch
73              0.32.
74
75              Default: See HOOKS, below.
76
77       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
82              History: this configuration  value  was  introduced  in  notmuch
83              0.32.
84
85              Default:  For compatibility with older configurations, the value
86              of database.path is used if database.mail_root is unset.
87
88       database.path
89              Notmuch will store its database here,  (in  sub-directory  named
90              .notmuch if database.mail_root is unset).
91
92              Default: see DATABASE LOCATION
93
94       index.decrypt
95              Policy  for decrypting encrypted messages during indexing.  Must
96              be one of: false, auto, nostash, or true.
97
98              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
107              nostash  is  the  same  as  true  except  that it will not stash
108              newly-discovered session keys in the database.
109
110              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
114              Here is a table that summarizes the  functionality  of  each  of
115              these policies:
116
117                      ┌──────────────┬───────┬──────┬─────────┬──────┐
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
133                      │Delete        │ X     │      │         │      │
134                      │stashed  ses‐ │       │      │         │      │
135                      │sion  keys on │       │      │         │      │
136                      │reindex       │       │      │         │      │
137                      └──────────────┴───────┴──────┴─────────┴──────┘
138
139              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
143              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
150              Default: auto.
151
152       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
161       maildir.synchronize_flags
162              If true, then the following maildir flags (in message filenames)
163              will be synchronized with the corresponding notmuch tags:
164
165                            ┌─────┬────────────────────────────┐
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
180              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
184              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
191              Default: true.
192
193       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
198              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
202              Or:
203
204              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
211              Default: empty list.
212
213       new.tags
214              A  list  of tags that will be added to all messages incorporated
215              by notmuch new.
216
217              Default: unread;inbox.
218
219       query.<name>
220              Expansion   for   named   query   called   <name>.   See    not‐
221              much-search-terms(7) for more information about named queries.
222
223       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
228              Default:   empty   list.   Note   that   notmuch-setup(1)   puts
229              deleted;spam here when creating new configuration file.
230
231       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
237          History: This configuration value was introduced in notmuch 0.35.
238
239          Default: empty list.
240
241       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
246       user.name
247              Your full name.
248
249              Default: $NAME variable if set, otherwise read from /etc/passwd.
250
251       user.other_email
252              A  list of other email addresses at which you receive email (see
253              also, user.primary_email).
254
255              Default: not set.
256
257       user.primary_email
258              Your primary email address.
259
260              Default: $EMAIL variable if set, otherwise constructed from  the
261              username and hostname of the current machine.
262

FILES

264   CONFIGURATION
265       Notmuch configuration file search order:
266
267       1. File specified by notmuch --config global option; see notmuch(1).
268
269       2. File specified by NOTMUCH_CONFIG environment variable.
270
271       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
275       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
279   DATABASE LOCATION
280       Notmuch database search order:
281
282       1. Directory specified by NOTMUCH_DATABASE environment variable.
283
284       2. Directory specified by config key database.path.
285
286       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
290       4. Directory specified by MAILDIR environment variable.
291
292       5. $HOME/mail
293
294   HOOKS
295       Notmuch hook directory search order:
296
297       1. Directory specified by database.hook_dir configuration option.
298
299       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
303       3. <database.path>/.notmuch/hooks
304

SEE ALSO

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

AUTHOR

312       Carl Worth and many others
313
315       2009-2022, Carl Worth and many others
316
317
318
319
3200.36                             Jun 25, 2022                NOTMUCH-CONFIG(1)
Impressum