X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=doc%2Fman1%2Fnotmuch-insert.rst;h=e05bd0b5730507bd1bed22ee30016713ed36d569;hb=HEAD;hp=67adf225ca9a17b76f3f0426ebbb1ef5308da0a1;hpb=ff4e81ac57dee5a62f35093c2966f931a7b7580c;p=notmuch diff --git a/doc/man1/notmuch-insert.rst b/doc/man1/notmuch-insert.rst index 67adf225..e05bd0b5 100644 --- a/doc/man1/notmuch-insert.rst +++ b/doc/man1/notmuch-insert.rst @@ -14,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 :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. @@ -33,52 +33,69 @@ 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. - -``--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. - -``--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 :any:`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 ===========