manpages updates for release 0.33

[notmuch-wiki] / manpages / notmuch-config-1.mdwn

diff --git a/manpages/notmuch-config-1.mdwn b/manpages/notmuch-config-1.mdwn
index 2e4fa2cded1746b4e09984f22c6108cb53649ae4..6ffaba62603c51b4cd846b594db3d82dce846d06 100644 (file)
--- a/manpages/notmuch-config-1.mdwn
+++ b/manpages/notmuch-config-1.mdwn
@@ -9,7 +9,7 @@
 <pre>
        <b>notmuch</b> <b>config</b> <b>get</b> &lt;<u>section</u>&gt;.&lt;<u>item</u>&gt;
 
 <pre>
        <b>notmuch</b> <b>config</b> <b>get</b> &lt;<u>section</u>&gt;.&lt;<u>item</u>&gt;
 

-       <b>notmuch</b> <b>config</b> <b>set</b> &lt;<u>section</u>&gt;.&lt;<u>item</u>&gt; [<u>value</u> ...]
+       <b>notmuch</b> <b>config</b> <b>set</b> [--database] &lt;<u>section</u>&gt;.&lt;<u>item</u>&gt; [<u>value</u> ...]

 
        <b>notmuch</b> <b>config</b> <b>list</b>
 </pre>
 
        <b>notmuch</b> <b>config</b> <b>list</b>
 </pre>


@@ -19,10 +19,6 @@
        The  <b>config</b>  command  can be used to get or set settings in the notmuch
        configuration file and corresponding database.
 
        The  <b>config</b>  command  can be used to get or set settings in the notmuch
        configuration file and corresponding database.
 

-       Items marked <b>[STORED</b> <b>IN</b> <b>DATABASE]</b>  are  only  in  the  database.   They
-       should  not be placed in the configuration file, and should be accessed
-       programmatically as described in the SYNOPSIS above.
-

        <b>get</b>    The value of the specified configuration item is printed to std‐
               out.  If the item has multiple values (it is a list), each value
               is separated by a newline character.
        <b>get</b>    The value of the specified configuration item is printed to std‐
               out.  If the item has multiple values (it is a list), each value
               is separated by a newline character.


@@ -34,25 +30,63 @@
               If no values are provided, the specified configuration item will
               be removed from the configuration file.
 
               If no values are provided, the specified configuration item will
               be removed from the configuration file.
 

+              With  the  <u>--database</u>  option,  updates  configuration  metadata
+              stored in the database, rather than the default (text)  configu‐
+              ration file.
+

        <b>list</b>   Every  configuration  item is printed to stdout, each on a sepa‐
               rate line of the form:
 
        <b>list</b>   Every  configuration  item is printed to stdout, each on a sepa‐
               rate line of the form:
 

-                 *section*.\ *item*\ =\ *value*
+                 section.item=value

 
               No additional whitespace surrounds the dot or equals sign  char‐
               acters.  In a multiple-value item (a list), the values are sepa‐
               rated by semicolon characters.
 
 
               No additional whitespace surrounds the dot or equals sign  char‐
               acters.  In a multiple-value item (a list), the values are sepa‐
               rated by semicolon characters.
 

-       The available configuration items are described below.
+       The available configuration items  are  described  below.  Non-absolute
+       paths are presumed relative to <u>$HOME</u> for items in section <b>database</b>.

 
        <b>database.path</b>
 
        <b>database.path</b>

+              Notmuch  will  store  its database here, (in sub-directory named
+              <b>.notmuch</b> if <b>database.mail</b>_<b>root</b> is unset).
+
+              Default: see <u>DATABASE</u> <u>LOCATION</u>
+
+       <b>database.mail</b>_<b>root</b>

               The top-level directory where your mail currently exists and  to
               The top-level directory where your mail currently exists and  to

-              where  mail  will  be  delivered  in the future. Files should be
-              individual email  messages.  Notmuch  will  store  its  database
-              within  a  sub-directory of the path configured here named <b>.not-</b>
-              <b>much</b>.
+              where  mail will be delivered in the future. Files should be in‐
+              dividual email messages.
+
+              History: this configuration  value  was  introduced  in  notmuch
+              0.32.
+
+              Default:  For compatibility with older configurations, the value
+              of database.path is used if <b>database.mail</b>_<b>root</b> is unset.
+
+       <b>database.backup</b>_<b>dir</b>
+              Directory to store tag dumps when upgrading database.
+
+              History: this configuration  value  was  introduced  in  notmuch
+              0.32.
+
+              Default: A sibling directory of the Xapian database called <u>back‐</u>
+              <u>ups</u>.
+
+       <b>database.hook</b>_<b>dir</b>
+              Directory containing hooks run by  notmuch  commands.  See  <a href='../notmuch-hooks-5/'>not‐</a>
+              <a href='../notmuch-hooks-5/'>much-hooks</a>(5).

 
 

