X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=doc%2Fman1%2Fnotmuch-insert.rst;h=86e2f567348ba5920c972a967b7e936c35e34d82;hp=478845150e016e1c82cb590585d40491aeb603e6;hb=HEAD;hpb=99407db25cbd44f915fb33708c497bc375ff63de diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst index 47884515..e05bd0b5 100644 --- a/doc/man1/notmuch-insert.rst +++ b/doc/man1/notmuch-insert.rst @@ -1,3 +1,5 @@ +.. _notmuch-insert(1): + ============== notmuch-insert ============== @@ -12,12 +14,12 @@ DESCRIPTION **notmuch insert** reads a message from standard input and delivers it into the maildir directory given by configuration option -**database.path**, then incorporates the message into the notmuch +:nmconfig:`database.mail_root`, then incorporates the message into the notmuch database. It is an alternative to using a separate tool to deliver the -message then running **notmuch new** afterwards. +message then running :any:`notmuch-new(1)` afterwards. The new message will be tagged with the tags specified by the -**new.tags** configuration option, then by operations specified on the +:nmconfig:`new.tags` configuration option, then by operations specified on the command-line: tags prefixed by '+' are added while those prefixed by '-' are removed. @@ -25,52 +27,75 @@ 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. -The **insert** command supports hooks. See **notmuch-hooks(5)** for +The **insert** command supports hooks. See :any:`notmuch-hooks(5)` for more details on hooks. Option arguments must appear before any tag operation arguments. 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 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 - 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. - -``--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)**. +.. program:: insert + +.. option:: --folder= + + Deliver the message to the specified folder, relative to the + top-level directory given by the value of :nmconfig:`database.mail_root`. The + default is the empty string, which means delivering to the + top-level directory. + +.. option:: --create-folder + + Try to create the folder named by the ``--folder`` option, if it + does not exist. Otherwise the folder must already exist for mail + delivery to succeed. + +.. option:: --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. + +.. option:: --no-hooks + + Prevent hooks from being run. + +.. option:: --world-readable + + When writing mail to the mailbox, allow it to be read by users + other than the current user. Note that this does not override + umask. By default, delivered mail is only readable by the current + user. + +.. option:: --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 :nmconfig:`index.decrypt` in :any:`notmuch-config(1)`. + +CONFIGURATION +============= + +Indexing is influenced by the configuration options +:nmconfig:`index.decrypt` and :nmconfig:`index.header.\`. Tagging +is controlled by options :nmconfig:`new.tags` and +:nmconfig:`maildir.synchronize_flags`. See +:any:`notmuch-config(1)` for details. EXIT STATUS =========== @@ -95,14 +120,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)** +:any:`notmuch(1)`, +:any:`notmuch-config(1)`, +:any:`notmuch-count(1)`, +:any:`notmuch-dump(1)`, +:any:`notmuch-hooks(5)`, +:any:`notmuch-reply(1)`, +:any:`notmuch-restore(1)`, +:any:`notmuch-search(1)`, +:any:`notmuch-search-terms(7)`, +:any:`notmuch-show(1)`, +:any:`notmuch-tag(1)`