Merge tag 'debian/0.26-1' into debian/stretch-backports

notmuch Debian 0.26-1 upload (same as 0.26)

20 files changed, 681 insertions, 207 deletions

diff --git a/doc/.gitignore b/doc/.gitignore
index 9fa35d08..bbb749fa 100644
--- a/doc/.gitignore
+++ b/doc/.gitignore
@@ -1,3 +1,3 @@
 *.pyc
-_build
-config.dox
+/_build
+/config.dox
diff --git a/doc/conf.py b/doc/conf.py
index a3d82696..efbafc93 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -12,7 +12,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'notmuch'
-copyright = u'2009-2017, Carl Worth and many others'
+copyright = u'2009-2018, Carl Worth and many others'
 
 location = os.path.dirname(__file__)
 
@@ -47,6 +47,10 @@ html_static_path = []
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'notmuchdoc'
 
+# Disable SmartyPants, as it mangles command lines.
+# Despite the name, this actually affects manual pages as well.
+html_use_smartypants = False
+
 # -- Options for manual page output ---------------------------------------
 
 # One entry per manual page. List of tuples
@@ -95,6 +99,14 @@ man_pages = [
      u'incorporate new mail into the notmuch database',
      [notmuch_authors], 1),
 
+    ('man7/notmuch-properties', 'notmuch-properties',
+     u'notmuch message property conventions and documentation',
+     [notmuch_authors], 7),
+
+    ('man1/notmuch-reindex', 'notmuch-reindex',
+     u're-index matching messages',
+     [notmuch_authors], 1),
+
     ('man1/notmuch-reply', 'notmuch-reply',
      u'constructs a reply template for a set of messages',
      [notmuch_authors], 1),
diff --git a/doc/index.rst b/doc/index.rst
index 344606d9..4440d93a 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -18,6 +18,8 @@ Contents:
    man5/notmuch-hooks
    man1/notmuch-insert
    man1/notmuch-new
+   man7/notmuch-properties
+   man1/notmuch-reindex
    man1/notmuch-reply
    man1/notmuch-restore
    man1/notmuch-search
diff --git a/doc/man1/notmuch-address.rst b/doc/man1/notmuch-address.rst
index cc31cc5a..68415d13 100644
--- a/doc/man1/notmuch-address.rst
+++ b/doc/man1/notmuch-address.rst
@@ -29,7 +29,7 @@ Supported options for **address** include
         intended for programs that invoke **notmuch(1)** internally. If
         omitted, the latest supported version will be used.
 
-    ``--output=(sender|recipients|count)``
+    ``--output=(sender|recipients|count|address)``
 
         Controls which information appears in the output. This option
         can be given multiple times to combine different outputs.
@@ -55,6 +55,11 @@ Supported options for **address** include
             Note: With this option, addresses are printed only after
             the whole search is finished. This may take long time.
 
+        **address**
+            Output only the email addresses instead of the full
+            mailboxes with names and email addresses. This option has
+            no effect on the JSON or S-Expression output formats.
+
     ``--deduplicate=(no|mailbox|address)``
 
         Control the deduplication of results.
@@ -115,8 +120,16 @@ This command supports the following special exit status codes
 SEE ALSO
 ========
 
-**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
-**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
-**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
-**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**,
+**notmuch(1)**,
+**notmuch-config(1)**,
+**notmuch-count(1)**,
+**notmuch-dump(1)**,
+**notmuch-hooks(5)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-reply(1)**,
+**notmuch-restore(1)**,
+**notmuch-search-terms(7)**,
+**notmuch-show(1)**,
+**notmuch-tag(1)**,
 **notmuch-search(1)**
diff --git a/doc/man1/notmuch-compact.rst b/doc/man1/notmuch-compact.rst
index e0109dce..25692c5b 100644
--- a/doc/man1/notmuch-compact.rst
+++ b/doc/man1/notmuch-compact.rst
@@ -46,7 +46,15 @@ of notmuch.
 SEE ALSO
 ========
 