-              Default: <b>$MAILDIR</b> variable if set, otherwise <b>$HOME/mail</b>.
+              History:  this  configuration  value  was  introduced in notmuch
+              0.32.
+
+              Default: See HOOKS, below.
+
+       <b>database.autocommit</b>
+          How often to commit transactions to disk. <u>0</u> means wait until command
+          completes,  otherwise an integer <u>n</u> specifies to commit to disk after
+          every <u>n</u> completed transactions.
+
+          History: this configuration value was introduced in notmuch 0.33.

 
        <b>user.name</b>
               Your full name.
 
        <b>user.name</b>
               Your full name.


@@ -78,8 +112,8 @@
 
        <b>new.ignore</b>
               A list to  specify  files  and  directories  that  will  not  be
 
        <b>new.ignore</b>
               A list to  specify  files  and  directories  that  will  not  be

-              searched  for messages by <b>notmuch</b> <b>new</b>. Each entry in the list is
-              either:
+              searched  for messages by <a href='../notmuch-new-1/'>notmuch-new</a>(1). Each entry in the list
+              is either:

 
               A file or a directory name, without path, that will be  ignored,
               regardless  of  the location in the mail store directory hierar‐
 
               A file or a directory name, without path, that will be  ignored,
               regardless  of  the location in the mail store directory hierar‐


@@ -90,16 +124,16 @@
               A regular expression delimited with  //  that  will  be  matched
               against  the path of the file or directory relative to the data‐
               base path. Matching files and directories will be  ignored.  The
               A regular expression delimited with  //  that  will  be  matched
               against  the path of the file or directory relative to the data‐
               base path. Matching files and directories will be  ignored.  The

-              beginning  and  end  of  string must be explicitly anchored. For
-              example, /.*/foo$/ would match &quot;bar/foo&quot; and &quot;bar/baz/foo&quot;,  but
+              beginning and end of string must be explicitly anchored. For ex‐
+              ample, /.*/foo$/ would match &quot;bar/foo&quot;  and  &quot;bar/baz/foo&quot;,  but

               not &quot;foo&quot; or &quot;bar/foobar&quot;.
 
               Default: empty list.
 
        <b>search.exclude</b>_<b>tags</b>
               not &quot;foo&quot; or &quot;bar/foobar&quot;.
 
               Default: empty list.
 
        <b>search.exclude</b>_<b>tags</b>

-              A  list  of  tags  that  will be excluded from search results by
-              default. Using an excluded tag in a  query  will  override  that
-              exclusion.
+              A  list of tags that will be excluded from search results by de‐
+              fault. Using an excluded tag in a query will override  that  ex‐
+              clusion.

 
               Default:   empty   list.   Note   that   <b>notmuch-setup</b>(1)   puts
               <b>deleted;spam</b> here when creating new configuration file.
 
               Default:   empty   list.   Note   that   <b>notmuch-setup</b>(1)   puts
               <b>deleted;spam</b> here when creating new configuration file.


@@ -123,62 +157,54 @@
                             │     │ flag is not present)       │
                             └─────┴────────────────────────────┘
 
                             │     │ flag is not present)       │
                             └─────┴────────────────────────────┘
 

