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 6a91a06416ad6ee0a9d05dce37b8186a5d2a2d0c..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,10 +30,14 @@
               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‐
 
               No additional whitespace surrounds the dot or equals sign  char‐
               acters.  In a multiple-value item (a list), the values are sepa‐


@@ -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,34 +148,25 @@
 
               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:
 
               Here is a table that summarizes the  functionality  of  each  of
               these policies:


@@ -177,38 +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    │
                       ├──────────────┼───────┼──────┼─────────┼──────┤
                       │Stash session │       │      │         │ X    │

-                      │keys          │       │      │         │      │
+                      │keys

                       ├──────────────┼───────┼──────┼─────────┼──────┤
                       ├──────────────┼───────┼──────┼─────────┼──────┤

-                      │Delete        │       │      │         │      │
+                      │Delete

                       │stashed  ses‐ │       │      │         │      │
                       │sion  keys on │       │      │         │      │
                       │reindex       │       │      │         │      │
                       └──────────────┴───────┴──────┴─────────┴──────┘
 
                       │stashed  ses‐ │       │      │         │      │
                       │sion  keys on │       │      │         │      │
                       │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>
+              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‐
+              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>
        <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>
 


@@ -218,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>


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

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

 </pre>
 
 </pre>
 

-<h2>0.26</h2>
+<h2>0.32</h2>