git.cworth.org Git - notmuch-wiki/blob - manpages/notmuch-show-1.mdwn

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