-              The <b>notmuch</b> <b>new</b> command will notice flag  changes  in  filenames
-              and  update tags, while the <b>notmuch</b> <b>tag</b> and <b>notmuch</b> <b>restore</b> com‐
-              mands will notice tag changes and update flags in filenames.
+              The <a href='../notmuch-new-1/'>notmuch-new</a>(1) command will notice flag changes in filenames
+              and update tags, while the <a href='../notmuch-tag-1/'>notmuch-tag</a>(1) and <a href='../notmuch-restore-1/'>notmuch-restore</a>(1)
+              commands will notice tag changes and update flags in filenames.

 
               If there have been any changes  in  the  maildir  (new  messages
               added,  old  ones  removed  or  renamed,  maildir flags changed,
 
               If there have been any changes  in  the  maildir  (new  messages
               added,  old  ones  removed  or  renamed,  maildir flags changed,

-              etc.), it is advisable to run <b>notmuch</b> <b>new</b> before <b>notmuch</b> <b>tag</b>  or
-              <b>notmuch</b>  <b>restore</b> commands to ensure the tag changes are properly
-              synchronized to the maildir flags, as the  commands  expect  the
-              database and maildir to be in sync.
+              etc.),  it  is  advisable  to  run  <a href='../notmuch-new-1/'>notmuch-new</a>(1)  before  <a href='../notmuch-tag-1/'>not‐</a>
+              <a href='../notmuch-tag-1/'>much-tag</a>(1)  or  <a href='../notmuch-restore-1/'>notmuch-restore</a>(1)  commands  to ensure the tag
+              changes are properly synchronized to the maildir flags,  as  the
+              commands expect the database and maildir to be in sync.

 
               Default: <b>true</b>.
 
 
               Default: <b>true</b>.
 

-       <b>crypto.gpg</b>_<b>path</b>
-              Name  (or  full  path)  of gpg binary to use in verification and
-              decryption of PGP/MIME messages.  NOTE: This configuration  item
-              is  deprecated,  and will be ignored if notmuch is built against
-              GMime 3.0 or later.
-
-              Default: <b>gpg</b>.
-
-       <b>index.decrypt</b> <b>[STORED</b> <b>IN</b> <b>DATABASE]</b>
-              Policy for decrypting encrypted messages during indexing.   Must
+       <b>index.decrypt</b>
+              Policy  for decrypting encrypted messages during indexing.  Must

               be one of: <b>false</b>, <b>auto</b>, <b>nostash</b>, or <b>true</b>.
 
               be one of: <b>false</b>, <b>auto</b>, <b>nostash</b>, or <b>true</b>.
 

-              When  indexing  an encrypted e-mail message, if this variable is
-              set to <b>true</b>, notmuch will try to decrypt the message  and  index
-              the  cleartext,  stashing  a copy of any discovered session keys
+              When indexing an encrypted e-mail message, if this  variable  is
+              set  to  <b>true</b>, notmuch will try to decrypt the message and index
+              the cleartext, stashing a copy of any  discovered  session  keys

               for the message.  If <b>auto</b>, it will try to index the cleartext if
               for the message.  If <b>auto</b>, it will try to index the cleartext if

-              a  stashed  session  key  is already known for the message (e.g.
-              from a previous copy), but will not try to  access  your  secret
+              a stashed session key is already known  for  the  message  (e.g.
+              from  a  previous  copy), but will not try to access your secret

               keys.  Use <b>false</b> to avoid decrypting even when a stashed session
               key is already present.
 
               keys.  Use <b>false</b> to avoid decrypting even when a stashed session
               key is already present.
 

-              <b>nostash</b> is the same as  <b>true</b>  except  that  it  will  not  stash
+              <b>nostash</b>  is  the  same  as  <b>true</b>  except  that it will not stash

               newly-discovered session keys in the database.
 
               newly-discovered session keys in the database.
 

-              From   the   command  line  (i.e.  during  <a href='../notmuch-new-1/'>notmuch-new</a>(1),  <a href='../notmuch-insert-1/'>not‐</a>
-              <a href='../notmuch-insert-1/'>much-insert</a>(1), or <a href='../notmuch-reindex-1/'>notmuch-reindex</a>(1)), the  user  can  override
-              the  database&apos;s  stored  decryption  policy  with the <b>--decrypt=</b>
-              option.
+              From the command line (i.e. during  <a href='../notmuch-new-1/'>notmuch-new</a>(1),  <a href='../notmuch-insert-1/'>notmuch-in‐</a>
+              <a href='../notmuch-insert-1/'>sert</a>(1), or <a href='../notmuch-reindex-1/'>notmuch-reindex</a>(1)), the user can override the data‐
+              base&apos;s stored decryption policy with the <b>--decrypt=</b> option.

 
               Here is a table that summarizes the  functionality  of  each  of
               these policies:
 
                       ┌──────────────┬───────┬──────┬─────────┬──────┐
                       │              │ false │ auto │ nostash │ true │
 
               Here is a table that summarizes the  functionality  of  each  of
               these policies:
 
                       ┌──────────────┬───────┬──────┬─────────┬──────┐
                       │              │ false │ auto │ nostash │ true │

