git.cworth.org Git - notmuch/blob - doc/man1/notmuch-show.rst

   1 .. _notmuch-show(1):
   2
   3 ============
   4 notmuch-show
   5 ============
   6
   7 SYNOPSIS
   8 ========
   9
  10 **notmuch** **show** [*option* ...] <*search-term*> ...
  11
  12 DESCRIPTION
  13 ===========
  14
  15 Shows all messages matching the search terms.
  16
  17 See :any:`notmuch-search-terms(7)` for details of the supported syntax for
  18 <search-terms>.
  19
  20 The messages will be grouped and sorted based on the threading (all
  21 replies to a particular message will appear immediately after that
  22 message in date order). The output is not indented by default, but depth
  23 tags are printed so that proper indentation can be performed by a
  24 post-processor (such as the emacs interface to notmuch).
  25
  26 Supported options for **show** include
  27
  28 ``--entire-thread=(true|false)``
  29     If true, **notmuch show** outputs all messages in the thread of
  30     any message matching the search terms; if false, it outputs only
  31     the matching messages. For ``--format=json`` and ``--format=sexp``
  32     this defaults to true. For other formats, this defaults to false.
  33
  34 ``--format=(text|json|sexp|mbox|raw)``
  35     **text** (default for messages)
  36         The default plain-text format has all text-content MIME parts
  37         decoded. Various components in the output, (**message**,
  38         **header**, **body**, **attachment**, and MIME **part**), will
  39         be delimited by easily-parsed markers. Each marker consists of
  40         a Control-L character (ASCII decimal 12), the name of the
  41         marker, and then either an opening or closing brace, ('{' or
  42         '}'), to either open or close the component. For a multipart
  43         MIME message, these parts will be nested.
  44
  45     **json**
  46         The output is formatted with Javascript Object Notation
  47         (JSON). This format is more robust than the text format for
  48         automated processing. The nested structure of multipart MIME
  49         messages is reflected in nested JSON output. By default JSON
  50         output includes all messages in a matching thread; that is, by
  51         default, ``--format=json`` sets ``--entire-thread``. The
  52         caller can disable this behaviour by setting
  53         ``--entire-thread=false``.  The JSON output is always encoded
  54         as UTF-8 and any message content included in the output will
  55         be charset-converted to UTF-8.
  56
  57     **sexp**
  58         The output is formatted as the Lisp s-expression (sexp)
  59         equivalent of the JSON format above. Objects are formatted as
  60         property lists whose keys are keywords (symbols preceded by a
  61         colon). True is formatted as ``t`` and both false and null are
  62         formatted as ``nil``. As for JSON, the s-expression output is
  63         always encoded as UTF-8.
  64
  65     **mbox**
  66         All matching messages are output in the traditional, Unix mbox
  67         format with each message being prefixed by a line beginning
  68         with "From " and a blank line separating each message. Lines
  69         in the message content beginning with "From " (preceded by
  70         zero or more '>' characters) have an additional '>' character
  71         added. This reversible escaping is termed "mboxrd" format and
  72         described in detail here:
  73
  74             http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
  75
  76     **raw** (default if ``--part`` is given)
  77         Write the raw bytes of the given MIME part of a message to
  78         standard out. For this format, it is an error to specify a
  79         query that matches more than one message.
  80
  81         If the specified part is a leaf part, this outputs the body of
  82         the part after performing content transfer decoding (but no
  83         charset conversion). This is suitable for saving attachments,
  84         for example.
  85
  86         For a multipart or message part, the output includes the part
  87         headers as well as the body (including all child parts). No
  88         decoding is performed because multipart and message parts
  89         cannot have non-trivial content transfer encoding. Consumers
  90         of this may need to implement MIME decoding and similar
  91         functions.
  92
  93 ``--format-version=N``
  94     Use the specified structured output format version. This is
  95     intended for programs that invoke :any:`notmuch(1)` internally. If
  96     omitted, the latest supported version will be used.
  97
  98 ``--part=N``
  99     Output the single decoded MIME part N of a single message. The
 100     search terms must match only a single message. Message parts are
 101     numbered in a depth-first walk of the message MIME structure, and
 102     are identified in the 'json', 'sexp' or 'text' output formats.
 103
 104     Note that even a message with no MIME structure or a single body
 105     part still has two MIME parts: part 0 is the whole message
 106     (headers and body) and part 1 is just the body.
 107
 108 ``--verify``
 109     Compute and report the validity of any MIME cryptographic
 110     signatures found in the selected content (e.g., "multipart/signed"
 111     parts). Status of the signature will be reported (currently only
 112     supported with ``--format=json`` and ``--format=sexp``), and the
 113     multipart/signed part will be replaced by the signed data.
 114
 115 ``--decrypt=(false|auto|true|stash)``
 116     If ``true``, decrypt any MIME encrypted parts found in the
 117     selected content (e.g., "multipart/encrypted" parts). Status of
 118     the decryption will be reported (currently only supported
 119     with ``--format=json`` and ``--format=sexp``) and on successful
 120     decryption the multipart/encrypted part will be replaced by
 121     the decrypted content.
 122
 123     ``stash`` behaves like ``true``, but upon successful decryption it
 124     will also stash the message's session key in the database, and
 125     index the cleartext of the message, enabling automatic decryption
 126     in the future.
 127
 128     If ``auto``, and a session key is already known for the
 129     message, then it will be decrypted, but notmuch will not try
 130     to access the user's keys.
 131
 132     Use ``false`` to avoid even automatic decryption.
 133
 134     Non-automatic decryption (``stash`` or ``true``, in the absence of
 135     a stashed session key) expects a functioning :manpage:`gpg-agent(1)` to
 136     provide any needed credentials. Without one, the decryption will
 137     fail.
 138
 139     Note: setting either ``true`` or ``stash`` here implies
 140     ``--verify``.
 141
 142     Here is a table that summarizes each of these policies:
 143
 144     +------------------------+-------+------+------+-------+
 145     |                        | false | auto | true | stash |
 146     +========================+=======+======+======+=======+
 147     | Show cleartext if      |       |  X   |  X   |   X   |
 148     | session key is         |       |      |      |       |
 149     | already known          |       |      |      |       |
 150     +------------------------+-------+------+------+-------+
 151     | Use secret keys to     |       |      |  X   |   X   |
 152     | show cleartext         |       |      |      |       |
 153     +------------------------+-------+------+------+-------+
 154     | Stash any newly        |       |      |      |   X   |
 155     | recovered session keys,|       |      |      |       |
 156     | reindexing message if  |       |      |      |       |
 157     | found                  |       |      |      |       |
 158     +------------------------+-------+------+------+-------+
 159
 160     Note: ``--decrypt=stash`` requires write access to the database.
 161     Otherwise, ``notmuch show`` operates entirely in read-only mode.
 162
 163     Default: ``auto``
 164
 165 ``--exclude=(true|false)``
 166     Specify whether to omit threads only matching search.exclude\_tags
 167     from the search results (the default) or not. In either case the
 168     excluded message will be marked with the exclude flag (except when
 169     output=mbox when there is nowhere to put the flag).
 170
 171     If ``--entire-thread`` is specified then complete threads are returned
 172     regardless (with the excluded flag being set when appropriate) but
 173     threads that only match in an excluded message are not returned
 174     when ``--exclude=true.``
 175
 176     The default is ``--exclude=true.``
 177
 178 ``--body=(true|false)``
 179     If true (the default) **notmuch show** includes the bodies of the
 180     messages in the output; if false, bodies are omitted.
 181     ``--body=false`` is only implemented for the text, json and sexp
 182     formats and it is incompatible with ``--part > 0.``
 183
 184     This is useful if the caller only needs the headers as body-less
 185     output is much faster and substantially smaller.
 186
 187 ``--include-html``
 188     Include "text/html" parts as part of the output (currently
 189     only supported with ``--format=text``, ``--format=json`` and
 190     ``--format=sexp``). By default, unless ``--part=N`` is used to
 191     select a specific part or ``--include-html`` is used to include all
 192     "text/html" parts, no part with content type "text/html" is included
 193     in the output.
 194
 195 A common use of **notmuch show** is to display a single thread of
 196 email messages. For this, use a search term of "thread:<thread-id>" as
 197 can be seen in the first column of output from the
 198 :any:`notmuch-search(1)` command.
 199
 200 EXIT STATUS
 201 ===========
 202
 203 This command supports the following special exit status codes
 204
 205 ``20``
 206     The requested format version is too old.
 207
 208 ``21``
 209     The requested format version is too new.
 210
 211 SEE ALSO
 212 ========
 213
 214 :any:`notmuch(1)`,
 215 :any:`notmuch-config(1)`,
 216 :any:`notmuch-count(1)`,
 217 :any:`notmuch-dump(1)`,
 218 :any:`notmuch-hooks(5)`,
 219 :any:`notmuch-insert(1)`,
 220 :any:`notmuch-new(1)`,
 221 :any:`notmuch-reply(1)`,
 222 :any:`notmuch-restore(1)`,
 223 :any:`notmuch-search(1)`,
 224 :any:`notmuch-search-terms(7)`,
 225 :any:`notmuch-tag(1)`