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>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>