-                      ├──────────────┼───────┼──────┼─────────┼──────┤
+                      └──────────────┴───────┴──────┴─────────┴──────┘
+

                       │Index cleart‐ │       │ X    │ X       │ X    │
                       │ext     using │       │      │         │      │
                       │stashed  ses‐ │       │      │         │      │
                       │sion keys     │       │      │         │      │
                       ├──────────────┼───────┼──────┼─────────┼──────┤
                       │Index cleart‐ │       │      │ X       │ X    │
                       │Index cleart‐ │       │ X    │ X       │ X    │
                       │ext     using │       │      │         │      │
                       │stashed  ses‐ │       │      │         │      │
                       │sion keys     │       │      │         │      │
                       ├──────────────┼───────┼──────┼─────────┼──────┤
                       │Index cleart‐ │       │      │ X       │ X    │

-                      │ext     using │       │      │         │      │
-                      │secret keys   │       │      │         │      │
+                      │ext using se‐ │       │      │         │      │
+                      │cret keys     │       │      │         │      │

                       ├──────────────┼───────┼──────┼─────────┼──────┤
                       │Stash session │       │      │         │ X    │
                       │keys
                       ├──────────────┼───────┼──────┼─────────┼──────┤
                       │Stash session │       │      │         │ X    │
                       │keys


@@ -189,20 +215,20 @@
                       │reindex       │       │      │         │      │
                       └──────────────┴───────┴──────┴─────────┴──────┘
 
                       │reindex       │       │      │         │      │
                       └──────────────┴───────┴──────┴─────────┴──────┘
 

-              Stashed session keys are kept  in  the  database  as  properties
-              associated with the message.  See <b>session-key</b> in <a href='../notmuch-properties-7/'>notmuch-proper‐</a>
+              Stashed session keys are kept in the database as properties  as‐
+              sociated  with  the message.  See <b>session-key</b> in <a href='../notmuch-properties-7/'>notmuch-proper‐</a>

               <a href='../notmuch-properties-7/'>ties</a>(7) for more details about how they can be useful.
 
               Be aware that the notmuch index  is  likely  sufficient  (and  a
               stashed  session key is certainly sufficient) to reconstruct the
               cleartext of the message itself, so please ensure that the  not‐
               <a href='../notmuch-properties-7/'>ties</a>(7) for more details about how they can be useful.
 
               Be aware that the notmuch index  is  likely  sufficient  (and  a
               stashed  session key is certainly sufficient) to reconstruct the
               cleartext of the message itself, so please ensure that the  not‐

-              much   message  index  is  adequately  protected.   DO  NOT  USE
-              <b>index.decrypt=true</b> or <b>index.decrypt=nostash</b> without  considering
+              much  message  index  is  adequately  protected.  DO NOT USE <b>in-</b>
+              <b>dex.decrypt=true</b> or  <b>index.decrypt=nostash</b>  without  considering

               the security of your index.
 
               Default: <b>auto</b>.
 
               the security of your index.
 
               Default: <b>auto</b>.
 

-       <b>index.header.&lt;prefix&gt;</b> <b>[STORED</b> <b>IN</b> <b>DATABASE]</b>
+       <b>index.header.&lt;prefix&gt;</b>

               Define  the  query  prefix &lt;prefix&gt;, based on a mail header. For
               example <b>index.header.List=List-Id</b> will add a probabilistic  pre‐
               fix  <b>List:</b>  that  searches the <b>List-Id</b> field.  User defined pre‐
               Define  the  query  prefix &lt;prefix&gt;, based on a mail header. For
               example <b>index.header.List=List-Id</b> will add a probabilistic  pre‐
               fix  <b>List:</b>  that  searches the <b>List-Id</b> field.  User defined pre‐


@@ -212,32 +238,71 @@
               explanation of probabilistic prefixes.
 
        <b>built</b>_<b>with.&lt;name&gt;</b>
               explanation of probabilistic prefixes.
 
        <b>built</b>_<b>with.&lt;name&gt;</b>

-              Compile time feature &lt;name&gt;. Current possibilities include &quot;com‐
-              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>
-              <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7)).
+              Compile  time  feature  &lt;name&gt;.  Current  possibilities  include
+              &quot;retry_lock&quot; (configure option, included  by  default).   (since
+              notmuch  0.30,  &quot;compact&quot;  and  &quot;field_processor&quot; are always in‐
+              cluded.)

 
 

