git.cworth.org Git - notmuch-wiki/blob - 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> [--database] &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        <b>get</b>    The value of the specified configuration item is printed to std‐
  23               out.  If the item has multiple values (it is a list), each value
  24               is separated by a newline character.
  25
  26        <b>set</b>    The specified configuration item is set to the given  value.  To
  27               specify  a multiple-value item (a list), provide each value as a
  28               separate command-line argument.
  29
  30               If no values are provided, the specified configuration item will
  31               be removed from the configuration file.
  32
  33               With  the  <u>--database</u>  option,  updates  configuration  metadata
  34               stored in the database, rather than the default (text)  configu‐
  35               ration 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.  Non-absolute
  47        paths are presumed relative to <u>$HOME</u> for items in section <b>database</b>.
  48
  49        <b>database.path</b>
  50               Notmuch  will  store  its database here, (in sub-directory named
  51               <b>.notmuch</b> if <b>database.mail</b>_<b>root</b> is unset).
  52
  53               Default: see <u>DATABASE</u> <u>LOCATION</u>
  54
  55        <b>database.mail</b>_<b>root</b>
  56               The top-level directory where your mail currently exists and  to
  57               where  mail will be delivered in the future. Files should be in‐
  58               dividual email messages.
  59
  60               History: this configuration  value  was  introduced  in  notmuch
  61               0.32.
  62
  63               Default:  For compatibility with older configurations, the value
  64               of database.path is used if <b>database.mail</b>_<b>root</b> is unset.
  65
  66        <b>database.backup</b>_<b>dir</b>
  67               Directory to store tag dumps when upgrading database.
  68
  69               History: this configuration  value  was  introduced  in  notmuch
  70               0.32.
  71
  72               Default: A sibling directory of the Xapian database called <u>back‐</u>
  73               <u>ups</u>.
  74
  75        <b>database.hook</b>_<b>dir</b>
  76               Directory containing hooks run by  notmuch  commands.  See  <a href='../notmuch-hooks-5/'>not‐</a>
  77               <a href='../notmuch-hooks-5/'>much-hooks</a>(5).
  78
  79               History:  this  configuration  value  was  introduced in notmuch
  80               0.32.
  81
  82               Default: See HOOKS, below.
  83
  84        <b>database.autocommit</b>
  85           How often to commit transactions to disk. <u>0</u> means wait until command
  86           completes,  otherwise an integer <u>n</u> specifies to commit to disk after
  87           every <u>n</u> completed transactions.
  88
  89           History: this configuration value was introduced in notmuch 0.33.
  90
  91        <b>user.name</b>
  92               Your full name.
  93
  94               Default: <b>$NAME</b> variable if set, otherwise read from <b>/etc/passwd</b>.
  95
  96        <b>user.primary</b>_<b>email</b>
  97               Your primary email address.
  98
  99               Default: <b>$EMAIL</b> variable if set, otherwise constructed from  the
 100               username and hostname of the current machine.
 101
 102        <b>user.other</b>_<b>email</b>
 103               A list of other email addresses at which you receive email.
 104
 105               Default: not set.
 106
 107        <b>new.tags</b>
 108               A  list  of tags that will be added to all messages incorporated
 109               by <b>notmuch</b> <b>new</b>.
 110
 111               Default: <b>unread;inbox</b>.
 112
 113        <b>new.ignore</b>
 114               A list to  specify  files  and  directories  that  will  not  be
 115               searched  for messages by <a href='../notmuch-new-1/'>notmuch-new</a>(1). Each entry in the list
 116               is either:
 117
 118               A file or a directory name, without path, that will be  ignored,
 119               regardless  of  the location in the mail store directory hierar‐
 120               chy.
 121
 122               Or:
 123
 124               A regular expression delimited with  //  that  will  be  matched
 125               against  the path of the file or directory relative to the data‐
 126               base path. Matching files and directories will be  ignored.  The
 127               beginning and end of string must be explicitly anchored. For ex‐
 128               ample, /.*/foo$/ would match &quot;bar/foo&quot;  and  &quot;bar/baz/foo&quot;,  but
 129               not &quot;foo&quot; or &quot;bar/foobar&quot;.
 130
 131               Default: empty list.
 132
 133        <b>search.exclude</b>_<b>tags</b>
 134               A  list of tags that will be excluded from search results by de‐
 135               fault. Using an excluded tag in a query will override  that  ex‐
 136               clusion.
 137
 138               Default:   empty   list.   Note   that   <b>notmuch-setup</b>(1)   puts
 139               <b>deleted;spam</b> here when creating new configuration file.
 140
 141        <b>show.extra_headers</b>
 142           By default <a href='../notmuch-show-1/'>notmuch-show</a>(1) includes the following headers in  struc‐
 143           tured  output if they are present in the message: <u>Subject</u>, <u>From</u>, <u>To</u>,
 144           <u>Cc</u>, <u>Bcc</u>, <u>Reply-To</u>, <u>Date</u>. This option allows the specification  of  a
 145           list of further headers to output.
 146
 147           History: This configuration value was introduced in notmuch 0.35.
 148
 149           Default: empty list.
 150
 151        <b>maildir.synchronize</b>_<b>flags</b>
 152               If true, then the following maildir flags (in message filenames)
 153               will be synchronized with the corresponding notmuch tags:
 154
 155                             ┌─────┬────────────────────────────┐
 156                             │Flag │ Tag                        │
 157                             ├─────┼────────────────────────────┤
 158                             │D    │ draft                      │
 159                             ├─────┼────────────────────────────┤
 160                             │F    │ flagged                    │
 161                             ├─────┼────────────────────────────┤
 162                             │P    │ passed                     │
 163                             ├─────┼────────────────────────────┤
 164                             │R    │ replied                    │
 165                             ├─────┼────────────────────────────┤
 166                             │S    │ unread  (added  when   &apos;S&apos; │
 167                             │     │ flag is not present)       │
 168                             └─────┴────────────────────────────┘
 169
 170               The <a href='../notmuch-new-1/'>notmuch-new</a>(1) command will notice flag changes in filenames
 171               and update tags, while the <a href='../notmuch-tag-1/'>notmuch-tag</a>(1) and <a href='../notmuch-restore-1/'>notmuch-restore</a>(1)
 172               commands will notice tag changes and update flags in filenames.
 173
 174               If  there  have  been  any  changes in the maildir (new messages
 175               added, old ones  removed  or  renamed,  maildir  flags  changed,
 176               etc.),  it  is  advisable  to  run  <a href='../notmuch-new-1/'>notmuch-new</a>(1)  before  <a href='../notmuch-tag-1/'>not‐</a>
 177               <a href='../notmuch-tag-1/'>much-tag</a>(1) or <a href='../notmuch-restore-1/'>notmuch-restore</a>(1) commands  to  ensure  the  tag
 178               changes  are  properly synchronized to the maildir flags, as the
 179               commands expect the database and maildir to be in sync.
 180
 181               Default: <b>true</b>.
 182
 183        <b>index.decrypt</b>
 184               Policy for decrypting encrypted messages during indexing.   Must
 185               be one of: <b>false</b>, <b>auto</b>, <b>nostash</b>, or <b>true</b>.
 186
 187               When  indexing  an encrypted e-mail message, if this variable is
 188               set to <b>true</b>, notmuch will try to decrypt the message  and  index
 189               the  cleartext,  stashing  a copy of any discovered session keys
 190               for the message.  If <b>auto</b>, it will try to index the cleartext if
 191               a  stashed  session  key  is already known for the message (e.g.
 192               from a previous copy), but will not try to  access  your  secret
 193               keys.  Use <b>false</b> to avoid decrypting even when a stashed session
 194               key is already present.
 195
 196               <b>nostash</b> is the same as  <b>true</b>  except  that  it  will  not  stash
 197               newly-discovered session keys in the database.
 198
 199               From  the  command line (i.e. during <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-insert-1/'>notmuch-in‐</a>
 200               <a href='../notmuch-insert-1/'>sert</a>(1), or <a href='../notmuch-reindex-1/'>notmuch-reindex</a>(1)), the user can override the data‐
 201               base&apos;s stored decryption policy with the <b>--decrypt=</b> option.
 202
 203               Here  is  a  table  that summarizes the functionality of each of
 204               these policies:
 205
 206                       ┌──────────────┬───────┬──────┬─────────┬──────┐
 207                       │              │ false │ auto │ nostash │ true │
 208                       ├──────────────┼───────┼──────┼─────────┼──────┤
 209                       │Index cleart‐ │       │ X    │ X       │ X    │
 210                       │ext     using │       │      │         │      │
 211                       │stashed  ses‐ │       │      │         │      │
 212                       │sion keys     │       │      │         │      │
 213                       ├──────────────┼───────┼──────┼─────────┼──────┤
 214                       │Index cleart‐ │       │      │ X       │ X    │
 215                       │ext using se‐ │       │      │         │      │
 216                       │cret keys     │       │      │         │      │
 217                       ├──────────────┼───────┼──────┼─────────┼──────┤
 218                       │Stash session │       │      │         │ X    │
 219                       │keys
 220                       ├──────────────┼───────┼──────┼─────────┼──────┤
 221                       │Delete
 222                       │stashed  ses‐ │       │      │         │      │
 223                       │sion keys  on │       │      │         │      │
 224                       │reindex       │       │      │         │      │
 225                       └──────────────┴───────┴──────┴─────────┴──────┘
 226
 227               Stashed  session keys are kept in the database as properties as‐
 228               sociated with the message.  See <b>session-key</b>  in  <a href='../notmuch-properties-7/'>notmuch-proper‐</a>
 229               <a href='../notmuch-properties-7/'>ties</a>(7) for more details about how they can be useful.
 230
 231               Be  aware  that  the  notmuch  index is likely sufficient (and a
 232               stashed session key is certainly sufficient) to reconstruct  the
 233               cleartext  of the message itself, so please ensure that the not‐
 234               much message index is adequately  protected.   DO  NOT  USE  <b>in-</b>
 235               <b>dex.decrypt=true</b>  or  <b>index.decrypt=nostash</b>  without considering
 236               the security of your index.
 237
 238               Default: <b>auto</b>.
 239
 240        <b>index.header.&lt;prefix&gt;</b>
 241               Define the query prefix &lt;prefix&gt;, based on a  mail  header.  For
 242               example  <b>index.header.List=List-Id</b> will add a probabilistic pre‐
 243               fix <b>List:</b> that searches the <b>List-Id</b> field.   User  defined  pre‐
 244               fixes must not start with &apos;a&apos;...&apos;z&apos;; in particular adding a pre‐
 245               fix with same name as a predefined prefix is not supported.  See
 246               <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7)  for a list of existing prefixes, and an
 247               explanation of probabilistic prefixes.
 248
 249        <b>built</b>_<b>with.&lt;name&gt;</b>
 250               Compile  time  feature  &lt;name&gt;.  Current  possibilities  include
 251               &quot;retry_lock&quot;  (configure  option,  included by default).  (since
 252               notmuch 0.30, &quot;compact&quot; and  &quot;field_processor&quot;  are  always  in‐
 253               cluded.)
 254
 255        <b>query.&lt;name&gt;</b>
 256               Expansion    for   named   query   called   &lt;name&gt;.   See   <a href='../notmuch-search-terms-7/'>not‐</a>
 257               <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7) for more information about named queries.
 258
 259        <b>squery.&lt;name&gt;</b>
 260               Expansion for named query called &lt;name&gt;, using s-expression syn‐
 261               tax.  See  <a href='../notmuch-sexp-queries-7/'>notmuch-sexp-queries</a>(7)  for  more  information about
 262               s-expression queries.
 263 </pre>
 264
 265 <h2>FILES</h2>
 266
 267 <h3> &nbsp; CONFIGURATION</h3>
 268 <pre>
 269        Notmuch configuration file search order:
 270
 271        1. File specified by <b>notmuch</b> <b>--config</b> global option; see <a href='../notmuch-1/'>notmuch</a>(1).
 272
 273        2. File specified by <b>NOTMUCH</b>_<b>CONFIG</b> environment variable.
 274
 275        3. <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/&lt;profile&gt;/config</b> where <b>&lt;profile&gt;</b> is defined
 276           by   <b>NOTMUCH</b>_<b>PROFILE</b>   environment   variable   if   set,  <b>$XDG</b>_<b>CON-</b>
 277           <b>FIG</b>_<b>HOME/notmuch/default/config</b> otherwise.
 278
 279        4. <b>$HOME/.notmuch-config.&lt;profile&gt;</b> where <b>&lt;profile&gt;</b> is defined  by  <b>NOT-</b>
 280           <b>MUCH</b>_<b>PROFILE</b> environment variable if set, <b>$HOME/.notmuch-config</b> oth‐
 281           erwise.
 282 </pre>
 283
 284 <h3> &nbsp; DATABASE LOCATION</h3>
 285 <pre>
 286        Notmuch database search order:
 287
 288        1. Directory specified by <b>NOTMUCH</b>_<b>DATABASE</b> environment variable.
 289
 290        2. Directory specified by config key <b>database.path</b>.
 291
 292        3. <b>$XDG</b>_<b>DATA</b>_<b>HOME/notmuch/&lt;profile&gt;</b> where <b>&lt;profile&gt;</b> is defined by  <b>NOT-</b>
 293           <b>MUCH</b>_<b>PROFILE</b> environment variable if set, <b>$XDG</b>_<b>DATA</b>_<b>HOME/notmuch/de-</b>
 294           <b>fault</b> otherwise.
 295
 296        4. Directory specified by <b>MAILDIR</b> environment variable.
 297
 298        5. <b>$HOME/mail</b>
 299 </pre>
 300
 301 <h3> &nbsp; HOOKS</h3>
 302 <pre>
 303        Notmuch hook directory search order:
 304
 305        1. Directory specified by <b>database.hook</b>_<b>dir</b> configuration option.
 306
 307        2. <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/&lt;profile&gt;/hooks</b> where <b>&lt;profile&gt;</b> is  defined
 308           by   <b>NOTMUCH</b>_<b>PROFILE</b>   environment   variable   if   set,  <b>$XDG</b>_<b>CON-</b>
 309           <b>FIG</b>_<b>HOME/notmuch/default/hooks</b> otherwise.
 310
 311        3. <b>&lt;database.path&gt;/.notmuch/hooks</b>
 312 </pre>
 313
 314 <h2>SEE ALSO</h2>
 315 <pre>
 316        <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>
 317        <a href='../notmuch-insert-1/'>much-insert</a>(1),   <a href='../notmuch-new-1/'>notmuch-new</a>(1),   <a href='../notmuch-properties-7/'>notmuch-properties</a>(7),  <a href='../notmuch-reply-1/'>notmuch-re‐</a>
 318        <a href='../notmuch-reply-1/'>ply</a>(1), <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7),
 319        <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
 320 </pre>
 321
 322 <h2>AUTHOR</h2>
 323 <pre>
 324        Carl Worth and many others
 325 </pre>
 326
 327 <h2>COPYRIGHT</h2>
 328 <pre>
 329        2009-2022, Carl Worth and many others
 330 </pre>
 331
 332 <h2>0.35</h2>