debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-23 03:18:08 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
notmuch/doc/man1/notmuch-insert.rst

135 lines
4.4 KiB
ReStructuredText
Raw Normal View History

doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
.. _notmuch-insert(1):
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
==============
notmuch-insert
==============
SYNOPSIS
========
**notmuch** **insert** [option ...] [+<*tag*>|-<*tag*> ...]
DESCRIPTION
===========
**notmuch insert** reads a message from standard input and delivers it
into the maildir directory given by configuration option
doc: mail store is given by database.mail_root The mail store directory is given by database.mail_root, which can be different from database.path. However, notmuch-insert documentation was still referencing the latter as the provider of the maildir directory instead of the former.
2021-12-16 18:40:52 +01:00
**database.mail_root**, then incorporates the message into the notmuch
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
database. It is an alternative to using a separate tool to deliver the
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
message then running :any:`notmuch-new(1)` afterwards.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
The new message will be tagged with the tags specified by the
**new.tags** configuration option, then by operations specified on the
command-line: tags prefixed by '+' are added while those prefixed by '-'
are removed.
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.
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
The **insert** command supports hooks. See :any:`notmuch-hooks(5)` for
cli/insert: add post-insert hook The post-new hook might no longer be needed or run very often if notmuch insert is being used. Therefore a post-insert hook is needed (arguably pre-insert not so much, so don't add one). Also add the --no-hooks option to skip hooks.
2014-09-28 16:40:59 +02:00
more details on hooks.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
Option arguments must appear before any tag operation arguments.
Supported options for **insert** include
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
.. program:: insert
.. option:: --folder=<folder>
Deliver the message to the specified folder, relative to the
doc: mail store is given by database.mail_root The mail store directory is given by database.mail_root, which can be different from database.path. However, notmuch-insert documentation was still referencing the latter as the provider of the maildir directory instead of the former.
2021-12-16 18:40:52 +01:00
top-level directory given by the value of **database.mail_root**. The
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
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 ``index.decrypt`` in :any:`notmuch-config(1)`.
cli/insert: add --try-decrypt=(true|false) Enable override of the index.try_decrypt setting on a per-message basis when invoking "notmuch insert". We also update the documentation and tab completion, and add more tests.
2017-10-21 04:25:47 +02:00
doc: add configuration section to notmuch-insert(1) This is partially redudant given some existing cross references, but it is useful to have all of the config keys listed in one place, to help keep track of them if nothing else.
2022-02-06 14:38:16 +01:00
CONFIGURATION
=============
Indexing is influenced by the configuration options
:ref:`index.decrypt <index.decrypt>` and :ref:`index.header
<index.header>`. Tagging
is controlled by :ref:`new.tags <new.tags>` and
:ref:`maildir.synchronize_flags <maildir.synchronize_flags>`. See
:any:`notmuch-config(1)` for details.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
EXIT STATUS
===========
clean up spelling
2016-09-12 04:23:48 +02:00
This command returns exit status 0 on successful mail delivery,
cli/insert: require succesful message indexing for success status Add --keep option to keep any remaining stuff in index or file. We could distinguish between failures to index and failures to apply tags or maildir sync, but for simplicity just have one.
2014-10-03 23:18:59 +02:00
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.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
cli/insert: document the use of EX_TEMPFAIL
2016-12-07 12:27:12 +01:00
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)``
Fix orthography
2017-07-18 00:16:02 +02:00
A temporary failure occurred; the user is invited to retry.
cli/insert: document the use of EX_TEMPFAIL
2016-12-07 12:27:12 +01:00
cli/insert: add post-insert hook The post-new hook might no longer be needed or run very often if notmuch insert is being used. Therefore a post-insert hook is needed (arguably pre-insert not so much, so don't add one). Also add the --no-hooks option to skip hooks.
2014-09-28 16:40:59 +02:00
The exit status of the **post-insert** hook does not affect the exit
status of the **insert** command.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
SEE ALSO
========
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
: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)`
Reference in a new issue Copy permalink