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.
``--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``
- Decrypt any MIME encrypted parts found in the selected content
- (ie. "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 a session key is already known for the message, then it will be
- decrypted automatically unless the user explicitly sets
- ``--decrypt=false``.
-
- Decryption expects a functioning **gpg-agent(1)** to provide any
- needed credentials. Without one, the decryption will fail.
-
- Implies --verify.
+``--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.``
``--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:<thread-id>" as can be
projects / notmuch / blobdiff