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
54              command completes, otherwise an integer n specifies to commit to
55              disk after every n completed transactions.
56
57              History: this configuration  value  was  introduced  in  notmuch
58              0.33.
59
60       database.backup_dir
61              Directory to store tag dumps when upgrading database.
62
63              History:  this  configuration  value  was  introduced in notmuch
64              0.32.
65
66              Default: A sibling directory of the Xapian database called back‐
67              ups.
68
69       database.hook_dir
70              Directory   containing   hooks  run  by  notmuch  commands.  See
71              notmuch-hooks.
72
73              History: this configuration  value  was  introduced  in  notmuch
74              0.32.
75
76              Default: See HOOKS, below.
77
78       database.mail_root
79              The  top-level directory where your mail currently exists and to
80              where mail will be delivered in the future. Files should be  in‐
81              dividual email messages.
82
83              History:  this  configuration  value  was  introduced in notmuch
84              0.32.
85
86              Default: For compatibility with older configurations, the  value
87              of database.path is used if database.mail_root is unset.
88
89       database.path
90              Notmuch  will  store  its database here, (in sub-directory named
91              .notmuch if database.mail_root is unset).
92
93              Default: see DATABASE LOCATION
94
95       git.path
96              Default location for git repository for notmuch-git.
97
98       git.safe_fraction
99              Some notmuch-git operations check that the fraction of  messages
100              changed  (in  the database or in git, as appropriate) is not too
101              large. This item controls what fraction  of  total  messages  is
102              considered "not too large".
103
104       git.tag_prefix
105              Default tag prefix (filter) for notmuch-git.
106
107       index.decrypt
108              Policy  for decrypting encrypted messages during indexing.  Must
109              be one of: false, auto, nostash, or true.
110
111              When indexing an encrypted e-mail message, if this  variable  is
112              set  to  true, notmuch will try to decrypt the message and index
113              the cleartext, stashing a copy of any  discovered  session  keys
114              for the message.  If auto, it will try to index the cleartext if
115              a stashed session key is already known  for  the  message  (e.g.
116              from  a  previous  copy), but will not try to access your secret
117              keys.  Use false to avoid decrypting even when a stashed session
118              key is already present.
119
120              nostash  is  the  same  as  true  except  that it will not stash
121              newly-discovered session keys in the database.
122
123              From the command line (i.e. during notmuch-new,  notmuch-insert,
124              or notmuch-reindex), the user can override the database's stored
125              decryption policy with the --decrypt= option.
126
127              Here is a table that summarizes the  functionality  of  each  of
128              these policies:
129
130
131
132
133                      ┌──────────────┬───────┬──────┬─────────┬──────┐
134                      │              │ false │ auto │ nostash │ true │
135                      ├──────────────┼───────┼──────┼─────────┼──────┤
136                      │Index cleart‐ │       │ X    │ X       │ X    │
137                      │ext     using │       │      │         │      │
138                      │stashed  ses‐ │       │      │         │      │
139                      │sion keys     │       │      │         │      │
140                      ├──────────────┼───────┼──────┼─────────┼──────┤
141                      │Index cleart‐ │       │      │ X       │ X    │
142                      │ext using se‐ │       │      │         │      │
143                      │cret keys     │       │      │         │      │
144                      ├──────────────┼───────┼──────┼─────────┼──────┤
145                      │Stash session │       │      │         │ X    │
146                      │keys          │       │      │         │      │
147                      ├──────────────┼───────┼──────┼─────────┼──────┤
148                      │Delete        │ X     │      │         │      │
149                      │stashed  ses‐ │       │      │         │      │
150                      │sion  keys on │       │      │         │      │
151                      │reindex       │       │      │         │      │
152                      └──────────────┴───────┴──────┴─────────┴──────┘
153
154              Stashed session keys are kept in the database as properties  as‐
155              sociated    with    the    message.     See    session-key    in
156              notmuch-properties for more details about how they can  be  use‐
157              ful.
158
159              Be  aware  that  the  notmuch  index is likely sufficient (and a
160              stashed session key is certainly sufficient) to reconstruct  the
161              cleartext  of the message itself, so please ensure that the not‐
162              much message index is adequately  protected.   DO  NOT  USE  in‐
163              dex.decrypt=true  or  index.decrypt=nostash  without considering
164              the security of your index.
165
166              Default: auto.
167
168       index.header.<prefix>
169              Define the query prefix <prefix>, based on a  mail  header.  For
170              example  index.header.List=List-Id will add a probabilistic pre‐
171              fix List: that searches the List-Id field.   User  defined  pre‐
172              fixes must not start with 'a'...'z'; in particular adding a pre‐
173              fix with same name as a predefined prefix is not supported.  See
174              notmuch-search-terms for a list of existing prefixes, and an ex‐
175              planation of probabilistic prefixes.
176
177       maildir.synchronize_flags
178              If true, then the following maildir flags (in message filenames)
179              will be synchronized with the corresponding notmuch tags:
180
181                            ┌─────┬────────────────────────────┐
182                            │Flag │ Tag                        │
183                            ├─────┼────────────────────────────┤
184                            │D    │ draft                      │
185                            ├─────┼────────────────────────────┤
186                            │F    │ flagged                    │
187                            ├─────┼────────────────────────────┤
188                            │P    │ passed                     │
189                            ├─────┼────────────────────────────┤
190                            │R    │ replied                    │
191                            ├─────┼────────────────────────────┤
192                            │S    │ unread   (added  when  'S' │
193                            │     │ flag is not present)       │
194                            └─────┴────────────────────────────┘
195
196              The notmuch-new command will notice flag  changes  in  filenames
197              and  update tags, while the notmuch-tag and notmuch-restore com‐
198              mands will notice tag changes and update flags in filenames.
199
200              If there have been any changes  in  the  maildir  (new  messages
201              added,  old  ones  removed  or  renamed,  maildir flags changed,
202              etc.), it is advisable to run notmuch-new before notmuch-tag  or
203              notmuch-restore  commands to ensure the tag changes are properly
204              synchronized to the maildir flags, as the  commands  expect  the
205              database and maildir to be in sync.
206
207              Default: true.
208
209       new.ignore
210              A  list  to  specify  files  and  directories  that  will not be
211              searched for messages by notmuch-new. Each entry in the list  is
212              either:
213
214              A  file or a directory name, without path, that will be ignored,
215              regardless of the location in the mail store  directory  hierar‐
216              chy.
217
218              Or:
219
220              A  regular  expression  delimited  with  // that will be matched
221              against the path of the file or directory relative to the  data‐
222              base  path.  Matching files and directories will be ignored. The
223              beginning and end of string must be explicitly anchored. For ex‐
224              ample,  /.*/foo$/  would  match "bar/foo" and "bar/baz/foo", but
225              not "foo" or "bar/foobar".
226
227              Default: empty list.
228
229       new.tags
230              A list of tags that will be added to all  messages  incorporated
231              by notmuch new.
232
233              Default: unread;inbox.
234
235       query.<name>
236              Expansion     for     named    query    called    <name>.    See
237              notmuch-search-terms for more information about named queries.
238
239       search.exclude_tags
240              A list of tags that will be excluded from search results by  de‐
241              fault.  Using  an excluded tag in a query will override that ex‐
242              clusion.
243
244              Default: empty list. Note that notmuch  puts  deleted;spam  here
245              when creating new configuration file.
246
247       show.extra_headers
248              By default notmuch-show includes the following headers in struc‐
249              tured output if they are present in the message: Subject,  From,
250              To,  Cc,  Bcc, Reply-To, Date. This option allows the specifica‐
251              tion of a list of further headers to output.
252
253              History: This configuration  value  was  introduced  in  notmuch
254              0.35.
255
256              Default: empty list.
257
258       squery.<name>
259              Expansion for named query called <name>, using s-expression syn‐
260              tax. See notmuch-sexp-queries for more information  about  s-ex‐
261              pression queries.
262
263       user.name
264              Your full name.
265
266              Default: $NAME variable if set, otherwise read from /etc/passwd.
267
268       user.other_email
269              A  list of other email addresses at which you receive email (see
270              also, user.primary_email)
271
272              Default: not set.
273
274       user.primary_email
275              Your primary email address.
276
277              Default: $EMAIL variable if set, otherwise constructed from  the
278              username and hostname of the current machine.
279

