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>maildir.synchronize</b>_<b>flags</b>
 142               If true, then the following maildir flags (in message filenames)
 143               will be synchronized with the corresponding notmuch tags:
 144
 145                             ┌─────┬────────────────────────────┐
 146                             │Flag │ Tag                        │
 147                             ├─────┼────────────────────────────┤
 148                             │D    │ draft                      │
 149                             ├─────┼────────────────────────────┤
 150                             │F    │ flagged                    │
 151                             ├─────┼────────────────────────────┤
 152                             │P    │ passed                     │
 153                             ├─────┼────────────────────────────┤
 154                             │R    │ replied                    │
 155                             ├─────┼────────────────────────────┤
 156                             │S    │ unread   (added  when  &apos;S&apos; │
 157                             │     │ flag is not present)       │
 158                             └─────┴────────────────────────────┘
 159
 160               The <a href='../notmuch-new-1/'>notmuch-new</a>(1) command will notice flag changes in filenames
 161               and update tags, while the <a href='../notmuch-tag-1/'>notmuch-tag</a>(1) and <a href='../notmuch-restore-1/'>notmuch-restore</a>(1)
 162               commands will notice tag changes and update flags in filenames.
 163
 164               If there have been any changes  in  the  maildir  (new  messages
 165               added,  old  ones  removed  or  renamed,  maildir flags changed,
 166               etc.),  it  is  advisable  to  run  <a href='../notmuch-new-1/'>notmuch-new</a>(1)  before  <a href='../notmuch-tag-1/'>not‐</a>
 167               <a href='../notmuch-tag-1/'>much-tag</a>(1)  or  <a href='../notmuch-restore-1/'>notmuch-restore</a>(1)  commands  to ensure the tag
 168               changes are properly synchronized to the maildir flags,  as  the
 169               commands expect the database and maildir to be in sync.
 170
 171               Default: <b>true</b>.
 172
 173        <b>index.decrypt</b>
 174               Policy  for decrypting encrypted messages during indexing.  Must
 175               be one of: <b>false</b>, <b>auto</b>, <b>nostash</b>, or <b>true</b>.
 176
 177               When indexing an encrypted e-mail message, if this  variable  is
 178               set  to  <b>true</b>, notmuch will try to decrypt the message and index
 179               the cleartext, stashing a copy of any  discovered  session  keys
 180               for the message.  If <b>auto</b>, it will try to index the cleartext if
 181               a stashed session key is already known  for  the  message  (e.g.
 182               from  a  previous  copy), but will not try to access your secret
 183               keys.  Use <b>false</b> to avoid decrypting even when a stashed session
 184               key is already present.
 185
 186               <b>nostash</b>  is  the  same  as  <b>true</b>  except  that it will not stash
 187               newly-discovered session keys in the database.
 188
 189               From the command line (i.e. during  <a href='../notmuch-new-1/'>notmuch-new</a>(1),  <a href='../notmuch-insert-1/'>notmuch-in‐</a>
 190               <a href='../notmuch-insert-1/'>sert</a>(1), or <a href='../notmuch-reindex-1/'>notmuch-reindex</a>(1)), the user can override the data‐
 191               base&apos;s stored decryption policy with the <b>--decrypt=</b> option.
 192
 193               Here is a table that summarizes the  functionality  of  each  of
 194               these policies:
 195
 196                       ┌──────────────┬───────┬──────┬─────────┬──────┐
 197                       │              │ false │ auto │ nostash │ true │
 198                       └──────────────┴───────┴──────┴─────────┴──────┘
 199
 200                       │Index cleart‐ │       │ X    │ X       │ X    │
 201                       │ext     using │       │      │         │      │
 202                       │stashed  ses‐ │       │      │         │      │
 203                       │sion keys     │       │      │         │      │
 204                       ├──────────────┼───────┼──────┼─────────┼──────┤
 205                       │Index cleart‐ │       │      │ X       │ X    │
 206                       │ext using se‐ │       │      │         │      │
 207                       │cret keys     │       │      │         │      │
 208                       ├──────────────┼───────┼──────┼─────────┼──────┤
 209                       │Stash session │       │      │         │ X    │
 210                       │keys
 211                       ├──────────────┼───────┼──────┼─────────┼──────┤
 212                       │Delete
 213                       │stashed  ses‐ │       │      │         │      │
 214                       │sion  keys on │       │      │         │      │
 215                       │reindex       │       │      │         │      │
 216                       └──────────────┴───────┴──────┴─────────┴──────┘
 217
 218               Stashed session keys are kept in the database as properties  as‐
 219               sociated  with  the message.  See <b>session-key</b> in <a href='../notmuch-properties-7/'>notmuch-proper‐</a>
 220               <a href='../notmuch-properties-7/'>ties</a>(7) for more details about how they can be useful.
 221
 222               Be aware that the notmuch index  is  likely  sufficient  (and  a
 223               stashed  session key is certainly sufficient) to reconstruct the
 224               cleartext of the message itself, so please ensure that the  not‐
 225               much  message  index  is  adequately  protected.  DO NOT USE <b>in-</b>
 226               <b>dex.decrypt=true</b> or  <b>index.decrypt=nostash</b>  without  considering
 227               the security of your index.
 228
 229               Default: <b>auto</b>.
 230
 231        <b>index.header.&lt;prefix&gt;</b>
 232               Define  the  query  prefix &lt;prefix&gt;, based on a mail header. For
 233               example <b>index.header.List=List-Id</b> will add a probabilistic  pre‐
 234               fix  <b>List:</b>  that  searches the <b>List-Id</b> field.  User defined pre‐
 235               fixes must not start with &apos;a&apos;...&apos;z&apos;; in particular adding a pre‐
 236               fix  with same name as a predefined prefix is not supported. See
 237               <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for a list of existing prefixes, and  an
 238               explanation of probabilistic prefixes.
 239
 240        <b>built</b>_<b>with.&lt;name&gt;</b>
 241               Compile  time  feature  &lt;name&gt;.  Current  possibilities  include
 242               &quot;retry_lock&quot; (configure option, included  by  default).   (since
 243               notmuch  0.30,  &quot;compact&quot;  and  &quot;field_processor&quot; are always in‐
 244               cluded.)
 245
 246        <b>query.&lt;name&gt;</b>
 247               Expansion   for   named   query   called   &lt;name&gt;.   See    <a href='../notmuch-search-terms-7/'>not‐</a>
 248               <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7) for more information about named queries.
 249 </pre>
 250
 251 <h2>FILES</h2>
 252
 253 <h3> &nbsp; CONFIGURATION</h3>
 254 <pre>
 255        Notmuch configuration file search order:
 256
 257        1. File specified by <b>notmuch</b> <b>--config</b> global option; see <a href='../notmuch-1/'>notmuch</a>(1).
 258
 259        2. File specified by <b>NOTMUCH</b>_<b>CONFIG</b> environment variable.
 260
 261        3. <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/&lt;profile&gt;/config</b> where <b>&lt;profile&gt;</b> is defined
 262           by  <b>NOTMUCH</b>_<b>PROFILE</b>   environment   variable   if   set,   <b>$XDG</b>_<b>CON-</b>
 263           <b>FIG</b>_<b>HOME/notmuch/default/config</b> otherwise.
 264
 265        4. <b>$HOME/.notmuch-config.&lt;profile&gt;</b>  where  <b>&lt;profile&gt;</b> is defined by <b>NOT-</b>
 266           <b>MUCH</b>_<b>PROFILE</b> environment variable if set, <b>$HOME/.notmuch-config</b> oth‐
 267           erwise.
 268 </pre>
 269
 270 <h3> &nbsp; DATABASE LOCATION</h3>
 271 <pre>
 272        Notmuch database search order:
 273
 274        1. Directory specified by <b>NOTMUCH</b>_<b>DATABASE</b> environment variable.
 275
 276        2. Directory specified by config key <b>database.path</b>.
 277
 278        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>
 279           <b>MUCH</b>_<b>PROFILE</b> environment variable if set, <b>$XDG</b>_<b>DATA</b>_<b>HOME/notmuch/de-</b>
 280           <b>fault</b> otherwise.
 281
 282        4. Directory specified by <b>MAILDIR</b> environment variable.
 283
 284        5. <b>$HOME/mail</b>
 285 </pre>
 286
 287 <h3> &nbsp; HOOKS</h3>
 288 <pre>
 289        Notmuch hook directory search order:
 290
 291        1. Directory specified by <b>database.hook</b>_<b>dir</b> configuration option.
 292
 293        2. <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/&lt;profile&gt;/hooks</b>  where <b>&lt;profile&gt;</b> is defined
 294           by  <b>NOTMUCH</b>_<b>PROFILE</b>   environment   variable   if   set,   <b>$XDG</b>_<b>CON-</b>
 295           <b>FIG</b>_<b>HOME/notmuch/default/hooks</b> otherwise.
 296
 297        3. <b>&lt;database.path&gt;/.notmuch/hooks</b>
 298 </pre>
 299
 300 <h2>SEE ALSO</h2>
 301 <pre>
 302        <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>
 303        <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>
 304        <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),
 305        <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
 306 </pre>
 307
 308 <h2>AUTHOR</h2>
 309 <pre>
 310        Carl Worth and many others
 311 </pre>
 312
 313 <h2>COPYRIGHT</h2>
 314 <pre>
 315        2009-2021, Carl Worth and many others
 316 </pre>
 317
 318 <h2>0.33</h2>