X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=doc%2Fman1%2Fnotmuch-show.rst;h=becd3e79929023b089a9e5542c15380961aae58f;hp=ad72a740252f126443fd9aa3382ba4952b68b250;hb=3d0fd40eb0eca54fd05460203ae754c63f633d69;hpb=99407db25cbd44f915fb33708c497bc375ff63de diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst index ad72a740..becd3e79 100644 --- a/doc/man1/notmuch-show.rst +++ b/doc/man1/notmuch-show.rst @@ -71,7 +71,7 @@ Supported options for **show** include http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html - **raw** (default if --part is given) + **raw** (default if ``--part`` is given) Write the raw bytes of the given MIME part of a message to standard out. For this format, it is an error to specify a query that matches more than one message. @@ -105,40 +105,68 @@ Supported options for **show** include ``--verify`` Compute and report the validity of any MIME cryptographic - signatures found in the selected content (ie. "multipart/signed" + signatures found in the selected content (e.g., "multipart/signed" parts). Status of the signature will be reported (currently only - supported with --format=json and --format=sexp), and the + supported with ``--format=json`` and ``--format=sexp``), and the multipart/signed part will be replaced by the signed data. - ``--decrypt=(false|auto|true)`` - If ``true``, decrypt any MIME encrypted parts found in the - selected content (i.e. "multipart/encrypted" parts). Status of - the decryption will be reported (currently only supported - with --format=json and --format=sexp) and on successful - decryption the multipart/encrypted part will be replaced by - the decrypted content. - - If ``auto``, and a session key is already known for the - message, then it will be decrypted, but notmuch will not try - to access the user's keys. - - Use ``false`` to avoid even automatic decryption. - - Non-automatic decryption expects a functioning - **gpg-agent(1)** to provide any needed credentials. Without - one, the decryption will fail. - - Note: ``true`` implies --verify. - - Default: ``auto`` +``--decrypt=(false|auto|true|stash)`` + If ``true``, decrypt any MIME encrypted parts found in the + selected content (e.g., "multipart/encrypted" parts). Status of + the decryption will be reported (currently only supported + with ``--format=json`` and ``--format=sexp``) and on successful + decryption the multipart/encrypted part will be replaced by + the decrypted content. + + ``stash`` behaves like ``true``, but upon successful decryption it + will also stash the message's session key in the database, and + index the cleartext of the message, enabling automatic decryption + in the future. + + If ``auto``, and a session key is already known for the + message, then it will be decrypted, but notmuch will not try + to access the user's keys. + + Use ``false`` to avoid even automatic decryption. + + Non-automatic decryption (``stash`` or ``true``, in the absence of + a stashed session key) expects a functioning **gpg-agent(1)** to + provide any needed credentials. Without one, the decryption will + fail. + + Note: setting either ``true`` or ``stash`` here implies + ``--verify``. + + Here is a table that summarizes each of these policies: + + +------------------------+-------+------+------+-------+ + | | false | auto | true | stash | + +========================+=======+======+======+=======+ + | Show cleartext if | | X | X | X | + | session key is | | | | | + | already known | | | | | + +------------------------+-------+------+------+-------+ + | Use secret keys to | | | X | X | + | show cleartext | | | | | + +------------------------+-------+------+------+-------+ + | Stash any newly | | | | X | + | recovered session keys,| | | | | + | reindexing message if | | | | | + | found | | | | | + +------------------------+-------+------+------+-------+ + + Note: ``--decrypt=stash`` requires write access to the database. + Otherwise, ``notmuch show`` operates entirely in read-only mode. + + Default: ``auto`` ``--exclude=(true|false)`` - Specify whether to omit threads only matching search.tag\_exclude + Specify whether to omit threads only matching search.exclude\_tags from the search results (the default) or not. In either case the excluded message will be marked with the exclude flag (except when output=mbox when there is nowhere to put the flag). - If --entire-thread is specified then complete threads are returned + If ``--entire-thread`` is specified then complete threads are returned regardless (with the excluded flag being set when appropriate) but threads that only match in an excluded message are not returned when ``--exclude=true.`` @@ -148,18 +176,19 @@ Supported options for **show** include ``--body=(true|false)`` If true (the default) **notmuch show** includes the bodies of the messages in the output; if false, bodies are omitted. - ``--body=false`` is only implemented for the json and sexp formats - and it is incompatible with ``--part > 0.`` + ``--body=false`` is only implemented for the text, json and sexp + formats and it is incompatible with ``--part > 0.`` This is useful if the caller only needs the headers as body-less output is much faster and substantially smaller. ``--include-html`` - Include "text/html" parts as part of the output (currently only - supported with --format=json and --format=sexp). By default, - unless ``--part=N`` is used to select a specific part or - ``--include-html`` is used to include all "text/html" parts, no - part with content type "text/html" is included in the output. + Include "text/html" parts as part of the output (currently + only supported with ``--format=text``, ``--format=json`` and + ``--format=sexp``). By default, unless ``--part=N`` is used to + select a specific part or ``--include-html`` is used to include all + "text/html" parts, no part with content type "text/html" is included + in the output. A common use of **notmuch show** is to display a single thread of email messages. For this, use a search term of "thread:" as can be