complete sentence

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

diff --git a/manpages/notmuch-config-1.mdwn b/manpages/notmuch-config-1.mdwn
index 3e8cca4bce479891b61942ee5acf6859a7d3efcf..a8c8ccde10dbab7d5dfbefe3804e50285238b3a0 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,20 +124,30 @@
               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.
 

+       <b>show.extra_headers</b>
+          By default <a href='../notmuch-show-1/'>notmuch-show</a>(1) includes the following headers in  struc‐
+          tured  output if they are present in the message: <u>Subject</u>, <u>From</u>, <u>To</u>,
+          <u>Cc</u>, <u>Bcc</u>, <u>Reply-To</u>, <u>Date</u>. This option allows the specification  of  a
+          list of further headers to output.
+
+          History: This configuration value was introduced in notmuch 0.35.
+
+          Default: empty list.
+

        <b>maildir.synchronize</b>_<b>flags</b>
               If true, then the following maildir flags (in message filenames)
               will be synchronized with the corresponding notmuch tags:
        <b>maildir.synchronize</b>_<b>flags</b>
               If true, then the following maildir flags (in message filenames)
               will be synchronized with the corresponding notmuch tags:


@@ -119,32 +163,24 @@
                             ├─────┼────────────────────────────┤
                             │R    │ replied                    │
                             ├─────┼────────────────────────────┤
                             ├─────┼────────────────────────────┤
                             │R    │ replied                    │
                             ├─────┼────────────────────────────┤

-                            │S    │ unread   (added  when  &apos;S&apos; │
+                            │S    │ unread  (added  when   &apos;S&apos; │

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


@@ -160,12 +196,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:
 
                       ┌──────────────┬───────┬──────┬─────────┬──────┐


@@ -177,58 +212,111 @@
                       │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‐ │       │      │         │      │
                       │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>
+              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>
+       <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.
               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.

+
+       <b>squery.&lt;name&gt;</b>
+              Expansion for named query called &lt;name&gt;, using s-expression syn‐
+              tax.  See  <a href='../notmuch-sexp-queries-7/'>notmuch-sexp-queries</a>(7)  for  more  information about
+              s-expression queries.
+</pre>
+
+<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>
 
 </pre>
 

-<h2>ENVIRONMENT</h2>
+<h3> &nbsp; DATABASE LOCATION</h3>

 <pre>
 <pre>

-       The following environment variables can be used to control the behavior
-       of notmuch.
+       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>
+       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>
 </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-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-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>


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

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

 </pre>
 
 </pre>
 

-<h2>0.28</h2>
+<h2>0.35</h2>