]> git.cworth.org Git - notmuch-wiki/blob - manpages/notmuch-config-1.mdwn
news for release 0.29.2
[notmuch-wiki] / manpages / notmuch-config-1.mdwn
1 <h1>NOTMUCH-CONFIG(1)</h1>
2
3 <h2>NAME</h2>
4 <pre>
5        notmuch-config - access notmuch configuration file
6 </pre>
7
8 <h2>SYNOPSIS</h2>
9 <pre>
10        <b>notmuch</b> <b>config</b> <b>get</b> &lt;<u>section</u>&gt;.&lt;<u>item</u>&gt;
11
12        <b>notmuch</b> <b>config</b> <b>set</b> &lt;<u>section</u>&gt;.&lt;<u>item</u>&gt; [<u>value</u> ...]
13
14        <b>notmuch</b> <b>config</b> <b>list</b>
15 </pre>
16
17 <h2>DESCRIPTION</h2>
18 <pre>
19        The  <b>config</b>  command  can be used to get or set settings in the notmuch
20        configuration file and corresponding database.
21
22        Items marked <b>[STORED</b> <b>IN</b> <b>DATABASE]</b>  are  only  in  the  database.   They
23        should  not be placed in the configuration file, and should be accessed
24        programmatically as described in the SYNOPSIS above.
25
26        <b>get</b>    The value of the specified configuration item is printed to std‐
27               out.  If the item has multiple values (it is a list), each value
28               is separated by a newline character.
29
30        <b>set</b>    The specified configuration item is set to the given  value.  To
31               specify  a multiple-value item (a list), provide each value as a
32               separate command-line argument.
33
34               If no values are provided, the specified configuration item will
35               be removed from the configuration file.
36
37        <b>list</b>   Every  configuration  item is printed to stdout, each on a sepa‐
38               rate line of the form:
39
40                  *section*.\ *item*\ =\ *value*
41
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.
45
46        The available configuration items are described below.
47
48        <b>database.path</b>
49               The top-level directory where your mail currently exists and  to
50               where  mail  will  be  delivered  in the future. Files should be
51               individual email  messages.  Notmuch  will  store  its  database
52               within  a  sub-directory of the path configured here named <b>.not-</b>
53               <b>much</b>.
54
55               Default: <b>$MAILDIR</b> variable if set, otherwise <b>$HOME/mail</b>.
56
57        <b>user.name</b>
58               Your full name.
59
60               Default: <b>$NAME</b> variable if set, otherwise read from <b>/etc/passwd</b>.
61
62        <b>user.primary</b>_<b>email</b>
63               Your primary email address.
64
65               Default: <b>$EMAIL</b> variable if set, otherwise constructed from  the
66               username and hostname of the current machine.
67
68        <b>user.other</b>_<b>email</b>
69               A list of other email addresses at which you receive email.
70
71               Default: not set.
72
73        <b>new.tags</b>
74               A  list  of tags that will be added to all messages incorporated
75               by <b>notmuch</b> <b>new</b>.
76
77               Default: <b>unread;inbox</b>.
78
79        <b>new.ignore</b>
80               A list to  specify  files  and  directories  that  will  not  be
81               searched  for messages by <b>notmuch</b> <b>new</b>. Each entry in the list is
82               either:
83
84               A file or a directory name, without path, that will be  ignored,
85               regardless  of  the location in the mail store directory hierar‐
86               chy.
87
88               Or:
89
90               A regular expression delimited with  //  that  will  be  matched
91               against  the path of the file or directory relative to the data‐
92               base path. Matching files and directories will be  ignored.  The
93               beginning  and  end  of  string must be explicitly anchored. For
94               example, /.*/foo$/ would match &quot;bar/foo&quot; and &quot;bar/baz/foo&quot;,  but
95               not &quot;foo&quot; or &quot;bar/foobar&quot;.
96
97               Default: empty list.
98
99        <b>search.exclude</b>_<b>tags</b>
100               A  list  of  tags  that  will be excluded from search results by
101               default. Using an excluded tag in a  query  will  override  that
102               exclusion.
103
104               Default:   empty   list.   Note   that   <b>notmuch-setup</b>(1)   puts
105               <b>deleted;spam</b> here when creating new configuration file.
106
107        <b>maildir.synchronize</b>_<b>flags</b>
108               If true, then the following maildir flags (in message filenames)
109               will be synchronized with the corresponding notmuch tags:
110
111                             ┌─────┬────────────────────────────┐
112                             │Flag │ Tag                        │
113                             ├─────┼────────────────────────────┤
114                             │D    │ draft                      │
115                             ├─────┼────────────────────────────┤
116                             │F    │ flagged                    │
117                             ├─────┼────────────────────────────┤
118                             │P    │ passed                     │
119                             ├─────┼────────────────────────────┤
120                             │R    │ replied                    │
121                             ├─────┼────────────────────────────┤
122                             │S    │ unread   (added  when  &apos;S&apos; │
123                             │     │ flag is not present)       │
124                             └─────┴────────────────────────────┘
125
126               The <b>notmuch</b> <b>new</b> command will notice flag  changes  in  filenames
127               and  update tags, while the <b>notmuch</b> <b>tag</b> and <b>notmuch</b> <b>restore</b> com‐
128               mands will notice tag changes and update flags in filenames.
129
130               If there have been any changes  in  the  maildir  (new  messages
131               added,  old  ones  removed  or  renamed,  maildir flags changed,
132               etc.), it is advisable to run <b>notmuch</b> <b>new</b> before <b>notmuch</b> <b>tag</b>  or
133               <b>notmuch</b>  <b>restore</b> commands to ensure the tag changes are properly
134               synchronized to the maildir flags, as the  commands  expect  the
135               database and maildir to be in sync.
136
137               Default: <b>true</b>.
138
139        <b>crypto.gpg</b>_<b>path</b>
140               Name  (or  full  path)  of gpg binary to use in verification and
141               decryption of PGP/MIME messages.  NOTE: This configuration  item
142               is  deprecated,  and will be ignored if notmuch is built against
143               GMime 3.0 or later.
144
145               Default: <b>gpg</b>.
146
147        <b>index.decrypt</b> <b>[STORED</b> <b>IN</b> <b>DATABASE]</b>
148               Policy for decrypting encrypted messages during indexing.   Must
149               be one of: <b>false</b>, <b>auto</b>, <b>nostash</b>, or <b>true</b>.
150
151               When  indexing  an encrypted e-mail message, if this variable is
152               set to <b>true</b>, notmuch will try to decrypt the message  and  index
153               the  cleartext,  stashing  a copy of any discovered session keys
154               for the message.  If <b>auto</b>, it will try to index the cleartext if
155               a  stashed  session  key  is already known for the message (e.g.
156               from a previous copy), but will not try to  access  your  secret
157               keys.  Use <b>false</b> to avoid decrypting even when a stashed session
158               key is already present.
159
160               <b>nostash</b> is the same as  <b>true</b>  except  that  it  will  not  stash
161               newly-discovered session keys in the database.
162
163               From   the   command  line  (i.e.  during  <a href='../notmuch-new-1/'>notmuch-new</a>(1),  <a href='../notmuch-insert-1/'>not‐</a>
164               <a href='../notmuch-insert-1/'>much-insert</a>(1), or <a href='../notmuch-reindex-1/'>notmuch-reindex</a>(1)), the  user  can  override
165               the  database&apos;s  stored  decryption  policy  with the <b>--decrypt=</b>
166               option.
167
168               Here is a table that summarizes the  functionality  of  each  of
169               these policies:
170
171                       ┌──────────────┬───────┬──────┬─────────┬──────┐
172                       │              │ false │ auto │ nostash │ true │
173                       ├──────────────┼───────┼──────┼─────────┼──────┤
174                       │Index cleart‐ │       │ X    │ X       │ X    │
175                       │ext     using │       │      │         │      │
176                       │stashed  ses‐ │       │      │         │      │
177                       │sion keys     │       │      │         │      │
178                       ├──────────────┼───────┼──────┼─────────┼──────┤
179                       │Index cleart‐ │       │      │ X       │ X    │
180                       │ext     using │       │      │         │      │
181                       │secret keys   │       │      │         │      │
182                       ├──────────────┼───────┼──────┼─────────┼──────┤
183                       │Stash session │       │      │         │ X    │
184                       │keys
185                       ├──────────────┼───────┼──────┼─────────┼──────┤
186                       │Delete
187                       │stashed  ses‐ │       │      │         │      │
188                       │sion  keys on │       │      │         │      │
189                       │reindex       │       │      │         │      │
190                       └──────────────┴───────┴──────┴─────────┴──────┘
191
192               Stashed session keys are kept  in  the  database  as  properties
193               associated with the message.  See <b>session-key</b> in <a href='../notmuch-properties-7/'>notmuch-proper‐</a>
194               <a href='../notmuch-properties-7/'>ties</a>(7) for more details about how they can be useful.
195
196               Be aware that the notmuch index  is  likely  sufficient  (and  a
197               stashed  session key is certainly sufficient) to reconstruct the
198               cleartext of the message itself, so please ensure that the  not‐
199               much   message  index  is  adequately  protected.   DO  NOT  USE
200               <b>index.decrypt=true</b> or <b>index.decrypt=nostash</b> without  considering
201               the security of your index.
202
203               Default: <b>auto</b>.
204
205        <b>index.header.&lt;prefix&gt;</b> <b>[STORED</b> <b>IN</b> <b>DATABASE]</b>
206               Define  the  query  prefix &lt;prefix&gt;, based on a mail header. For
207               example <b>index.header.List=List-Id</b> will add a probabilistic  pre‐
208               fix  <b>List:</b>  that  searches the <b>List-Id</b> field.  User defined pre‐
209               fixes must not start with &apos;a&apos;...&apos;z&apos;; in particular adding a pre‐
210               fix  with same name as a predefined prefix is not supported. See
211               <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for a list of existing prefixes, and  an
212               explanation of probabilistic prefixes.
213
214        <b>built</b>_<b>with.&lt;name&gt;</b>
215               Compile time feature &lt;name&gt;. Current possibilities include &quot;com‐
216               pact&quot; (see <a href='../notmuch-compact-1/'>notmuch-compact</a>(1)) and &quot;field_processor&quot;  (see  <a href='../notmuch-search-terms-7/'>not‐</a>
217               <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7)).
218
219        <b>query.&lt;name&gt;</b> <b>[STORED</b> <b>IN</b> <b>DATABASE]</b>
220               Expansion    for   named   query   called   &lt;name&gt;.   See   <a href='../notmuch-search-terms-7/'>not‐</a>
221               <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7) for more information about named queries.
222 </pre>
223
224 <h2>ENVIRONMENT</h2>
225 <pre>
226        The following environment variables can be used to control the behavior
227        of notmuch.
228
229        <b>NOTMUCH</b>_<b>CONFIG</b>
230               Specifies  the  location of the notmuch configuration file. Not‐
231               much will use ${HOME}/.notmuch-config if this  variable  is  not
232               set.
233 </pre>
234
235 <h2>SEE ALSO</h2>
236 <pre>
237        <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>
238        <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),
239        <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>
240        <a href='../notmuch-show-1/'>much-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
241 </pre>
242
243 <h2>AUTHOR</h2>
244 <pre>
245        Carl Worth and many others
246 </pre>
247
248 <h2>COPYRIGHT</h2>
249 <pre>
250        2009-2019, Carl Worth and many others
251 </pre>
252
253 <h2>0.29</h2>