git.notmuchmail.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.
  47
  48        <b>database.path</b>
  49               Notmuch will store its database here,  (in  sub-directory  named
  50               <b>.notmuch</b> if <b>database.mail</b>_<b>root</b> is unset).
  51
  52               Default: <b>$MAILDIR</b> variable if set, otherwise <b>$HOME/mail</b>.
  53
  54        <b>database.mail</b>_<b>root</b>
  55               The  top-level directory where your mail currently exists and to
  56               where mail will be delivered in the future. Files should be  in‐
  57               dividual email messages.
  58
  59               History:  this  configuration  value  was  introduced in notmuch
  60               0.32.
  61
  62               Default: For compatibility with older configurations, the  value
  63               of database.path is used if <b>database.mail</b>_<b>root</b> is unset.
  64
  65        <b>database.hook</b>_<b>dir</b>
  66           Directory  containing  hooks  run  by  notmuch  commands.  See  <a href='../notmuch-hooks-5/'>not‐</a>
  67           <a href='../notmuch-hooks-5/'>much-hooks</a>(5).
  68
  69        <b>user.name</b>
  70               Your full name.
  71
  72               Default: <b>$NAME</b> variable if set, otherwise read from <b>/etc/passwd</b>.
  73
  74        <b>user.primary</b>_<b>email</b>
  75               Your primary email address.
  76
  77               Default: <b>$EMAIL</b> variable if set, otherwise constructed from  the
  78               username and hostname of the current machine.
  79
  80        <b>user.other</b>_<b>email</b>
  81               A list of other email addresses at which you receive email.
  82
  83               Default: not set.
  84
  85        <b>new.tags</b>
  86               A  list  of tags that will be added to all messages incorporated
  87               by <b>notmuch</b> <b>new</b>.
  88
  89               Default: <b>unread;inbox</b>.
  90
  91        <b>new.ignore</b>
  92               A list to  specify  files  and  directories  that  will  not  be
  93               searched  for messages by <b>notmuch</b> <b>new</b>. Each entry in the list is
  94               either:
  95
  96               A file or a directory name, without path, that will be  ignored,
  97               regardless  of  the location in the mail store directory hierar‐
  98               chy.
  99
 100               Or:
 101
 102               A regular expression delimited with  //  that  will  be  matched
 103               against  the path of the file or directory relative to the data‐
 104               base path. Matching files and directories will be  ignored.  The
 105               beginning and end of string must be explicitly anchored. For ex‐
 106               ample, /.*/foo$/ would match &quot;bar/foo&quot;  and  &quot;bar/baz/foo&quot;,  but
 107               not &quot;foo&quot; or &quot;bar/foobar&quot;.
 108
 109               Default: empty list.
 110
 111        <b>search.exclude</b>_<b>tags</b>
 112               A  list of tags that will be excluded from search results by de‐
 113               fault. Using an excluded tag in a query will override  that  ex‐
 114               clusion.
 115
 116               Default:   empty   list.   Note   that   <b>notmuch-setup</b>(1)   puts
 117               <b>deleted;spam</b> here when creating new configuration file.
 118
 119        <b>maildir.synchronize</b>_<b>flags</b>
 120               If true, then the following maildir flags (in message filenames)
 121               will be synchronized with the corresponding notmuch tags:
 122
 123                             ┌─────┬────────────────────────────┐
 124                             │Flag │ Tag                        │
 125                             ├─────┼────────────────────────────┤
 126                             │D    │ draft                      │
 127                             ├─────┼────────────────────────────┤
 128                             │F    │ flagged                    │
 129                             ├─────┼────────────────────────────┤
 130                             │P    │ passed                     │
 131                             ├─────┼────────────────────────────┤
 132                             │R    │ replied                    │
 133                             ├─────┼────────────────────────────┤
 134                             │S    │ unread   (added  when  &apos;S&apos; │
 135                             │     │ flag is not present)       │
 136                             └─────┴────────────────────────────┘
 137
 138               The <b>notmuch</b> <b>new</b> command will notice flag  changes  in  filenames
 139               and  update tags, while the <b>notmuch</b> <b>tag</b> and <b>notmuch</b> <b>restore</b> com‐
 140               mands will notice tag changes and update flags in filenames.
 141
 142               If there have been any changes  in  the  maildir  (new  messages
 143               added,  old  ones  removed  or  renamed,  maildir flags changed,
 144               etc.), it is advisable to run <b>notmuch</b> <b>new</b> before <b>notmuch</b> <b>tag</b>  or
 145               <b>notmuch</b>  <b>restore</b> commands to ensure the tag changes are properly
 146               synchronized to the maildir flags, as the  commands  expect  the
 147               database and maildir to be in sync.
 148
 149               Default: <b>true</b>.
 150
 151        <b>index.decrypt</b>
 152               Policy  for decrypting encrypted messages during indexing.  Must
 153               be one of: <b>false</b>, <b>auto</b>, <b>nostash</b>, or <b>true</b>.
 154
 155               When indexing an encrypted e-mail message, if this  variable  is
 156               set  to  <b>true</b>, notmuch will try to decrypt the message and index
 157               the cleartext, stashing a copy of any  discovered  session  keys
 158               for the message.  If <b>auto</b>, it will try to index the cleartext if
 159               a stashed session key is already known  for  the  message  (e.g.
 160               from  a  previous  copy), but will not try to access your secret
 161               keys.  Use <b>false</b> to avoid decrypting even when a stashed session
 162               key is already present.
 163
 164               <b>nostash</b>  is  the  same  as  <b>true</b>  except  that it will not stash
 165               newly-discovered session keys in the database.
 166
 167               From the command line (i.e. during  <a href='../notmuch-new-1/'>notmuch-new</a>(1),  <a href='../notmuch-insert-1/'>notmuch-in‐</a>
 168               <a href='../notmuch-insert-1/'>sert</a>(1), or <a href='../notmuch-reindex-1/'>notmuch-reindex</a>(1)), the user can override the data‐
 169               base&apos;s stored decryption policy with the <b>--decrypt=</b> option.
 170
 171               Here is a table that summarizes the  functionality  of  each  of
 172               these policies:
 173
 174                       ┌──────────────┬───────┬──────┬─────────┬──────┐
 175                       │              │ false │ auto │ nostash │ true │
 176                       ├──────────────┼───────┼──────┼─────────┼──────┤
 177                       │Index cleart‐ │       │ X    │ X       │ X    │
 178                       │ext     using │       │      │         │      │
 179                       │stashed  ses‐ │       │      │         │      │
 180                       │sion keys     │       │      │         │      │
 181                       ├──────────────┼───────┼──────┼─────────┼──────┤
 182                       │Index cleart‐ │       │      │ X       │ X    │
 183                       │ext using se‐ │       │      │         │      │
 184                       │cret keys     │       │      │         │      │
 185                       ├──────────────┼───────┼──────┼─────────┼──────┤
 186                       │Stash session │       │      │         │ X    │
 187                       │keys
 188                       ├──────────────┼───────┼──────┼─────────┼──────┤
 189                       │Delete
 190                       │stashed  ses‐ │       │      │         │      │
 191                       │sion  keys on │       │      │         │      │
 192                       │reindex       │       │      │         │      │
 193                       └──────────────┴───────┴──────┴─────────┴──────┘
 194
 195               Stashed session keys are kept in the database as properties  as‐
 196               sociated  with  the message.  See <b>session-key</b> in <a href='../notmuch-properties-7/'>notmuch-proper‐</a>
 197               <a href='../notmuch-properties-7/'>ties</a>(7) for more details about how they can be useful.
 198
 199               Be aware that the notmuch index  is  likely  sufficient  (and  a
 200               stashed  session key is certainly sufficient) to reconstruct the
 201               cleartext of the message itself, so please ensure that the  not‐
 202               much  message  index  is  adequately  protected.  DO NOT USE <b>in-</b>
 203               <b>dex.decrypt=true</b> or  <b>index.decrypt=nostash</b>  without  considering
 204               the security of your index.
 205
 206               Default: <b>auto</b>.
 207
 208        <b>index.header.&lt;prefix&gt;</b>
 209               Define  the  query  prefix &lt;prefix&gt;, based on a mail header. For
 210               example <b>index.header.List=List-Id</b> will add a probabilistic  pre‐
 211               fix  <b>List:</b>  that  searches the <b>List-Id</b> field.  User defined pre‐
 212               fixes must not start with &apos;a&apos;...&apos;z&apos;; in particular adding a pre‐
 213               fix  with same name as a predefined prefix is not supported. See
 214               <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for a list of existing prefixes, and  an
 215               explanation of probabilistic prefixes.
 216
 217        <b>built</b>_<b>with.&lt;name&gt;</b>
 218               Compile  time  feature  &lt;name&gt;.  Current  possibilities  include
 219               &quot;retry_lock&quot; (configure option, included  by  default).   (since
 220               notmuch  0.30,  &quot;compact&quot;  and  &quot;field_processor&quot; are always in‐
 221               cluded.)
 222
 223        <b>query.&lt;name&gt;</b>
 224               Expansion   for   named   query   called   &lt;name&gt;.   See    <a href='../notmuch-search-terms-7/'>not‐</a>
 225               <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7) for more information about named queries.
 226 </pre>
 227
 228 <h2>ENVIRONMENT</h2>
 229 <pre>
 230        The following environment variables can be used to control the behavior
 231        of notmuch.
 232
 233        <b>NOTMUCH</b>_<b>CONFIG</b>
 234               Specifies the location of the notmuch configuration file.
 235
 236        <b>NOTMUCH</b>_<b>PROFILE</b>
 237               Selects among notmuch configurations.
 238 </pre>
 239
 240 <h2>FILES</h2>
 241
 242 <h3> &nbsp; CONFIGURATION</h3>
 243 <pre>
 244        If <b>NOTMUCH</b>_<b>CONFIG</b> is unset, notmuch tries (in order)
 245
 246        • <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/&lt;profile&gt;/config</b> where <b>&lt;profile&gt;</b> is  defined
 247          by <b>$NOTMUCH</b>_<b>PROFILE</b> or &quot;default&quot;
 248
 249        • <b>${HOME}/.notmuch-config&lt;profile&gt;</b> where <b>&lt;profile&gt;</b> is <b>.$NOTMUCH</b>_<b>PROFILE</b>
 250          or &quot;&quot;
 251 </pre>
 252
 253 <h3> &nbsp; Hooks</h3>
 254 <pre>
 255        If <b>database.hook</b>_<b>dir</b> is unset, notmuch tries (in order)
 256
 257        • <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/&lt;profile&gt;/hooks</b> where <b>&lt;profile&gt;</b>  is  defined
 258          by <b>$NOTMUCH</b>_<b>PROFILE</b> or &quot;default&quot;
 259
 260        • <b>&lt;database.path&gt;/.notmuch/hooks</b>
 261 </pre>
 262
 263 <h2>SEE ALSO</h2>
 264 <pre>
 265        <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>
 266        <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),
 267        <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>
 268        <a href='../notmuch-show-1/'>much-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
 269 </pre>
 270
 271 <h2>AUTHOR</h2>
 272 <pre>
 273        Carl Worth and many others
 274 </pre>
 275
 276 <h2>COPYRIGHT</h2>
 277 <pre>
 278        2009-2021, Carl Worth and many others
 279 </pre>
 280
 281 <h2>0.32</h2>