-**notmuch(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
-**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
-**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
-**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
+**notmuch(1)**,
+**notmuch-count(1)**,
+**notmuch-dump(1)**,
+**notmuch-hooks(5)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-reply(1)**,
+**notmuch-restore(1)**,
+**notmuch-search(1)**,
+**notmuch-search-terms(7)**,
+**notmuch-show(1)**,
+**notmuch-tag(1)**
diff --git a/doc/man1/notmuch-config.rst b/doc/man1/notmuch-config.rst
index 6a51e64f..9d6ff107 100644
--- a/doc/man1/notmuch-config.rst
+++ b/doc/man1/notmuch-config.rst
@@ -15,7 +15,11 @@ DESCRIPTION
 ===========
 
 The **config** command can be used to get or set settings in the notmuch
-configuration file.
+configuration file and corresponding database.
+
+Items marked **[STORED IN DATABASE]** 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.
 
     **get**
         The value of the specified configuration item is printed to
@@ -75,11 +79,22 @@ The available configuration items are described below.
         Default: ``unread;inbox``.
 
     **new.ignore**
-        A list of file and directory names, without path, that will not
-        be searched for messages by **notmuch new**. All the files and
-        directories matching any of the names specified here will be
-        ignored, regardless of the location in the mail store directory
-        hierarchy.
+        A list to specify files and directories that will not be
+        searched for messages by **notmuch new**. 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 hierarchy.
+
+        Or:
+
+          A regular expression delimited with // that will be matched
+          against the path of the file or directory relative to the
+          database path. Matching files and directories will be
+          ignored. The beginning and end of string must be explictly
+          anchored. For example, /.*/foo$/ would match "bar/foo" and
+          "bar/baz/foo", but not "foo" or "bar/foobar".
 
         Default: empty list.
 
@@ -134,6 +149,63 @@ The available configuration items are described below.
 
         Default: ``gpg``.
 
+    **index.decrypt**
+
+        **[STORED IN DATABASE]**
+
+        Policy for decrypting encrypted messages during indexing.
+        Must be one of: ``false``, ``auto``, ``nostash``, or
+        ``true``.
+
+        When indexing an encrypted e-mail message, if this variable is
+        set to ``true``, notmuch will try to decrypt the message and
+        index the cleartext, stashing a copy of any discovered session
+        keys for the message.  If ``auto``, 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 keys.  Use ``false`` to avoid decrypting even when a
+        stashed session key is already present.
+
+        ``nostash`` is the same as ``true`` except that it will not
+        stash newly-discovered session keys in the database.
+
+        From the command line (i.e. during **notmuch-new(1)**,
+        **notmuch-insert(1)**, or **notmuch-reindex(1)**), the user
+        can override the database's stored decryption policy with the
+        ``--decrypt=`` option.
+
+        Here is a table that summarizes the functionality of each of
+        these policies:
+
+        +------------------------+-------+------+---------+------+
+        |                        | false | auto | nostash | true |
+        +========================+=======+======+=========+======+
+        | Index cleartext using  |       |  X   |    X    |  X   |
+        | stashed session keys   |       |      |         |      |
+        +------------------------+-------+------+---------+------+
+        | Index cleartext        |       |      |    X    |  X   |
+        | using secret keys      |       |      |         |      |
+        +------------------------+-------+------+---------+------+
+        | Stash session keys     |       |      |         |  X   |
+        +------------------------+-------+------+---------+------+
+        | Delete stashed session |   X   |      |         |      |
+        | keys on reindex        |       |      |         |      |
+        +------------------------+-------+------+---------+------+
+
+        Stashed session keys are kept in the database as properties
+        associated with the message.  See ``session-key`` in
+        **notmuch-properties(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
+        notmuch message index is adequately protected.  DO NOT USE
+        ``index.decrypt=true`` or ``index.decrypt=nostash`` without
+        considering the security of your index.
+
+        Default: ``auto``.
+
     **built_with.<name>**
 
         Compile time feature <name>. Current possibilities include
@@ -142,6 +214,7 @@ The available configuration items are described below.
 
     **query.<name>**
 
+        **[STORED IN DATABASE]**
         Expansion for named query called <name>. See
         **notmuch-search-terms(7)** for more information about named
         queries.
@@ -159,7 +232,16 @@ of notmuch.
 SEE ALSO
 ========
 
-**notmuch(1)**, **notmuch-count(1)**, **notmuch-dump(1)**,
-**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
-**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
-**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
+**notmuch(1)**,
+**notmuch-count(1)**,
+**notmuch-dump(1)**,
+**notmuch-hooks(5)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-reply(1)**,
+**notmuch-restore(1)**,
+**notmuch-search(1)**,
+**notmuch-search-terms(7)**,
+**notmuch-properties(7)**,
+**notmuch-show(1)**,
+**notmuch-tag(1)**
diff --git a/doc/man1/notmuch-count.rst b/doc/man1/notmuch-count.rst
index 90d852ae..35a2e5e8 100644
--- a/doc/man1/notmuch-count.rst
+++ b/doc/man1/notmuch-count.rst
@@ -59,7 +59,15 @@ Supported options for **count** include
 SEE ALSO
 ========
 
-**notmuch(1)**, **notmuch-config(1)**, **notmuch-dump(1)**,
-**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
-**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
-**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
+**notmuch(1)**,
+**notmuch-config(1)**,
+**notmuch-dump(1)**,
+**notmuch-hooks(5)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-reply(1)**,
+**notmuch-restore(1)**,
+**notmuch-search(1)**,
+**notmuch-search-terms(7)**,
+**notmuch-show(1)**,
+**notmuch-tag(1)**
diff --git a/doc/man1/notmuch-dump.rst b/doc/man1/notmuch-dump.rst
index f3f2b394..7bc57d29 100644
--- a/doc/man1/notmuch-dump.rst
+++ b/doc/man1/notmuch-dump.rst
@@ -85,8 +85,8 @@ Supported options for **dump** include
 
         Output per-message (key,value) metadata.  Each line starts
         with "#= ", followed by a message id, and a space separated
-        list of key=value pairs.  pair.  Ids, keys and values are hex
-        encoded if needed.
+        list of key=value pairs.  Ids, keys and values are hex encoded
+        if needed.  See **notmuch-properties(7)** for more details.
 
       **tags**
 
@@ -110,7 +110,16 @@ Supported options for **dump** include
 SEE ALSO
 ========
 
-**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
-**notmuch-hooks(5)**, **notmuch-insert(1)**, **notmuch-new(1)**,
-**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
-**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
+**notmuch(1)**,
+**notmuch-config(1)**,
+**notmuch-count(1)**,
+**notmuch-hooks(5)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-properties(7)**,
+**notmuch-reply(1)**,
+**notmuch-restore(1)**,
+**notmuch-search(1)**,
+**notmuch-search-terms(7)**,
+**notmuch-show(1)**,
+**notmuch-tag(1)**
diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst
index f79600d6..1a3dfe98 100644
--- a/doc/man1/notmuch-insert.rst
+++ b/doc/man1/notmuch-insert.rst
@@ -34,7 +34,8 @@ Supported options for **insert** include
     ``--folder=<``\ folder\ **>**
         Deliver the message to the specified folder, relative to the
         top-level directory given by the value of **database.path**. The
-        default is to deliver to the top-level directory.
+        default is the empty string, which means delivering to the
+        top-level directory.
 
     ``--create-folder``
         Try to create the folder named by the ``--folder`` option, if it
@@ -50,6 +51,29 @@ Supported options for **insert** include
     ``--no-hooks``
         Prevent hooks from being run.
 
+    ``--decrypt=(true|nostash|auto|false)``
+
+        If ``true`` and the message is encrypted, try to decrypt the
+        message while indexing, stashing any session keys discovered.
+        If ``auto``, and notmuch already knows about a session key for
+        the message, it will try decrypting using that session key but
+        will not try to access the user's secret keys.  If decryption
+        is successful, index the cleartext itself.  Either way, the
+        message is always stored to disk in its original form
+        (ciphertext).
+
+        ``nostash`` is the same as ``true`` except that it will not
+        stash newly-discovered session keys in the database.
+
+        Be aware that the 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
+        notmuch message index is adequately protected. DO NOT USE
+        ``--decrypt=true`` or ``--decrypt=nostash`` without
+        considering the security of your index.
+
+        See also ``index.decrypt`` in **notmuch-config(1)**.
+
 EXIT STATUS
 ===========
 
@@ -73,7 +97,14 @@ status of the **insert** command.
 SEE ALSO
 ========
 
-**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
-**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-reply(1)**,
-**notmuch-restore(1)**, **notmuch-search(1)**,
-**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
+**notmuch(1)**,
+**notmuch-config(1)**,
+**notmuch-count(1)**,
+**notmuch-dump(1)**,
+**notmuch-hooks(5)**,
+**notmuch-reply(1)**,
+**notmuch-restore(1)**,
+**notmuch-search(1)**,
+**notmuch-search-terms(7)**,
+**notmuch-show(1)**,
+**notmuch-tag(1)**
diff --git a/doc/man1/notmuch-new.rst b/doc/man1/notmuch-new.rst
index 6acfa112..3ddd4621 100644
--- a/doc/man1/notmuch-new.rst
+++ b/doc/man1/notmuch-new.rst
@@ -43,6 +43,24 @@ Supported options for **new** include
     ``--quiet``
         Do not print progress or results.
 
+    ``--decrypt=(true|nostash|auto|false)``
+
+        If ``true``, when encountering an encrypted message, try to
+        decrypt it while indexing, and stash any discovered session
+        keys.  If ``auto``, try to use any session key already known
+        to belong to this message, but do not attempt to use the
+        user's secret keys.  If decryption is successful, index the
+        cleartext of the message.
+
+        Be aware that the index is likely sufficient (and the session
+        key is certainly sufficient) to reconstruct the cleartext of
+        the message itself, so please ensure that the notmuch message
+        index is adequately protected.  DO NOT USE ``--decrypt=true``
+        or ``--decrypt=nostash`` without considering the security of
+        your index.
+
+        See also ``index.decrypt`` in **notmuch-config(1)**.
+
 EXIT STATUS
 ===========
 
@@ -54,7 +72,15 @@ This command supports the following special exit status code
 SEE ALSO
 ========
 
-**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
-**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
-**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
-**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
+**notmuch(1)**,
+**notmuch-config(1)**,
+**notmuch-count(1)**,
+**notmuch-dump(1)**,
+**notmuch-hooks(5)**,
+**notmuch-insert(1)**,
+**notmuch-reply(1)**,
+**notmuch-restore(1)**,
+**notmuch-search(1)**,
+**notmuch-search-terms(7)**,
+**notmuch-show(1)**,
+**notmuch-tag(1)**
diff --git a/doc/man1/notmuch-reindex.rst b/doc/man1/notmuch-reindex.rst
new file mode 100644
index 00000000..8b3083cf
--- /dev/null
+++ b/doc/man1/notmuch-reindex.rst
@@ -0,0 +1,63 @@
+===============
+notmuch-reindex
+===============
+
+SYNOPSIS
+========
+
+**notmuch** **reindex** [*option* ...] <*search-term*> ...
+
+DESCRIPTION
+===========
+
+Re-index all messages matching the search terms.
+
+See **notmuch-search-terms(7)** for details of the supported syntax for
+<*search-term*\ >.
+
+The **reindex** command searches for all messages matching the
+supplied search terms, and re-creates the full-text index on these
+messages using the supplied options.
+
+Supported options for **reindex** include
+
+    ``--decrypt=(true|nostash|auto|false)``
+
+        If ``true``, when encountering an encrypted message, try to
+        decrypt it while reindexing, stashing any session keys
+        discovered.  If ``auto``, and notmuch already knows about a
+        session key for the message, it will try decrypting using that
+        session key but will not try to access the user's secret keys.
+        If decryption is successful, index the cleartext itself.
+
+        ``nostash`` is the same as ``true`` except that it will not
+        stash newly-discovered session keys in the database.
+
+        If ``false``, notmuch reindex will also delete any stashed
+        session keys for all messages matching the search terms.
+
+        Be aware that the 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
+        notmuch message index is adequately protected. DO NOT USE
+        ``--decrypt=true`` or ``--decrypt=nostash`` without
+        considering the security of your index.
+
+        See also ``index.decrypt`` in **notmuch-config(1)**.
+
+SEE ALSO
+========
+
+**notmuch(1)**,
+**notmuch-config(1)**,
+**notmuch-count(1)**,
+**notmuch-dump(1)**,
+**notmuch-hooks(5)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-reply(1)**,
+**notmuch-restore(1)**,
+**notmuch-search(1)**,
+**notmuch-search-terms(7)**,
+**notmuch-show(1)**,
+**notmuch-tag(1)**
diff --git a/doc/man1/notmuch-reply.rst b/doc/man1/notmuch-reply.rst
index d73f8f1c..1b62e075 100644
--- a/doc/man1/notmuch-reply.rst
+++ b/doc/man1/notmuch-reply.rst
@@ -72,16 +72,26 @@ Supported options for **reply** include
             in this order, and copy values from the first that contains
             something other than only the user's addresses.
 
-    ``--decrypt``
-        Decrypt any MIME encrypted parts found in the selected content
-        (ie. "multipart/encrypted" parts). Status of the decryption will
-        be reported (currently only supported with --format=json and
-        --format=sexp) and on successful decryption the
-        multipart/encrypted part will be replaced by the decrypted
-        content.
+    ``--decrypt=(false|auto|true)``
 
-        Decryption expects a functioning **gpg-agent(1)** to provide any
-        needed credentials. Without one, the decryption will fail.
+        If ``true``, decrypt any MIME encrypted parts found in the
+        selected content (i.e., "multipart/encrypted" parts). Status
+        of the decryption will be reported (currently only supported
+        with --format=json and --format=sexp), and on successful
+        decryption the multipart/encrypted part will be replaced by
+        the decrypted content.
+
+        If ``auto``, and a session key is already known for the
+        message, then it will be decrypted, but notmuch will not try
+        to access the user's secret keys.
+
+        Use ``false`` to avoid even automatic decryption.
+
+        Non-automatic decryption expects a functioning
+        **gpg-agent(1)** to provide any needed credentials. Without
+        one, the decryption will likely fail.
+
+        Default: ``auto``
 
 See **notmuch-search-terms(7)** for details of the supported syntax for
 <search-terms>.
@@ -108,7 +118,15 @@ This command supports the following special exit status codes
 SEE ALSO
 ========
 
-**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
-**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
-**notmuch-new(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
-**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
+**notmuch(1)**,
+**notmuch-config(1)**,
+**notmuch-count(1)**,
+**notmuch-dump(1)**,
+**notmuch-hooks(5)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-restore(1)**,
+**notmuch-search(1)**,
+**notmuch-search-terms(7)**,
+**notmuch-show(1)**,
+**notmuch-tag(1)**
diff --git a/doc/man1/notmuch-restore.rst b/doc/man1/notmuch-restore.rst
index cb68bc8a..b578af1f 100644
--- a/doc/man1/notmuch-restore.rst
+++ b/doc/man1/notmuch-restore.rst
@@ -62,14 +62,15 @@ Supported options for **restore** include
 
         **properties**
 
-          Output per-message (key,value) metadata.  Each line starts
+          Restore per-message (key,value) metadata.  Each line starts
           with "#= ", followed by a message id, and a space separated
-          list of key=value pairs.  pair.  Ids, keys and values are
-          hex encoded if needed.
+          list of key=value pairs.  Ids, keys and values are hex
+          encoded if needed.  See **notmuch-properties(7)** for more
+          details.
 
         **tags**
 
-          Output per-message metadata, namely tags. See *format* above
+          Restore per-message metadata, namely tags. See *format* above
           for more details.
 
       The default is to restore all available types of data.  The
@@ -89,7 +90,16 @@ standard input.
 SEE ALSO
 ========
 
-**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
-**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
-**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-search(1)**,
-**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
+**notmuch(1)**,
+**notmuch-config(1)**,
+**notmuch-count(1)**,
+**notmuch-dump(1)**,
+**notmuch-hooks(5)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-properties(7)**,
+**notmuch-reply(1)**,
+**notmuch-search(1)**,
+**notmuch-search-terms(7)**,
+**notmuch-show(1)**,
+**notmuch-tag(1)**
diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst
index 4e660a6f..67c1ce90 100644
--- a/doc/man1/notmuch-search.rst
+++ b/doc/man1/notmuch-search.rst
@@ -42,7 +42,9 @@ Supported options for **search** include
             the search terms. The summary includes the thread ID, date,
             the number of messages in the thread (both the number
             matched and the total number), the authors of the thread and
-            the subject.
+	    the subject. In the case where a thread contains multiple files for
+	    some messages, the total number of files is printed in parentheses
+	    (see below for an example).
 
         **threads**
             Output the thread IDs of all threads with any message
@@ -135,6 +137,19 @@ Supported options for **search** include
         prefix. The prefix matches messages based on filenames. This
         option filters filenames of the matching messages.
 
+EXAMPLE
+=======
+
+The following shows an example of the summary output format, with one
+message having multiple filenames.
+
+::
+
+  % notmuch search date:today.. and tag:bad-news
+  thread:0000000000063c10 Today [1/1] Some Persun; To the bone (inbox unread)
+  thread:0000000000063c25 Today [1/1(2)] Ann Other; Bears (inbox unread)
+  thread:0000000000063c00 Today [1/1] A Thurd; Bites, stings, sad feelings (inbox unread)
+
 EXIT STATUS
 ===========
 
@@ -149,8 +164,16 @@ This command supports the following special exit status codes
 SEE ALSO
 ========
 
-**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
-**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
-**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
-**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
+**notmuch(1)**,
+**notmuch-config(1)**,
+**notmuch-count(1)**,
+**notmuch-dump(1)**,
+**notmuch-hooks(5)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-reply(1)**,
+**notmuch-restore(1)**,
+**notmuch-search-terms(7)**,
+**notmuch-show(1)**,
+**notmuch-tag(1)**
 **notmuch-address(1)**
diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
index 9eb5198d..7d2b38cb 100644
--- a/doc/man1/notmuch-show.rst
+++ b/doc/man1/notmuch-show.rst
@@ -115,18 +115,27 @@ Supported options for **show** include
         supported with --format=json and --format=sexp), and the
         multipart/signed part will be replaced by the signed data.
 
-    ``--decrypt``
-        Decrypt any MIME encrypted parts found in the selected content
-        (ie. "multipart/encrypted" parts). Status of the decryption will
-        be reported (currently only supported with --format=json and
-        --format=sexp) and on successful decryption the
-        multipart/encrypted part will be replaced by the decrypted
-        content.
+    ``--decrypt=(false|auto|true)``
+        If ``true``, decrypt any MIME encrypted parts found in the
+        selected content (i.e. "multipart/encrypted" parts). Status of
+        the decryption will be reported (currently only supported
+        with --format=json and --format=sexp) and on successful
+        decryption the multipart/encrypted part will be replaced by
+        the decrypted content.
 
-        Decryption expects a functioning **gpg-agent(1)** to provide any
-        needed credentials. Without one, the decryption will fail.
+        If ``auto``, and a session key is already known for the
+        message, then it will be decrypted, but notmuch will not try
+        to access the user's keys.
 
-        Implies --verify.
+        Use ``false`` to avoid even automatic decryption.
+
+        Non-automatic decryption expects a functioning
+        **gpg-agent(1)** to provide any needed credentials. Without
+        one, the decryption will fail.
+
+        Note: ``true`` implies --verify.
+
+        Default: ``auto``
 
     ``--exclude=(true|false)``
         Specify whether to omit threads only matching
@@ -176,7 +185,15 @@ This command supports the following special exit status codes
 SEE ALSO
 ========
 
-**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
-**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
-**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
-**notmuch-search(1)**, **notmuch-search-terms(7)**, **notmuch-tag(1)**
+**notmuch(1)**,
+**notmuch-config(1)**,
+**notmuch-count(1)**,
+**notmuch-dump(1)**,
+**notmuch-hooks(5)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-reply(1)**,
+**notmuch-restore(1)**,
+**notmuch-search(1)**,
+**notmuch-search-terms(7)**,
+**notmuch-tag(1)**
diff --git a/doc/man1/notmuch-tag.rst b/doc/man1/notmuch-tag.rst
index 2e7e1d32..88e454ba 100644
--- a/doc/man1/notmuch-tag.rst
+++ b/doc/man1/notmuch-tag.rst
@@ -101,7 +101,15 @@ of the tag **space in tags**
 SEE ALSO
 ========
 
-**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
-**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
-**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
-**notmuch-search(1)**, **notmuch-search-terms(7)**, **notmuch-show(1)**,
+**notmuch(1)**,
+**notmuch-config(1)**,
+**notmuch-count(1)**,
+**notmuch-dump(1)**,
+**notmuch-hooks(5)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-reply(1)**,
+**notmuch-restore(1)**,
+**notmuch-search(1)**,
+**notmuch-search-terms(7)**,
+**notmuch-show(1)**,
diff --git a/doc/man1/notmuch.rst b/doc/man1/notmuch.rst
index cb350d1a..358f42e8 100644
--- a/doc/man1/notmuch.rst
+++ b/doc/man1/notmuch.rst
@@ -161,11 +161,22 @@ of notmuch.
 SEE ALSO
 ========
 
-**notmuch-address(1)**, **notmuch-compact(1)**, **notmuch-config(1)**,
-**notmuch-count(1)**, **notmuch-dump(1)**, **notmuch-hooks(5)**,
-**notmuch-insert(1)**, **notmuch-new(1)**, **notmuch-reply(1)**,
-**notmuch-restore(1)**, **notmuch-search(1)**,
-**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
+**notmuch-address(1)**,
+**notmuch-compact(1)**,
+**notmuch-config(1)**,
+**notmuch-count(1)**,
+**notmuch-dump(1)**,
+**notmuch-hooks(5)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-properties(7)**,
+**notmuch-reindex(1)**,
+**notmuch-reply(1)**,
+**notmuch-restore(1)**,
+**notmuch-search(1)**,
+**notmuch-search-terms(7)**,
+**notmuch-show(1)**,
+**notmuch-tag(1)**
 
 The notmuch website: **https://notmuchmail.org**
 
diff --git a/doc/man5/notmuch-hooks.rst b/doc/man5/notmuch-hooks.rst
index 3a72a80b..f07e4dab 100644
--- a/doc/man5/notmuch-hooks.rst
+++ b/doc/man5/notmuch-hooks.rst
@@ -49,7 +49,15 @@ The currently available hooks are described below.
 SEE ALSO
 ========
 
-**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
-**notmuch-dump(1)**, **notmuch-insert(1)**, **notmuch-new(1)**,
-**notmuch-reply(1)**, **notmuch-restore(1)**, **notmuch-search(1)**,
-**notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
+**notmuch(1)**,
+**notmuch-config(1)**,
+**notmuch-count(1)**,
+**notmuch-dump(1)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-reply(1)**,
+**notmuch-restore(1)**,
+**notmuch-search(1)**,
+**notmuch-search-terms(7)**,
+**notmuch-show(1)**,
+**notmuch-tag(1)**
diff --git a/doc/man7/notmuch-properties.rst b/doc/man7/notmuch-properties.rst
new file mode 100644
index 00000000..07d36a1a
--- /dev/null
+++ b/doc/man7/notmuch-properties.rst
@@ -0,0 +1,125 @@
+==================
+notmuch-properties
+==================
+
+SYNOPSIS
+========
+
+**notmuch** **count** **property:**\ <*key*>=<*value*>
+
+**notmuch** **search** **property:**\ <*key*>=<*value*>
+
+**notmuch** **show** **property:**\ <*key*>=<*value*>
+
+**notmuch** **reindex** **property:**\ <*key*>=<*value*>
+
+**notmuch** **tag** +<*tag*> **property:**\ <*key*>=<*value*>
+
+
+**notmuch** **dump** **--include=properties**
+
+**notmuch** **restore** **--include=properties**
+
+DESCRIPTION
+===========
+
+Several notmuch commands can search for, modify, add or remove
+properties associated with specific messages.  Properties are
+key/value pairs, and a message can have more than one key/value pair
+for the same key.
+
+While users can select based on a specific property in their search
+terms with the prefix **property:**, the notmuch command-line
+interface does not provide mechanisms for modifying properties
+directly to the user.
+
+Instead, message properties are expected to be set and used
+programmatically, according to logic in notmuch itself, or in
+extensions to it.
+
+Extensions to notmuch which make use of properties are encouraged to
+report the specific properties used to the upstream notmuch project,
+as a way of avoiding collisions in the property namespace.
+
+CONVENTIONS
+===========
+
+Any property with a key that starts with "index." will be removed (and
+possibly re-set) upon reindexing (see **notmuch-reindex(1)**).
+
+MESSAGE PROPERTIES
+==================
+
+The following properties are set by notmuch internally in the course
+of its normal activity.
+
+**index.decryption**
+
+    If a message contains encrypted content, and notmuch tries to
+    decrypt that content during indexing, it will add the property
+    ``index.decryption=success`` when the cleartext was successfully
+    indexed.  If notmuch attempts to decrypt any part of a message
+    during indexing and that decryption attempt fails, it will add the
+    property ``index.decryption=failure`` to the message.
+
+    Note that it's possible for a single message to have both
+    ``index.decryption=success`` and ``index.decryption=failure``.
+    Consider an encrypted e-mail message that contains another
+    encrypted e-mail message as an attachment -- if the outer message
+    can be decrypted, but the attached part cannot, then both
+    properties will be set on the message as a whole.
+
+    If notmuch never tried to decrypt an encrypted message during
+    indexing (which is the default, see ``index.decrypt`` in
+    **notmuch-config(1)**), then this property will not be set on that
+    message.
+
+**session-key**
+
+    When **notmuch-show(1)** or **nomtuch-reply** encounters a message
+    with an encrypted part, if notmuch finds a ``session-key``
+    property associated with the message, it will try that stashed
+    session key for decryption.
+
+    If you do not want to use any stashed session keys that might be
+    present, you should pass those programs ``--decrypt=false``.
+
+    Using a stashed session key with "notmuch show" will speed up
+    rendering of long encrypted threads.  It also allows the user to
+    destroy the secret part of any expired encryption-capable subkey
+    while still being able to read any retained messages for which
+    they have stashed the session key.  This enables truly deletable
+    e-mail, since (once the session key and asymmetric subkey are both
+    destroyed) there are no keys left that can be used to decrypt any
+    copy of the original message previously stored by an adversary.
+
+    However, access to the stashed session key for an encrypted message
+    permits full byte-for-byte reconstruction of the cleartext
+    message.  This includes attachments, cryptographic signatures, and
+    other material that cannot be reconstructed from the index alone.
+
+    See ``index.decrypt`` in **notmuch-config(1)** for more
+    details about how to set notmuch's policy on when to store session
+    keys.
+
+    The session key should be in the ASCII text form produced by
+    GnuPG.  For OpenPGP, that consists of a decimal representation of
+    the hash algorithm used (identified by number from RFC 4880,
+    e.g. 9 means AES-256) followed by a colon, followed by a
+    hexadecimal representation of the algorithm-specific key.  For
+    example, an AES-128 key might be stashed in a notmuch property as:
+    ``session-key=7:14B16AF65536C28AF209828DFE34C9E0``.
+
+SEE ALSO
+========
+
+**notmuch(1)**,
+**notmuch-config(1)**,
+**notmuch-dump(1)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-reindex(1)**,
+**notmuch-reply(1)**,
+**notmuch-restore(1)**,
+**notmuch-show(1)**,
+***notmuch-search-terms(7)**
diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst
index 47cab48d..6d2bf62a 100644
--- a/doc/man7/notmuch-search-terms.rst
+++ b/doc/man7/notmuch-search-terms.rst
@@ -9,6 +9,8 @@ SYNOPSIS
 
 **notmuch** **dump** [--format=(batch-tag|sup)] [--] [--output=<*file*>] [--] [<*search-term*> ...]
 
+**notmuch** **reindex** [option ...] <*search-term*> ...
+
 **notmuch** **search** [option ...] <*search-term*> ...
 
 **notmuch** **show** [option ...] <*search-term*> ...
@@ -28,136 +30,124 @@ recipient headers.
 As a special case, a search string consisting of exactly a single
 asterisk ("\*") will match all messages.
 
+Search prefixes
+---------------
+
 In addition to free text, the following prefixes can be used to force
 terms to match against specific portions of an email, (where <brackets>
-indicate user-supplied values):
-
--  from:<name-or-address>
-
--  from:/<regex>/
-
--  to:<name-or-address>
-
--  subject:<word-or-quoted-phrase>
-
--  subject:/<regex>/
-
--  attachment:<word>
-
--  mimetype:<word>
-
--  tag:<tag> (or is:<tag>)
-
--  id:<message-id>
-
--  thread:<thread-id>
+indicate user-supplied values).
 
--  folder:<maildir-folder>
+If notmuch is built with **Xapian Field Processors** (see below) some
+of the prefixes with <regex> forms can be also used to restrict the
+results to those whose value matches a regular expression (see
+**regex(7)**) delimited with //, for example::
 
--  path:<directory-path> or path:<directory-path>/**
-
--  date:<since>..<until>
-
--  lastmod:<initial-revision>..<final-revision>
-
--  query:<name>
-
--  property:<key>=<value>
-
-The **from:** prefix is used to match the name or address of the sender
-of an email message.
-
-The **to:** prefix is used to match the names or addresses of any
-recipient of an email message, (whether To, Cc, or Bcc).
+   notmuch search 'from:/bob@.*[.]example[.]com/'
 
-Any term prefixed with **subject:** will match only text from the
-subject of an email. Searching for a phrase in the subject is supported
-by including quotation marks around the phrase, immediately following
-**subject:**.
+from:<name-or-address> or from:/<regex>/
+    The **from:** prefix is used to match the name or address of
+    the sender of an email message.
 
-If notmuch is built with **Xapian Field Processors** (see below) the
-**from:** and **subject** prefix can be also used to restrict the
-results to those whose from/subject value matches a regular expression
-(see **regex(7)**) delimited with //.
+to:<name-or-address>
+    The **to:** prefix is used to match the names or addresses of any
+    recipient of an email message, (whether To, Cc, or Bcc).
 
-::
+subject:<word-or-quoted-phrase> or subject:/<regex>/
+    Any term prefixed with **subject:** will match only text from the
+    subject of an email. Searching for a phrase in the subject is
+    supported by including quotation marks around the phrase,
+    immediately following **subject:**.
 
-   notmuch search 'from:/bob@.*[.]example[.]com/'
+attachment:<word>
+    The **attachment:** prefix can be used to search for specific
+    filenames (or extensions) of attachments to email messages.
 
-The **attachment:** prefix can be used to search for specific filenames
-(or extensions) of attachments to email messages.
+mimetype:<word>
+    The **mimetype:** prefix will be used to match text from the
+    content-types of MIME parts within email messages (as specified by
+    the sender).
 
-The **mimetype:** prefix will be used to match text from the
-content-types of MIME parts within email messages (as specified by the
-sender).
+tag:<tag> or tag:/<regex>/ or is:<tag> or is:/<regex>/
+    For **tag:** and **is:** valid tag values include **inbox** and
+    **unread** by default for new messages added by **notmuch new** as
+    well as any other tag values added manually with **notmuch tag**.
 
-For **tag:** and **is:** valid tag values include **inbox** and
-**unread** by default for new messages added by **notmuch new** as well
-as any other tag values added manually with **notmuch tag**.
+id:<message-id> or mid:<message-id> or mid:/<regex>/
+    For **id:** and **mid:**, message ID values are the literal
+    contents of the Message-ID: header of email messages, but without
+    the '<', '>' delimiters.
 
-For **id:**, message ID values are the literal contents of the
-Message-ID: header of email messages, but without the '<', '>'
-delimiters.
+thread:<thread-id>
+    The **thread:** prefix can be used with the thread ID values that
+    are generated internally by notmuch (and do not appear in email
+    messages). These thread ID values can be seen in the first column
+    of output from **notmuch search**
 
-The **thread:** prefix can be used with the thread ID values that are
-generated internally by notmuch (and do not appear in email messages).
-These thread ID values can be seen in the first column of output from
-**notmuch search**
+path:<directory-path> or path:<directory-path>/** or path:/<regex>/
+    The **path:** prefix searches for email messages that are in
+    particular directories within the mail store. The directory must
+    be specified relative to the top-level maildir (and without the
+    leading slash). By default, **path:** matches messages in the
+    specified directory only. The "/\*\*" suffix can be used to match
+    messages in the specified directory and all its subdirectories
+    recursively. **path:""** matches messages in the root of the mail
+    store and, likewise, **path:\*\*** matches all messages.
 
-The **path:** prefix searches for email messages that are in
-particular directories within the mail store. The directory must be
-specified relative to the top-level maildir (and without the leading
-slash). By default, **path:** matches messages in the specified
-directory only. The "/\*\*" suffix can be used to match messages in
-the specified directory and all its subdirectories recursively.
-**path:""** matches messages in the root of the mail store and,
-likewise, **path:\*\*** matches all messages.
+    **path:** will find a message if *any* copy of that message is in
+    the specific directory.
 
-The **folder:** prefix searches for email messages by maildir or MH
-folder. For MH-style folders, this is equivalent to **path:**. For
-maildir, this includes messages in the "new" and "cur"
-subdirectories. The exact syntax for maildir folders depends on your
-mail configuration. For maildir++, **folder:""** matches the inbox
-folder (which is the root in maildir++), other folder names always
-start with ".", and nested folders are separated by "."s, such as
-**folder:.classes.topology**. For "file system" maildir, the inbox is
-typically **folder:INBOX** and nested folders are separated by
-slashes, such as **folder:classes/topology**.
+folder:<maildir-folder> or folder:/<regex>/
+    The **folder:** prefix searches for email messages by maildir or
+    MH folder. For MH-style folders, this is equivalent to
+    **path:**. For maildir, this includes messages in the "new" and
+    "cur" subdirectories. The exact syntax for maildir folders depends
+    on your mail configuration. For maildir++, **folder:""** matches
+    the inbox folder (which is the root in maildir++), other folder
+    names always start with ".", and nested folders are separated by
+    "."s, such as **folder:.classes.topology**. For "file system"
+    maildir, the inbox is typically **folder:INBOX** and nested
+    folders are separated by slashes, such as
+    **folder:classes/topology**.
 
-Both **path:** and **folder:** will find a message if *any* copy of
-that message is in the specific directory/folder.
+    **folder:** will find a message if *any* copy of that message is
+    in the specific folder.
 
-The **date:** prefix can be used to restrict the results to only
-messages within a particular time range (based on the Date: header) with
-a range syntax of:
-
-date:<since>..<until>
+date:<since>..<until> or date:<date>
+    The **date:** prefix can be used to restrict the results to only
+    messages within a particular time range (based on the Date:
+    header).
 
-See **DATE AND TIME SEARCH** below for details on the range expression,
-and supported syntax for <since> and <until> date and time expressions.
+    See **DATE AND TIME SEARCH** below for details on the range
+    expression, and supported syntax for <since> and <until> date and
+    time expressions.
 
-The time range can also be specified using timestamps with a syntax of:
+    The time range can also be specified using timestamps with a
+    syntax of:
 
-<initial-timestamp>..<final-timestamp>
+    <initial-timestamp>..<final-timestamp>
 
-Each timestamp is a number representing the number of seconds since
-1970-01-01 00:00:00 UTC.
+    Each timestamp is a number representing the number of seconds
+    since 1970-01-01 00:00:00 UTC.
 
-The **lastmod:** prefix can be used to restrict the result by the
-database revision number of when messages were last modified (tags
-were added/removed or filenames changed).  This is usually used in
-conjunction with the **--uuid** argument to **notmuch search**
-to find messages that have changed since an earlier query.
+lastmod:<initial-revision>..<final-revision>
+    The **lastmod:** prefix can be used to restrict the result by the
+    database revision number of when messages were last modified (tags
+    were added/removed or filenames changed). This is usually used in
+    conjunction with the **--uuid** argument to **notmuch search** to
+    find messages that have changed since an earlier query.
 
-The **query:** prefix allows queries to refer to previously saved
-queries added with **notmuch-config(1)**. Named queries are only
-available if notmuch is built with **Xapian Field Processors** (see
-below).
+query:<name>
+    The **query:** prefix allows queries to refer to previously saved
+    queries added with **notmuch-config(1)**. Named queries are only
+    available if notmuch is built with **Xapian Field Processors**
+    (see below).
 
-The **property:** prefix searches for messages with a particular
-<key>=<value> property pair. Properties are used internally by notmuch
-(and extensions) to add metadata to messages. A given key can be
-present on a given message with several different values.
+property:<key>=<value>
+    The **property:** prefix searches for messages with a particular
+    <key>=<value> property pair. Properties are used internally by
+    notmuch (and extensions) to add metadata to messages. A given key
+    can be present on a given message with several different values.
+    See **notmuch-properties(7)** for more details.
 
 Operators
 ---------
@@ -235,7 +225,7 @@ Boolean and Probabilistic Prefixes
 Xapian (and hence notmuch) prefixes are either **boolean**, supporting
 exact matches like "tag:inbox" or **probabilistic**, supporting a more
 flexible **term** based searching. Certain **special** prefixes are
-processed by notmuch in a way not stricly fitting either of Xapian's
+processed by notmuch in a way not strictly fitting either of Xapian's
 built in styles. The prefixes currently supported by notmuch are as
 follows.
 
@@ -253,7 +243,7 @@ In general Xapian distinguishes between lists of terms and
 **phrases**. Phrases are indicated by double quotes (but beware you
 probably need to protect those from your shell) and insist that those
 unstemmed words occur in that order. One useful, but initially
-surprising feature is that the following are equivalant ways to write
+surprising feature is that the following are equivalent ways to write
 the same phrase.
 
 - "a list of words"
@@ -262,7 +252,7 @@ the same phrase.
 - a.list.of.words
 
 Both parenthesised lists of terms and quoted phrases are ok with
-probabilisitic prefixes such as **to:**, **from:**, and **subject:**. In particular
+probabilistic prefixes such as **to:**, **from:**, and **subject:**. In particular
 
 ::
 
@@ -419,7 +409,17 @@ Currently the following features require field processor support:
 SEE ALSO
 ========
 
-**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
-**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
-**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
-**notmuch-search(1)**, **notmuch-show(1)**, **notmuch-tag(1)**
+**notmuch(1)**,
+**notmuch-config(1)**,
+**notmuch-count(1)**,
+**notmuch-dump(1)**,
+**notmuch-hooks(5)**,
+**notmuch-insert(1)**,
+**notmuch-new(1)**,
+**notmuch-reindex(1)**,
+**notmuch-properties(1)**,
+***notmuch-reply(1)**,
+**notmuch-restore(1)**,
+**notmuch-search(1)**,
+***notmuch-show(1)**,
+**notmuch-tag(1)**