]> git.cworth.org Git - notmuch/blob - doc/man1/notmuch-config.rst
test: add known broken tests for python bindings in split configs
[notmuch] / doc / man1 / notmuch-config.rst
1 .. _notmuch-config(1):
2
3 ==============
4 notmuch-config
5 ==============
6
7 SYNOPSIS
8 ========
9
10 **notmuch** **config** **get** <*section*>.<*item*>
11
12 **notmuch** **config** **set** [--database] <*section*>.<*item*> [*value* ...]
13
14 **notmuch** **config** **list**
15
16 DESCRIPTION
17 ===========
18
19 The **config** command can be used to get or set settings in the notmuch
20 configuration file and corresponding database.
21
22 .. program:: config
23
24 .. option:: get
25
26    The value of the specified configuration item is printed to
27    stdout. If the item has multiple values (it is a list), each value
28    is separated by a newline character.
29
30 .. option:: set
31
32    The specified configuration item is set to the given value. To
33    specify a multiple-value item (a list), provide each value as a
34    separate command-line argument.
35
36    If no values are provided, the specified configuration item will
37    be removed from the configuration file.
38
39    With the `--database` option, updates configuration metadata
40    stored in the database, rather than the default (text)
41    configuration file.
42
43 .. option:: list
44
45    Every configuration item is printed to stdout, each on a separate
46    line of the form::
47
48      section.item=value
49
50    No additional whitespace surrounds the dot or equals sign
51    characters. In a multiple-value item (a list), the values are
52    separated by semicolon characters.
53
54 The available configuration items are described below. Non-absolute
55 paths are presumed relative to `$HOME` for items in section
56 **database**.
57
58 **database.path**
59     Notmuch will store its database here, (in
60     sub-directory named ``.notmuch`` if **database.mail\_root**
61     is unset).
62
63     Default: see :ref:`database`
64
65 **database.mail_root**
66     The top-level directory where your mail currently exists and to
67     where mail will be delivered in the future. Files should be
68     individual email messages.
69
70     History: this configuration value was introduced in notmuch 0.32.
71
72     Default: For compatibility with older configurations, the value of
73     database.path is used if **database.mail\_root** is unset.
74
75 **database.backup_dir**
76     Directory to store tag dumps when upgrading database.
77
78     History: this configuration value was introduced in notmuch 0.32.
79
80     Default: A sibling directory of the Xapian database called
81     `backups`.
82
83 **database.hook_dir**
84     Directory containing hooks run by notmuch commands. See
85     :any:`notmuch-hooks(5)`.
86
87     History: this configuration value was introduced in notmuch 0.32.
88
89     Default: See HOOKS, below.
90
91 **database.autocommit**
92
93     How often to commit transactions to disk. `0` means wait until
94     command completes, otherwise an integer `n` specifies to commit to
95     disk after every `n` completed transactions.
96
97     History: this configuration value was introduced in notmuch 0.33.
98
99 **user.name**
100     Your full name.
101
102     Default: ``$NAME`` variable if set, otherwise read from
103     ``/etc/passwd``.
104
105 **user.primary\_email**
106     Your primary email address.
107
108     Default: ``$EMAIL`` variable if set, otherwise constructed from
109     the username and hostname of the current machine.
110
111 **user.other\_email**
112     A list of other email addresses at which you receive email.
113
114     Default: not set.
115
116 **new.tags**
117     A list of tags that will be added to all messages incorporated by
118     **notmuch new**.
119
120     Default: ``unread;inbox``.
121
122 **new.ignore**
123     A list to specify files and directories that will not be searched
124     for messages by :any:`notmuch-new(1)`. Each entry in the list is either:
125
126     A file or a directory name, without path, that will be ignored,
127     regardless of the location in the mail store directory hierarchy.
128
129     Or:
130
131     A regular expression delimited with // that will be matched
132     against the path of the file or directory relative to the database
133     path. Matching files and directories will be ignored. The
134     beginning and end of string must be explicitly anchored. For
135     example, /.*/foo$/ would match "bar/foo" and "bar/baz/foo", but
136     not "foo" or "bar/foobar".
137
138     Default: empty list.
139
140 **search.exclude\_tags**
141     A list of tags that will be excluded from search results by
142     default. Using an excluded tag in a query will override that
143     exclusion.
144
145     Default: empty list. Note that :any:`notmuch-setup(1)` puts
146     ``deleted;spam`` here when creating new configuration file.
147
148 **maildir.synchronize\_flags**
149     If true, then the following maildir flags (in message filenames)
150     will be synchronized with the corresponding notmuch tags:
151
152     +--------+-----------------------------------------------+
153     | Flag   | Tag                                           |
154     +========+===============================================+
155     | D      | draft                                         |
156     +--------+-----------------------------------------------+
157     | F      | flagged                                       |
158     +--------+-----------------------------------------------+
159     | P      | passed                                        |
160     +--------+-----------------------------------------------+
161     | R      | replied                                       |
162     +--------+-----------------------------------------------+
163     | S      | unread (added when 'S' flag is not present)   |
164     +--------+-----------------------------------------------+
165
166     The :any:`notmuch-new(1)` command will notice flag changes in
167     filenames and update tags, while the :any:`notmuch-tag(1)` and
168     :any:`notmuch-restore(1)` commands will notice tag changes and
169     update flags in filenames.
170
171     If there have been any changes in the maildir (new messages added,
172     old ones removed or renamed, maildir flags changed, etc.), it is
173     advisable to run :any:`notmuch-new(1)` before
174     :any:`notmuch-tag(1)` or :any:`notmuch-restore(1)` commands to
175     ensure the tag changes are properly synchronized to the maildir
176     flags, as the commands expect the database and maildir to be in
177     sync.
178
179     Default: ``true``.
180
181 **index.decrypt**
182     Policy for decrypting encrypted messages during indexing.  Must be
183     one of: ``false``, ``auto``, ``nostash``, or ``true``.
184
185     When indexing an encrypted e-mail message, if this variable is set
186     to ``true``, notmuch will try to decrypt the message and index the
187     cleartext, stashing a copy of any discovered session keys for the
188     message.  If ``auto``, it will try to index the cleartext if a
189     stashed session key is already known for the message (e.g. from a
190     previous copy), but will not try to access your secret keys.  Use
191     ``false`` to avoid decrypting even when a stashed session key is
192     already present.
193
194     ``nostash`` is the same as ``true`` except that it will not stash
195     newly-discovered session keys in the database.
196
197     From the command line (i.e. during :any:`notmuch-new(1)`,
198     :any:`notmuch-insert(1)`, or :any:`notmuch-reindex(1)`), the user can
199     override the database's stored decryption policy with the
200     ``--decrypt=`` option.
201
202     Here is a table that summarizes the functionality of each of these
203     policies:
204
205     +------------------------+-------+------+---------+------+
206     |                        | false | auto | nostash | true |
207     +========================+=======+======+=========+======+
208     | Index cleartext using  |       |  X   |    X    |  X   |
209     | stashed session keys   |       |      |         |      |
210     +------------------------+-------+------+---------+------+
211     | Index cleartext        |       |      |    X    |  X   |
212     | using secret keys      |       |      |         |      |
213     +------------------------+-------+------+---------+------+
214     | Stash session keys     |       |      |         |  X   |
215     +------------------------+-------+------+---------+------+
216     | Delete stashed session |   X   |      |         |      |
217     | keys on reindex        |       |      |         |      |
218     +------------------------+-------+------+---------+------+
219
220     Stashed session keys are kept in the database as properties
221     associated with the message.  See ``session-key`` in
222     :any:`notmuch-properties(7)` for more details about how they can be
223     useful.
224
225     Be aware that the notmuch index is likely sufficient (and a
226     stashed session key is certainly sufficient) to reconstruct the
227     cleartext of the message itself, so please ensure that the notmuch
228     message index is adequately protected.  DO NOT USE
229     ``index.decrypt=true`` or ``index.decrypt=nostash`` without
230     considering the security of your index.
231
232     Default: ``auto``.
233
234 **index.header.<prefix>**
235     Define the query prefix <prefix>, based on a mail header. For
236     example ``index.header.List=List-Id`` will add a probabilistic
237     prefix ``List:`` that searches the ``List-Id`` field.  User
238     defined prefixes must not start with 'a'...'z'; in particular
239     adding a prefix with same name as a predefined prefix is not
240     supported. See :any:`notmuch-search-terms(7)` for a list of existing
241     prefixes, and an explanation of probabilistic prefixes.
242
243 **built_with.<name>**
244     Compile time feature <name>. Current possibilities include
245     "retry_lock" (configure option, included by default).
246     (since notmuch 0.30, "compact" and "field_processor" are
247     always included.)
248
249 **query.<name>**
250     Expansion for named query called <name>. See
251     :any:`notmuch-search-terms(7)` for more information about named
252     queries.
253
254 **squery.<name>**
255     Expansion for named query called <name>, using s-expression syntax. See
256     :any:`notmuch-sexp-queries(7)` for more information about s-expression
257     queries.
258
259 FILES
260 =====
261
262 CONFIGURATION
263 -------------
264
265 Notmuch configuration file search order:
266
267 1. File specified by :option:`notmuch --config` global option; see
268    :any:`notmuch(1)`.
269
270 2. File specified by :envvar:`NOTMUCH_CONFIG` environment variable.
271
272 3. ``$XDG_CONFIG_HOME/notmuch/<profile>/config`` where ``<profile>``
273    is defined by :envvar:`NOTMUCH_PROFILE` environment variable if
274    set, ``$XDG_CONFIG_HOME/notmuch/default/config`` otherwise.
275
276 4. ``$HOME/.notmuch-config.<profile>`` where ``<profile>`` is defined
277    by :envvar:`NOTMUCH_PROFILE` environment variable if set,
278    ``$HOME/.notmuch-config`` otherwise.
279
280 .. _database:
281
282 DATABASE LOCATION
283 -----------------
284
285 Notmuch database search order:
286
287 1. Directory specified by :envvar:`NOTMUCH_DATABASE` environment variable.
288
289 2. Directory specified by config key ``database.path``.
290
291 3. ``$XDG_DATA_HOME/notmuch/<profile>`` where ``<profile>``
292    is defined by :envvar:`NOTMUCH_PROFILE` environment variable if
293    set, ``$XDG_DATA_HOME/notmuch/default`` otherwise.
294
295 4. Directory specified by :envvar:`MAILDIR` environment variable.
296
297 5. ``$HOME/mail``
298
299 HOOKS
300 -----
301
302 Notmuch hook directory search order:
303
304 1. Directory specified by ``database.hook_dir`` configuration option.
305
306 2. ``$XDG_CONFIG_HOME/notmuch/<profile>/hooks`` where ``<profile>``
307    is defined by :envvar:`NOTMUCH_PROFILE` environment variable if
308    set, ``$XDG_CONFIG_HOME/notmuch/default/hooks`` otherwise.
309
310 3. ``<database.path>/.notmuch/hooks``
311
312 SEE ALSO
313 ========
314
315 :any:`notmuch(1)`,
316 :any:`notmuch-count(1)`,
317 :any:`notmuch-dump(1)`,
318 :any:`notmuch-hooks(5)`,
319 :any:`notmuch-insert(1)`,
320 :any:`notmuch-new(1)`,
321 :any:`notmuch-properties(7)`,
322 :any:`notmuch-reply(1)`,
323 :any:`notmuch-restore(1)`,
324 :any:`notmuch-search(1)`,
325 :any:`notmuch-search-terms(7)`,
326 :any:`notmuch-show(1)`,
327 :any:`notmuch-tag(1)`