manpages updates for release 0.32

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

diff --git a/manpages/notmuch-config-1.mdwn b/manpages/notmuch-config-1.mdwn
index 037391026e52a433b9a1dd2e98a0adc657e67267..c06a30795e6d9509e2e4decab0cb20cefcf52562 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,6 +30,10 @@
               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:
 


@@ -46,14 +46,26 @@
        The available configuration items are described below.
 
        <b>database.path</b>
        The available configuration items are described below.
 
        <b>database.path</b>

-              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>.
+              Notmuch will store its database here,  (in  sub-directory  named
+              <b>.notmuch</b> if <b>database.mail</b>_<b>root</b> is unset).

 
               Default: <b>$MAILDIR</b> variable if set, otherwise <b>$HOME/mail</b>.
 
 
               Default: <b>$MAILDIR</b> variable if set, otherwise <b>$HOME/mail</b>.
 

+       <b>database.mail</b>_<b>root</b>
+              The  top-level directory where your mail currently exists and to
+              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.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).
+

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


@@ -90,16 +102,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.


@@ -136,7 +148,7 @@
 
               Default: <b>true</b>.
 
 
               Default: <b>true</b>.
 

-       <b>index.decrypt</b> <b>[STORED</b> <b>IN</b> <b>DATABASE]</b>
+       <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>.
 
               Policy  for decrypting encrypted messages during indexing.  Must
               be one of: <b>false</b>, <b>auto</b>, <b>nostash</b>, or <b>true</b>.
 


@@ -152,12 +164,11 @@
               <b>nostash</b>  is  the  same  as  <b>true</b>  except  that it will not stash
               newly-discovered session keys in the database.
 
               <b>nostash</b>  is  the  same  as  <b>true</b>  except  that it will not stash
               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
+              Here is a table that summarizes the  functionality  of  each  of

               these policies:
 
                       ┌──────────────┬───────┬──────┬─────────┬──────┐
               these policies:
 
                       ┌──────────────┬───────┬──────┬─────────┬──────┐


@@ -169,48 +180,48 @@
                       │sion keys     │       │      │         │      │
                       ├──────────────┼───────┼──────┼─────────┼──────┤
                       │Index cleart‐ │       │      │ X       │ X    │
                       │sion keys     │       │      │         │      │
                       ├──────────────┼───────┼──────┼─────────┼──────┤
                       │Index cleart‐ │       │      │ X       │ X    │

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

                       ├──────────────┼───────┼──────┼─────────┼──────┤
                       │Stash session │       │      │         │ X    │
                       │keys
                       ├──────────────┼───────┼──────┼─────────┼──────┤
                       │Delete
                       │stashed  ses‐ │       │      │         │      │
                       ├──────────────┼───────┼──────┼─────────┼──────┤
                       │Stash session │       │      │         │ X    │
                       │keys
                       ├──────────────┼───────┼──────┼─────────┼──────┤
                       │Delete
                       │stashed  ses‐ │       │      │         │      │

-                      │sion keys  on │       │      │         │      │
+                      │sion  keys on │       │      │         │      │

                       │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.
 
               <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
+              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>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>
-              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‐
+       <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‐

               fixes must not start with &apos;a&apos;...&apos;z&apos;; in particular adding a pre‐
               fixes must not start with &apos;a&apos;...&apos;z&apos;; in particular adding a pre‐

-              fix with same name as a predefined prefix is not supported.  See
-              <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7)  for a list of existing prefixes, and an
+              fix  with same name as a predefined prefix is not supported. See
+              <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for a list of existing prefixes, and  an

               explanation of probabilistic prefixes.
 
        <b>built</b>_<b>with.&lt;name&gt;</b>
               Compile  time  feature  &lt;name&gt;.  Current  possibilities  include
               explanation of probabilistic prefixes.
 
        <b>built</b>_<b>with.&lt;name&gt;</b>
               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
-              included.)
+              &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>
 


@@ -220,9 +231,33 @@
        of notmuch.
 
        <b>NOTMUCH</b>_<b>CONFIG</b>
        of notmuch.
 
        <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.
+              Specifies the location of the notmuch configuration file.
+
+       <b>NOTMUCH</b>_<b>PROFILE</b>
+              Selects among notmuch configurations.
+</pre>
+
+<h2>FILES</h2>
+
+<h3> &nbsp; CONFIGURATION</h3>
+<pre>
+       If <b>NOTMUCH</b>_<b>CONFIG</b> is unset, notmuch tries (in order)
+
+       • <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> or &quot;default&quot;
+
+       • <b>${HOME}/.notmuch-config&lt;profile&gt;</b> where <b>&lt;profile&gt;</b> is <b>.$NOTMUCH</b>_<b>PROFILE</b>
+         or &quot;&quot;
+</pre>
+
+<h3> &nbsp; Hooks</h3>
+<pre>
+       If <b>database.hook</b>_<b>dir</b> is unset, notmuch tries (in order)
+
+       • <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> or &quot;default&quot;
+
+       • <b>&lt;database.path&gt;/.notmuch/hooks</b>

 </pre>
 
 <h2>SEE ALSO</h2>
 </pre>
 
 <h2>SEE ALSO</h2>


@@ -240,7 +275,7 @@
 
 <h2>COPYRIGHT</h2>
 <pre>
 
 <h2>COPYRIGHT</h2>
 <pre>

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

 </pre>
 
 </pre>
 

-<h2>0.31</h2>
+<h2>0.32</h2>