-       <b>query.&lt;name&gt;</b> <b>[STORED</b> <b>IN</b> <b>DATABASE]</b>
-              Expansion    for   named   query   called   &lt;name&gt;.   See   <a href='../notmuch-search-terms-7/'>not‐</a>
+       <b>query.&lt;name&gt;</b>
+              Expansion   for   named   query   called   &lt;name&gt;.   See    <a href='../notmuch-search-terms-7/'>not‐</a>

               <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7) for more information about named queries.
 </pre>
 
               <a href='../notmuch-search-terms-7/'>much-search-terms</a>(7) for more information about named queries.
 </pre>
 

-<h2>ENVIRONMENT</h2>
+<h2>FILES</h2>
+
+<h3> &nbsp; CONFIGURATION</h3>
+<pre>
+       Notmuch configuration file search order:
+
+       1. File specified by <b>notmuch</b> <b>--config</b> global option; see <a href='../notmuch-1/'>notmuch</a>(1).
+
+       2. File specified by <b>NOTMUCH</b>_<b>CONFIG</b> environment variable.
+
+       3. <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/&lt;profile&gt;/config</b> where <b>&lt;profile&gt;</b> is defined
+          by  <b>NOTMUCH</b>_<b>PROFILE</b>   environment   variable   if   set,   <b>$XDG</b>_<b>CON-</b>
+          <b>FIG</b>_<b>HOME/notmuch/default/config</b> otherwise.
+
+       4. <b>$HOME/.notmuch-config.&lt;profile&gt;</b>  where  <b>&lt;profile&gt;</b> is defined by <b>NOT-</b>
+          <b>MUCH</b>_<b>PROFILE</b> environment variable if set, <b>$HOME/.notmuch-config</b> oth‐
+          erwise.
+</pre>
+
+<h3> &nbsp; DATABASE LOCATION</h3>
+<pre>
+       Notmuch database search order:
+
+       1. Directory specified by <b>NOTMUCH</b>_<b>DATABASE</b> environment variable.
+
+       2. Directory specified by config key <b>database.path</b>.
+
+       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>
+          <b>MUCH</b>_<b>PROFILE</b> environment variable if set, <b>$XDG</b>_<b>DATA</b>_<b>HOME/notmuch/de-</b>
+          <b>fault</b> otherwise.
+
+       4. Directory specified by <b>MAILDIR</b> environment variable.
+
+       5. <b>$HOME/mail</b>
+</pre>
+
+<h3> &nbsp; HOOKS</h3>

 <pre>
 <pre>

-       The following environment variables can be used to control the behavior
-       of notmuch.
+       Notmuch hook directory search order:
+
+       1. Directory specified by <b>database.hook</b>_<b>dir</b> configuration option.
+
+       2. <b>$XDG</b>_<b>CONFIG</b>_<b>HOME/notmuch/&lt;profile&gt;/hooks</b>  where <b>&lt;profile&gt;</b> is defined
+          by  <b>NOTMUCH</b>_<b>PROFILE</b>   environment   variable   if   set,   <b>$XDG</b>_<b>CON-</b>
+          <b>FIG</b>_<b>HOME/notmuch/default/hooks</b> otherwise.

 
 

-       <b>NOTMUCH</b>_<b>CONFIG</b>
-              Specifies  the  location of the notmuch configuration file. Not‐
-              much will use ${HOME}/.notmuch-config if this  variable  is  not
-              set.
+       3. <b>&lt;database.path&gt;/.notmuch/hooks</b>

 </pre>
 
 <h2>SEE ALSO</h2>
 <pre>
        <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>
 </pre>
 
 <h2>SEE ALSO</h2>
 <pre>
        <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>

-       <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),
-       <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>
-       <a href='../notmuch-show-1/'>much-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
+       <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>
+       <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),
+       <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)

 </pre>
 
 <h2>AUTHOR</h2>
 </pre>
 
 <h2>AUTHOR</h2>


@@ -247,7 +312,7 @@
 
 <h2>COPYRIGHT</h2>
 <pre>
 
 <h2>COPYRIGHT</h2>
 <pre>

-       2009-2019, Carl Worth and many others
+       2009-2021, Carl Worth and many others

 </pre>
 
 </pre>
 

-<h2>0.29</h2>
+<h2>0.33</h2>