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  de‐
  32               faults to true. For other formats, this defaults to false.
  33
  34        <b>--format=(text|json|sexp|mbox|raw)</b>
  35
  36               <b>text</b> <b>(default</b> <b>for</b> <b>messages)</b>
  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 <b>--en-</b>
  52                      <b>tire-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> <b>(default</b> <b>if</b> <b>--part</b> <b>is</b> <b>given)</b>
  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 in‐
  92               tended for programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If  omit‐
  93               ted, 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>--sort=(newest-first|oldest-first)</b>
 107               This option can be used to present results in either chronologi‐
 108               cal order (<b>oldest-first</b>) or reverse  chronological  order  (<b>new-</b>
 109               <b>est-first</b>).
 110
 111               Only  threads  as  a  whole are reordered.  Ordering of messages
 112               within each thread will not be affected by this flag, since that
 113               order is always determined by the thread&apos;s replies.
 114
 115               By  default,  results will be displayed in reverse chronological
 116               order, (that is, the newest results will be displayed first).
 117
 118        <b>--verify</b>
 119               Compute and report the validity of any MIME cryptographic signa‐
 120               tures  found  in  the selected content (e.g., &quot;multipart/signed&quot;
 121               parts). Status of the signature will be reported (currently only
 122               supported  with <b>--format=json</b> and <b>--format=sexp</b>), and the multi‐
 123               part/signed part will be replaced by the signed data.
 124
 125        <b>--decrypt=(false|auto|true|stash)</b>
 126               If <b>true</b>, decrypt any MIME encrypted parts found in the  selected
 127               content  (e.g.,  &quot;multipart/encrypted&quot; parts). Status of the de‐
 128               cryption will be reported (currently only supported with  <b>--for-</b>
 129               <b>mat=json</b>  and  <b>--format=sexp</b>)  and  on successful decryption the
 130               multipart/encrypted part will be replaced by the decrypted  con‐
 131               tent.
 132
 133               <b>stash</b>  behaves like <b>true</b>, but upon successful decryption it will
 134               also stash the message&apos;s session key in the database, and  index
 135               the  cleartext  of the message, enabling automatic decryption in
 136               the future.
 137
 138               If <b>auto</b>, and a session key is already  known  for  the  message,
 139               then  it  will  be decrypted, but notmuch will not try to access
 140               the user&apos;s keys.
 141
 142               Use <b>false</b> to avoid even automatic decryption.
 143
 144               Non-automatic decryption (<b>stash</b> or <b>true</b>, in  the  absence  of  a
 145               stashed  session key) expects a functioning <b>gpg-agent</b>(1) to pro‐
 146               vide any needed credentials. Without one,  the  decryption  will
 147               fail.
 148
 149               Note: setting either <b>true</b> or <b>stash</b> here implies <b>--verify</b>.
 150
 151               Here is a table that summarizes each of these policies:
 152
 153                        ┌──────────────┬───────┬──────┬──────┬───────┐
 154                        │              │ false │ auto │ true │ stash │
 155                        ├──────────────┼───────┼──────┼──────┼───────┤
 156                        │Show  cleart‐ │       │ X    │ X    │ X     │
 157                        │ext  if  ses‐ │       │      │      │       │
 158                        │sion  key  is │       │      │      │       │
 159                        │already known │       │      │      │       │
 160                        ├──────────────┼───────┼──────┼──────┼───────┤
 161                        │Use    secret │       │      │ X    │ X     │
 162                        │keys  to show │       │      │      │       │
 163                        │cleartext     │       │      │      │       │
 164                        ├──────────────┼───────┼──────┼──────┼───────┤
 165                        │Stash     any │       │      │      │ X     │
 166                        │newly  recov‐ │       │      │      │       │
 167                        │ered  session │       │      │      │       │
 168                        │keys,   rein‐ │       │      │      │       │
 169                        │dexing   mes‐ │       │      │      │       │
 170                        │sage if found │       │      │      │       │
 171                        └──────────────┴───────┴──────┴──────┴───────┘
 172
 173               Note:  <b>--decrypt=stash</b>  requires  write  access to the database.
 174               Otherwise, <b>notmuch</b> <b>show</b> operates entirely in read-only mode.
 175
 176               Default: <b>auto</b>
 177
 178        <b>--exclude=(true|false)</b>
 179               Specify  whether  to  omit  threads  only  matching   search.ex‐
 180               clude_tags  from the search results (the default) or not. In ei‐
 181               ther case the excluded message will be marked with  the  exclude
 182               flag  (except  when output=mbox when there is nowhere to put the
 183               flag).
 184
 185               If <b>--entire-thread</b> is specified then complete  threads  are  re‐
 186               turned  regardless (with the excluded flag being set when appro‐
 187               priate) but threads that only match in an excluded  message  are
 188               not returned when <b>--exclude=true.</b>
 189
 190               The default is <b>--exclude=true.</b>
 191
 192        <b>--body=(true|false)</b>
 193               If  true  (the  default) <b>notmuch</b> <b>show</b> includes the bodies of the
 194               messages  in  the  output;  if  false,   bodies   are   omitted.
 195               <b>--body=false</b>  is  only  implemented  for the text, json and sexp
 196               formats and it is incompatible with <b>--part</b> <b>&gt;</b> <b>0.</b>
 197
 198               This is useful if the caller only needs the headers as body-less
 199               output is much faster and substantially smaller.
 200
 201        <b>--include-html</b>
 202               Include  &quot;text/html&quot; parts as part of the output (currently only
 203               supported with <b>--format=text</b>, <b>--format=json</b> and  <b>--format=sexp</b>).
 204               By default, unless <b>--part=N</b> is used to select a specific part or
 205               <b>--include-html</b> is used to include all &quot;text/html&quot; parts, no part
 206               with content type &quot;text/html&quot; is included in the output.
 207
 208        A  common  use  of  <b>notmuch</b> <b>show</b> is to display a single thread of email
 209        messages. For this, use a search term of &quot;thread:&lt;thread-id&gt;&quot; as can be
 210        seen in the first column of output from the <a href='../notmuch-search-1/'>notmuch-search</a>(1) command.
 211 </pre>
 212
 213 <h2>CONFIGURATION</h2>
 214 <pre>
 215        Structured  output (json / sexp) is influenced by the configuration op‐
 216        tion show.extra_headers. See <a href='../notmuch-config-1/'>notmuch-config</a>(1) for details.
 217 </pre>
 218
 219 <h2>EXIT STATUS</h2>
 220 <pre>
 221        This command supports the following special exit status codes
 222
 223        <b>20</b>     The requested format version is too old.
 224
 225        <b>21</b>     The requested format version is too new.
 226 </pre>
 227
 228 <h2>SEE ALSO</h2>
 229 <pre>
 230        <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>
 231        <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),
 232        <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>
 233        <a href='../notmuch-tag-1/'>much-tag</a>(1)
 234 </pre>
 235
 236 <h2>AUTHOR</h2>
 237 <pre>
 238        Carl Worth and many others
 239 </pre>
 240
 241 <h2>COPYRIGHT</h2>
 242 <pre>
 243        2009-2022, Carl Worth and many others
 244 </pre>
 245
 246 <h2>0.35</h2>