X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=doc%2Fman1%2Fnotmuch-show.rst;h=becd3e79929023b089a9e5542c15380961aae58f;hp=c4518ec821e62c5bd1e2072cbc687eb093b55756;hb=HEAD;hpb=56871c628bea5a86feea5b2bc704661bbe02cccc diff --git a/doc/man1/notmuch-show.rst b/doc/man1/notmuch-show.rst index c4518ec8..c13d94de 100644 --- a/doc/man1/notmuch-show.rst +++ b/doc/man1/notmuch-show.rst @@ -1,3 +1,5 @@ +.. _notmuch-show(1): + ============ notmuch-show ============ @@ -12,7 +14,7 @@ DESCRIPTION Shows all messages matching the search terms. -See **notmuch-search-terms(7)** for details of the supported syntax for +See :any:`notmuch-search-terms(7)` for details of the supported syntax for . The messages will be grouped and sorted based on the threading (all @@ -23,145 +25,223 @@ post-processor (such as the emacs interface to notmuch). Supported options for **show** include - ``--entire-thread=(true|false)`` - If true, **notmuch show** outputs all messages in the thread of - any message matching the search terms; if false, it outputs only - the matching messages. For ``--format=json`` and - ``--format=sexp`` this defaults to true. For other formats, this - defaults to false. - - ``--format=(text|json|sexp|mbox|raw)`` - - **text** (default for messages) - The default plain-text format has all text-content MIME - parts decoded. Various components in the output, - (**message**, **header**, **body**, **attachment**, and MIME - **part**), will be delimited by easily-parsed markers. Each - marker consists of a Control-L character (ASCII decimal 12), - the name of the marker, and then either an opening or - closing brace, ('{' or '}'), to either open or close the - component. For a multipart MIME message, these parts will be - nested. - - **json** - The output is formatted with Javascript Object Notation - (JSON). This format is more robust than the text format for - automated processing. The nested structure of multipart MIME - messages is reflected in nested JSON output. By default JSON - output includes all messages in a matching thread; that is, - by default, - - ``--format=json`` sets ``--entire-thread`` The caller can - disable this behaviour by setting ``--entire-thread=false`` - - **sexp** - The output is formatted as an S-Expression (sexp). This - format is more robust than the text format for automated - processing. The nested structure of multipart MIME messages - is reflected in nested S-Expression output. By default, - S-Expression output includes all messages in a matching - thread; that is, by default, - - ``--format=sexp`` sets ``--entire-thread`` The caller can - disable this behaviour by setting ``--entire-thread=false`` - - **mbox** - All matching messages are output in the traditional, Unix - mbox format with each message being prefixed by a line - beginning with "From " and a blank line separating each - message. Lines in the message content beginning with "From " - (preceded by zero or more '>' characters) have an additional - '>' character added. This reversible escaping 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) - 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. - - If the specified part is a leaf part, this outputs the - body of the part after performing content transfer - decoding (but no charset conversion). This is suitable for - saving attachments, for example. - - For a multipart or message part, the output includes the - part headers as well as the body (including all child - parts). No decoding is performed because multipart and - message parts cannot have non-trivial content transfer - encoding. Consumers of this may need to implement MIME - decoding and similar functions. - - ``--format-version=N`` - Use the specified structured output format version. This is - intended for programs that invoke **notmuch(1)** internally. If - omitted, the latest supported version will be used. - - ``--part=N`` - Output the single decoded MIME part N of a single message. The - search terms must match only a single message. Message parts are - numbered in a depth-first walk of the message MIME structure, - and are identified in the 'json', 'sexp' or 'text' output - formats. - - Note that even a message with no MIME structure or a single - body part still has two MIME parts: part 0 is the whole - message (headers and body) and part 1 is just the body. - - ``--verify`` - Compute and report the validity of any MIME cryptographic - signatures found in the selected content (ie. "multipart/signed" - parts). Status of the signature will be reported (currently only - 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. - - Decryption expects a functioning **gpg-agent(1)** to provide any - needed credentials. Without one, the decryption will fail. - - Implies --verify. - - ``--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). - - 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.`` - - The default is ``--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.`` - - 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. - -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 -seen in the first column of output from the **notmuch search** command. +.. program:: show + +.. option:: --duplicate=N + + Output duplicate number N. The numbering starts from 1, and matches + the order used by :option:`search --duplicate` and + :option:`search --output=files ` + +.. option:: --entire-thread=(true|false) + + If true, **notmuch show** outputs all messages in the thread of + any message matching the search terms; if false, it outputs only + the matching messages. For ``--format=json`` and ``--format=sexp`` + this defaults to true. For other formats, this defaults to false. + +.. option:: --format=(text|json|sexp|mbox|raw) + + text (default for messages) + The default plain-text format has all text-content MIME parts + decoded. Various components in the output, (**message**, + **header**, **body**, **attachment**, and MIME **part**), will + be delimited by easily-parsed markers. Each marker consists of + a Control-L character (ASCII decimal 12), the name of the + marker, and then either an opening or closing brace, ('{' or + '}'), to either open or close the component. For a multipart + MIME message, these parts will be nested. + + json + The output is formatted with Javascript Object Notation + (JSON). This format is more robust than the text format for + automated processing. The nested structure of multipart MIME + messages is reflected in nested JSON output. By default JSON + output includes all messages in a matching thread; that is, by + default, ``--format=json`` sets ``--entire-thread``. The + caller can disable this behaviour by setting + ``--entire-thread=false``. The JSON output is always encoded + as UTF-8 and any message content included in the output will + be charset-converted to UTF-8. + + sexp + The output is formatted as the Lisp s-expression (sexp) + equivalent of the JSON format above. Objects are formatted as + property lists whose keys are keywords (symbols preceded by a + colon). True is formatted as ``t`` and both false and null are + formatted as ``nil``. As for JSON, the s-expression output is + always encoded as UTF-8. + + mbox + All matching messages are output in the traditional, Unix mbox + format with each message being prefixed by a line beginning + with "From " and a blank line separating each message. Lines + in the message content beginning with "From " (preceded by + zero or more '>' characters) have an additional '>' character + added. This reversible escaping 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) + 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. + + If the specified part is a leaf part, this outputs the body of + the part after performing content transfer decoding (but no + charset conversion). This is suitable for saving attachments, + for example. + + For a multipart or message part, the output includes the part + headers as well as the body (including all child parts). No + decoding is performed because multipart and message parts + cannot have non-trivial content transfer encoding. Consumers + of this may need to implement MIME decoding and similar + functions. + +.. option:: --format-version=N + + Use the specified structured output format version. This is + intended for programs that invoke :any:`notmuch(1)` internally. If + omitted, the latest supported version will be used. + +.. option:: --part=N + + Output the single decoded MIME part N of a single message. The + search terms must match only a single message. Message parts are + numbered in a depth-first walk of the message MIME structure, and + are identified in the 'json', 'sexp' or 'text' output formats. + + Note that even a message with no MIME structure or a single body + part still has two MIME parts: part 0 is the whole message + (headers and body) and part 1 is just the body. + +.. option:: --sort=(newest-first|oldest-first) + + This option can be used to present results in either chronological + order (**oldest-first**) or reverse chronological order + (**newest-first**). + + Only threads as a whole are reordered. Ordering of messages within + each thread will not be affected by this flag, since that order is + always determined by the thread's replies. + + By default, results will be displayed in reverse chronological + order, (that is, the newest results will be displayed first). + +.. option:: --offset=[-]N + + Skip displaying the first N results. With the leading '-', start + at the Nth result from the end. + +.. option:: --limit=N + + Limit the number of displayed results to N. + +.. option:: --verify + + Compute and report the validity of any MIME cryptographic + 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 + multipart/signed part will be replaced by the signed data. + +.. option:: --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 :manpage:`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`` + +.. option:: --exclude=(true|false) + + 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 + regardless (with the excluded flag being set when appropriate) but + threads that only match in an excluded message are not returned + when ``--exclude=true.`` + + The default is ``--exclude=true.`` + +.. option:: --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 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. + +.. option:: --include-html + + 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 seen in the first column of output from the +:any:`notmuch-search(1)` command. + +CONFIGURATION +============= + +Structured output (json / sexp) is influenced by the configuration +option :nmconfig:`show.extra_headers`. See +:any:`notmuch-config(1)` for details. EXIT STATUS =========== @@ -177,7 +257,15 @@ This command supports the following special exit status codes SEE ALSO ======== -**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**, -**notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**, -**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**, -**notmuch-search(1)**, **notmuch-search-terms(7)**, **notmuch-tag(1)** +:any:`notmuch(1)`, +:any:`notmuch-config(1)`, +:any:`notmuch-count(1)`, +:any:`notmuch-dump(1)`, +:any:`notmuch-hooks(5)`, +:any:`notmuch-insert(1)`, +:any:`notmuch-new(1)`, +:any:`notmuch-reply(1)`, +:any:`notmuch-restore(1)`, +:any:`notmuch-search(1)`, +:any:`notmuch-search-terms(7)`, +:any:`notmuch-tag(1)`