manual pages for 0.19 (sans api page, for now)

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

diff --git a/manpages/notmuch-insert-1.mdwn b/manpages/notmuch-insert-1.mdwn
index fdaa55a3ce2bcea5ca24b0dbb60b6198b2bf60cc..56a2b2a746708b0b8dd69ea94c914bafd17fcd5a 100644 (file)
--- a/manpages/notmuch-insert-1.mdwn
+++ b/manpages/notmuch-insert-1.mdwn
@@ -26,29 +26,42 @@
        base (it has same Message-ID), it will be added to the  maildir  folder
        and notmuch database, but the tags will not be changed.
 
-       Option  arguments must appear before any tag operation arguments.  Sup‐
+       The  <b>insert</b>  command  supports  hooks.  See  <a href='../notmuch-hooks-5/'>notmuch-hooks</a>(5)  for more
+       details on hooks.
+
+       Option arguments must appear before any tag operation arguments.   Sup‐
        ported options for <b>insert</b> include
 
           <b>--folder=&lt;folder&gt;</b>
-                 Deliver the message to the specified folder, relative to  the
-                 top-level  directory given by the value of <b>database.path</b>. The
+                 Deliver  the message to the specified folder, relative to the
+                 top-level directory given by the value of <b>database.path</b>.  The
                  default is to deliver to the top-level directory.
 
           <b>--create-folder</b>
-                 Try to create the folder named by the <b>--folder</b> option, if  it
-                 does  not  exist. Otherwise the folder must already exist for
+                 Try  to create the folder named by the <b>--folder</b> option, if it
+                 does not exist. Otherwise the folder must already  exist  for
                  mail delivery to succeed.
+
+          <b>--keep</b> 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 indi‐
+                 cate succesful mail delivery.
+
+          <b>--no-hooks</b>
+                 Prevent hooks from being run.
 </pre>
 
 <h2>EXIT STATUS</h2>
 <pre>
-       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 succesful 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 <b>--keep</b> option may be used to settle  for  successful
+       message file delivery.
 
-       If the message could not be written to disk then a non-zero exit status
-       is returned.
+       The exit status of the <b>post-insert</b> hook does not affect the exit status
+       of the <b>insert</b> command.
 </pre>
 
 <h2>SEE ALSO</h2>
@@ -68,4 +81,4 @@
        2014, Carl Worth and many others
 </pre>
 
-<h2>0.18.1</h2>
+<h2>0.19</h2>