FILES

281   CONFIGURATION
282       Notmuch configuration file search order:
283
284       1. File specified by notmuch --config global option; see notmuch.
285
286       2. File specified by NOTMUCH_CONFIG environment variable.
287
288       3. $XDG_CONFIG_HOME/notmuch/<profile>/config where <profile> is defined
289          by  NOTMUCH_PROFILE   environment   variable   if   set,   $XDG_CON‐
290          FIG_HOME/notmuch/default/config otherwise.
291
292       4. $HOME/.notmuch-config.<profile>   where   <profile>  is  defined  by
293          NOTMUCH_PROFILE environment variable if  set,  $HOME/.notmuch-config
294          otherwise.
295
296   DATABASE LOCATION
297       Notmuch database search order:
298
299       1. Directory specified by NOTMUCH_DATABASE environment variable.
300
301       2. Directory specified by config key database.path.
302
303       3. $XDG_DATA_HOME/notmuch/<profile>   where  <profile>  is  defined  by
304          NOTMUCH_PROFILE environment  variable  if  set,  $XDG_DATA_HOME/not‐
305          much/default otherwise.
306
307       4. Directory specified by MAILDIR environment variable.
308
309       5. $HOME/mail
310
311   HOOKS
312       Notmuch hook directory search order:
313
314       1. Directory specified by database.hook_dir configuration option.
315
316       2. $XDG_CONFIG_HOME/notmuch/<profile>/hooks  where <profile> is defined
317          by  NOTMUCH_PROFILE   environment   variable   if   set,   $XDG_CON‐
318          FIG_HOME/notmuch/default/hooks otherwise.
319
320       3. <database.path>/.notmuch/hooks
321

SEE ALSO

323       notmuch,  notmuch-count,  notmuch-dump,  notmuch-hooks, notmuch-insert,
324       notmuch-new,   notmuch-properties,   notmuch-reply,    notmuch-restore,
325       notmuch-search, notmuch-search-terms, notmuch-show, notmuch-tag
326

AUTHOR

328       Carl Worth and many others
329
331       2009-2023, Carl Worth and many others
332
333
334
335
3360.37                             Jan 19, 2023                NOTMUCH-CONFIG(1)
Impressum