cli/insert: add --try-decrypt=(true|false)

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

diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst
index 2be1a7b8841c9a7039f15ad15a46ff396bc7ad7c..e2bf37d04c79e49f6a8127bf36949a84470d2f86 100644 (file)
--- a/doc/man1/notmuch-insert.rst
+++ b/doc/man1/notmuch-insert.rst
@@ -25,6 +25,9 @@ If the new message is a duplicate of an existing message in the database
 (it has same Message-ID), it will be added to the maildir folder and
 notmuch database, but the tags will not be changed.
 
 (it has same Message-ID), it will be added to the maildir folder and
 notmuch database, but the tags will not be changed.
 

+The **insert** command supports hooks. See **notmuch-hooks(5)** for
+more details on hooks.
+

 Option arguments must appear before any tag operation arguments.
 Supported options for **insert** include
 
 Option arguments must appear before any tag operation arguments.
 Supported options for **insert** include
 


@@ -38,21 +41,60 @@ Supported options for **insert** include
         does not exist. Otherwise the folder must already exist for mail
         delivery to succeed.
 
         does not exist. Otherwise the folder must already exist for mail
         delivery to succeed.
 

+    ``--keep``
+        Keep the message file if indexing fails, and keep the message
+        indexed if applying tags or maildir flag synchronization
+        fails. Ignore these errors and return exit status 0 to
+        indicate successful mail delivery.
+
+    ``--no-hooks``
+        Prevent hooks from being run.
+
+    ``--try-decrypt=(true|false)``
+
+        If true and the message is encrypted, try to decrypt the
+        message while indexing.  If decryption is successful, index
+        the cleartext itself.  Either way, the message is always
+        stored to disk in its original form (ciphertext).  Be aware
+        that the index is likely sufficient to reconstruct the
+        cleartext of the message itself, so please ensure that the
+        notmuch message index is adequately protected. DO NOT USE
+        ``--try-decrypt=true`` without considering the security of
+        your index.
+
+        See also ``index.try_decrypt`` in **notmuch-config(1)**.
+

 EXIT STATUS
 ===========
 
 EXIT STATUS
 ===========
 

-This command returns exit status 0 if the message was successfully added
-to the mail directory, even if the message could not be indexed and
-added to the notmuch database. In the latter case, a warning will be
-printed to standard error but the message file will be left on disk.
+This command returns exit status 0 on successful mail delivery,
+non-zero otherwise. The default is to indicate failed mail delivery on
+any errors, including message file delivery to the filesystem, message
+indexing to Notmuch database, changing tags, and synchronizing tags to
+maildir flags. The ``--keep`` option may be used to settle for
+successful message file delivery.
+
+This command supports the following special exit status code for
+errors most likely to be temporary in nature, e.g. failure to get a
+database write lock.
+
+``75 (EX_TEMPFAIL)``
+    A temporary failure occurred; the user is invited to retry.

 
 

-If the message could not be written to disk then a non-zero exit status
-is returned.
+The exit status of the **post-insert** hook does not affect the exit
+status of the **insert** command.

 
 SEE ALSO
 ========
 
 
 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)**