cli/show: enable --decrypt=stash

[notmuch] / doc / man1 / notmuch-show.rst

diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst
index 3bc8d17b0af778a257b02affdabd39e3b3f07306..b2667537c220d88905d5c486af18016064644b13 100644 (file)
--- a/doc/man1/notmuch-show.rst
+++ b/doc/man1/notmuch-show.rst
@@ -110,22 +110,55 @@ 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.
-
-    If a session key is already known for the message, then it will be
-    decrypted automatically unless the user explicitly sets
-    ``--decrypt=false``.
-
-    Decryption expects a functioning **gpg-agent(1)** to provide any
-    needed credentials. Without one, the decryption will fail.
-
-    Implies --verify.
+``--decrypt=(false|auto|true|stash)``
+    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.
+
+    ``stash`` behaves like ``true``, but upon successful decryption it
+    will also stash the message's session key in the database, and
+    index the cleartext of the message, enabling automatic decryption
+    in the future.
+
+    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.
+
+    Use ``false`` to avoid even automatic decryption.
+
+    Non-automatic decryption (``stash`` or ``true``, in the absence of
+    a stashed session key) expects a functioning **gpg-agent(1)** to
+    provide any needed credentials. Without one, the decryption will
+    fail.
+
+    Note: setting either ``true`` or ``stash`` here implies
+    ``--verify``.
+
+    Here is a table that summarizes each of these policies:
+
+    +------------------------+-------+------+------+-------+
+    |                        | false | auto | true | stash |
+    +========================+=======+======+======+=======+
+    | Show cleartext if      |       |  X   |  X   |   X   |
+    | session key is         |       |      |      |       |
+    | already known          |       |      |      |       |
+    +------------------------+-------+------+------+-------+
+    | Use secret keys to     |       |      |  X   |   X   |
+    | show cleartext         |       |      |      |       |
+    +------------------------+-------+------+------+-------+
+    | Stash any newly        |       |      |      |   X   |
+    | recovered session keys,|       |      |      |       |
+    | reindexing message if  |       |      |      |       |
+    | found                  |       |      |      |       |
+    +------------------------+-------+------+------+-------+
+
+    Note: ``--decrypt=stash`` requires write access to the database.
+    Otherwise, ``notmuch show`` operates entirely in read-only mode.
+
+    Default: ``auto``
 
 ``--exclude=(true|false)``
     Specify whether to omit threads only matching search.tag\_exclude