X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=manpages%2Fnotmuch-show-1.mdwn;h=0439d1a740725b093af3c446e9e840a41834fb4f;hb=0568dc66970180cbda48af10d27c49fb1a36805e;hp=4902b5acffdd090b0c3609e4fec8c0f43980d4dc;hpb=29654905e64093a5275f4a554527231072efccb9;p=notmuch-wiki diff --git a/manpages/notmuch-show-1.mdwn b/manpages/notmuch-show-1.mdwn index 4902b5a..0439d1a 100644 --- a/manpages/notmuch-show-1.mdwn +++ b/manpages/notmuch-show-1.mdwn @@ -70,7 +70,7 @@ is termed "mboxrd" format and described in detail here: 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 spec‐ ify a query that matches more than one message. @@ -105,40 +105,72 @@ --verify Compute and report the validity of any MIME cryptographic signa‐ - tures found in the selected content (ie. "multipart/signed" + tures 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 multi‐ + supported with --format=json and --format=sexp), and the multi‐ part/signed part will be replaced by the signed data. - --decrypt=(false|auto|true) + --decrypt=(false|auto|true|stash) If true, decrypt any MIME encrypted parts found in the selected - content (i.e. "multipart/encrypted" parts). Status of the + 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 + --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 + 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 expects a functioning gpg-agent(1) to - provide any needed credentials. Without one, the decryption will + Non-automatic decryption (stash or true, in the absence of a + stashed session key) expects a functioning gpg-agent(1) to pro‐ + vide any needed credentials. Without one, the decryption will fail. - Note: true implies --verify. + Note: setting either true or stash here implies --verify. + + Here is a table that summarizes each of these policies: + + ┌──────────────┬───────┬──────┬──────┬───────┐ + │ │ false │ auto │ true │ stash │ + ├──────────────┼───────┼──────┼──────┼───────┤ + │Show cleart‐ │ │ X │ X │ X │ + │ext if ses‐ │ │ │ │ │ + │sion key is │ │ │ │ │ + │already known │ │ │ │ │ + ├──────────────┼───────┼──────┼──────┼───────┤ + │Use secret │ │ │ X │ X │ + │keys to show │ │ │ │ │ + │cleartext │ │ │ │ │ + ├──────────────┼───────┼──────┼──────┼───────┤ + │Stash any │ │ │ │ X │ + │newly recov‐ │ │ │ │ │ + │ered session │ │ │ │ │ + │keys, rein‐ │ │ │ │ │ + │dexing mes‐ │ │ │ │ │ + │sage 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 - 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). + 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 + 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,16 +180,16 @@ --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 + 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. @@ -190,7 +222,7 @@

COPYRIGHT

-       2009-2018, Carl Worth and many others
+       2009-2020, Carl Worth and many others
-

0.26

+

0.30