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> &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>index.decrypt</b> <b>[STORED</b> <b>IN</b> <b>DATABASE]</b>
 140               Policy  for decrypting encrypted messages during indexing.  Must
 141               be one of: <b>false</b>, <b>auto</b>, <b>nostash</b>, or <b>true</b>.
 142
 143               When indexing an encrypted e-mail message, if this  variable  is
 144               set  to  <b>true</b>, notmuch will try to decrypt the message and index
 145               the cleartext, stashing a copy of any  discovered  session  keys
 146               for the message.  If <b>auto</b>, it will try to index the cleartext if
 147               a stashed session key is already known  for  the  message  (e.g.
 148               from  a  previous  copy), but will not try to access your secret
 149               keys.  Use <b>false</b> to avoid decrypting even when a stashed session
 150               key is already present.
 151
 152               <b>nostash</b>  is  the  same  as  <b>true</b>  except  that it will not stash
 153               newly-discovered session keys in the database.
 154
 155               From  the  command  line  (i.e.  during   <a href='../notmuch-new-1/'>notmuch-new</a>(1),   <a href='../notmuch-insert-1/'>not‐</a>
 156               <a href='../notmuch-insert-1/'>much-insert</a>(1),  or  <a href='../notmuch-reindex-1/'>notmuch-reindex</a>(1)),  the user can override
 157               the database&apos;s stored  decryption  policy  with  the  <b>--decrypt=</b>
 158               option.
 159
 160               Here  is  a  table  that summarizes the functionality of each of
 161               these policies:
 162
 163                       ┌──────────────┬───────┬──────┬─────────┬──────┐
 164                       │              │ false │ auto │ nostash │ true │
 165                       ├──────────────┼───────┼──────┼─────────┼──────┤
 166                       │Index cleart‐ │       │ X    │ X       │ X    │
 167                       │ext     using │       │      │         │      │
 168                       │stashed  ses‐ │       │      │         │      │
 169                       │sion keys     │       │      │         │      │
 170                       ├──────────────┼───────┼──────┼─────────┼──────┤
 171                       │Index cleart‐ │       │      │ X       │ X    │
 172                       │ext     using │       │      │         │      │
 173                       │secret keys   │       │      │         │      │
 174                       ├──────────────┼───────┼──────┼─────────┼──────┤
 175                       │Stash session │       │      │         │ X    │
 176                       │keys
 177                       ├──────────────┼───────┼──────┼─────────┼──────┤
 178                       │Delete
 179                       │stashed  ses‐ │       │      │         │      │
 180                       │sion keys  on │       │      │         │      │
 181                       │reindex       │       │      │         │      │
 182                       └──────────────┴───────┴──────┴─────────┴──────┘
 183
 184               Stashed  session  keys  are  kept  in the database as properties
 185               associated with the message.  See <b>session-key</b> in <a href='../notmuch-properties-7/'>notmuch-proper‐</a>
 186               <a href='../notmuch-properties-7/'>ties</a>(7) for more details about how they can be useful.
 187
 188               Be  aware  that  the  notmuch  index is likely sufficient (and a
 189               stashed session key is certainly sufficient) to reconstruct  the
 190               cleartext  of the message itself, so please ensure that the not‐
 191               much  message  index  is  adequately  protected.   DO  NOT   USE
 192               <b>index.decrypt=true</b>  or <b>index.decrypt=nostash</b> without considering
 193               the security of your index.
 194
 195               Default: <b>auto</b>.
 196
 197        <b>index.header.&lt;prefix&gt;</b> <b>[STORED</b> <b>IN</b> <b>DATABASE]</b>
 198               Define the query prefix &lt;prefix&gt;, based on a  mail  header.  For
 199               example  <b>index.header.List=List-Id</b> will add a probabilistic pre‐
 200               fix <b>List:</b> that searches the <b>List-Id</b> field.   User  defined  pre‐
 201               fixes must not start with &apos;a&apos;...&apos;z&apos;; in particular adding a pre‐
 202               fix with same name as a predefined prefix is not supported.  See
 203               <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7)  for a list of existing prefixes, and an
 204               explanation of probabilistic prefixes.
 205
 206        <b>built</b>_<b>with.&lt;name&gt;</b>
 207               Compile  time  feature  &lt;name&gt;.  Current  possibilities  include
 208               &quot;retry_lock&quot;  (configure  option,  included by default).  (since
 209               notmuch  0.30,  &quot;compact&quot;  and  &quot;field_processor&quot;   are   always
 210               included.)
 211
 212        <b>query.&lt;name&gt;</b> <b>[STORED</b> <b>IN</b> <b>DATABASE]</b>
 213               Expansion    for   named   query   called   &lt;name&gt;.   See   <a href='../notmuch-search-terms-7/'>not‐</a>
 214               <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7) for more information about named queries.
 215 </pre>
 216
 217 <h2>ENVIRONMENT</h2>
 218 <pre>
 219        The following environment variables can be used to control the behavior
 220        of notmuch.
 221
 222        <b>NOTMUCH</b>_<b>CONFIG</b>
 223               Specifies  the  location of the notmuch configuration file. Not‐
 224               much will use ${HOME}/.notmuch-config if this  variable  is  not
 225               set.
 226 </pre>
 227
 228 <h2>SEE ALSO</h2>
 229 <pre>
 230        <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>
 231        <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),
 232        <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>
 233        <a href='../notmuch-show-1/'>much-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
 234 </pre>
 235
 236 <h2>AUTHOR</h2>
 237 <pre>
 238        Carl Worth and many others
 239 </pre>
 240
 241 <h2>COPYRIGHT</h2>
 242 <pre>
 243        2009-2020, Carl Worth and many others
 244 </pre>
 245
 246 <h2>0.30</h2>