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
  30                  any  message  matching the search terms; if false, it outputs
  31                  only the matching  messages.  For  <b>--format=json</b>  and  <b>--for-</b>
  32                  <b>mat=sexp</b>  this  defaults  to  true.  For  other formats, this
  33                  defaults to false.
  34
  35           <b>--format=(text|json|sexp|mbox|raw)</b>
  36
  37               <b>text</b> <b>(default</b> <b>for</b> <b>messages)</b>
  38                      The default plain-text format has all  text-content  MIME
  39                      parts  decoded.  Various  components in the output, (<b>mes-</b>
  40                      <b>sage</b>, <b>header</b>, <b>body</b>, <b>attachment</b>, and MIME <b>part</b>),  will  be
  41                      delimited  by easily-parsed markers. Each marker consists
  42                      of a Control-L character (ASCII decimal 12), the name  of
  43                      the  marker, and then either an opening or closing brace,
  44                      (&apos;{&apos; or &apos;}&apos;), to either open or close the component.  For
  45                      a multipart MIME message, these parts will be nested.
  46
  47               <b>json</b>   The  output  is formatted with Javascript Object Notation
  48                      (JSON). This format is more robust than the  text  format
  49                      for  automated processing. The nested structure of multi‐
  50                      part MIME messages is reflected in nested JSON output. By
  51                      default  JSON  output includes all messages in a matching
  52                      thread;  that  is,   by   default,   <b>--format=json</b>   sets
  53                      <b>--entire-thread</b>. The caller can disable this behaviour by
  54                      setting <b>--entire-thread=false</b>.  The JSON output is always
  55                      encoded  as UTF-8 and any message content included in the
  56                      output will be charset-converted to UTF-8.
  57
  58               <b>sexp</b>   The output is formatted as the Lisp  s-expression  (sexp)
  59                      equivalent  of the JSON format above. Objects are format‐
  60                      ted as property lists whose keys  are  keywords  (symbols
  61                      preceded  by  a  colon).  True is formatted as <b>t</b> and both
  62                      false and null are formatted as <b>nil</b>.  As  for  JSON,  the
  63                      s-expression output is always encoded as UTF-8.
  64
  65               <b>mbox</b>   All matching messages are output in the traditional, Unix
  66                      mbox format with each message being prefixed  by  a  line
  67                      beginning  with  &quot;From &quot; and a blank line separating each
  68                      message. Lines in  the  message  content  beginning  with
  69                      &quot;From &quot; (preceded by zero or more &apos;&gt;&apos; characters) have an
  70                      additional &apos;&gt;&apos; character added. This reversible  escaping
  71                      is termed &quot;mboxrd&quot; format and described in detail here:
  72
  73                      <u>http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html</u>
  74
  75               <b>raw</b> <b>(default</b> <b>if</b> <b>--part</b> <b>is</b> <b>given)</b>
  76                      Write the raw bytes of the given MIME part of  a  message
  77                      to standard out. For this format, it is an error to spec‐
  78                      ify a query that matches more than one message.
  79
  80                      If the specified part is a leaf part,  this  outputs  the
  81                      body of the part after performing content transfer decod‐
  82                      ing (but no charset conversion).  This  is  suitable  for
  83                      saving attachments, for example.
  84
  85                      For  a multipart or message part, the output includes the
  86                      part headers as well as the  body  (including  all  child
  87                      parts).  No  decoding  is performed because multipart and
  88                      message parts cannot have  non-trivial  content  transfer
  89                      encoding.  Consumers  of  this may need to implement MIME
  90                      decoding and similar functions.
  91
  92           <b>--format-version=N</b>
  93                  Use the specified structured output format version.  This  is
  94                  intended  for  programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If
  95                  omitted, the latest supported version will be used.
  96
  97           <b>--part=N</b>
  98                  Output the single decoded MIME part N of  a  single  message.
  99                  The  search  terms  must match only a single message. Message
 100                  parts are numbered in a depth-first walk of the message  MIME
 101                  structure, and are identified in the &apos;json&apos;, &apos;sexp&apos; or &apos;text&apos;
 102                  output formats.
 103
 104                  Note that even a message with no MIME structure or  a  single
 105                  body  part still has two MIME parts: part 0 is the whole mes‐
 106                  sage (headers and body) and part 1 is just the body.
 107
 108           <b>--verify</b>
 109                  Compute and report the validity  of  any  MIME  cryptographic
 110                  signatures   found  in  the  selected  content  (ie.  &quot;multi‐
 111                  part/signed&quot; parts). Status of the signature will be reported
 112                  (currently  only  supported  with  --format=json  and  --for‐
 113                  mat=sexp), and the multipart/signed part will be replaced  by
 114                  the signed data.
 115
 116           <b>--decrypt</b>
 117                  Decrypt  any  MIME encrypted parts found in the selected con‐
 118                  tent (ie. &quot;multipart/encrypted&quot; parts). Status of the decryp‐
 119                  tion  will  be reported (currently only supported with --for‐
 120                  mat=json and --format=sexp) and on successful decryption  the
 121                  multipart/encrypted  part  will  be replaced by the decrypted
 122                  content.
 123
 124                  Decryption expects a functioning <b>gpg-agent</b>(1) to provide  any
 125                  needed credentials. Without one, the decryption will fail.
 126
 127                  Implies --verify.
 128
 129           <b>--exclude=(true|false)</b>
 130                  Specify    whether    to    omit    threads   only   matching
 131                  search.tag_exclude from the search results (the  default)  or
 132                  not.  In either case the excluded message will be marked with
 133                  the exclude flag  (except  when  output=mbox  when  there  is
 134                  nowhere to put the flag).
 135
 136                  If  --entire-thread  is  specified  then complete threads are
 137                  returned regardless (with the excluded flag  being  set  when
 138                  appropriate)  but threads that only match in an excluded mes‐
 139                  sage are not returned when <b>--exclude=true.</b>
 140
 141                  The default is <b>--exclude=true.</b>
 142
 143           <b>--body=(true|false)</b>
 144                  If true (the default) <b>notmuch</b> <b>show</b> includes the bodies of the
 145                  messages  in  the  output;  if  false,  bodies  are  omitted.
 146                  <b>--body=false</b> is only implemented for the json and  sexp  for‐
 147                  mats and it is incompatible with <b>--part</b> <b>&gt;</b> <b>0.</b>
 148
 149                  This  is  useful  if  the  caller  only  needs the headers as
 150                  body-less output is much faster and substantially smaller.
 151
 152           <b>--include-html</b>
 153                  Include &quot;text/html&quot; parts as part of  the  output  (currently
 154                  only  supported  with  --format=json  and  --format=sexp). By
 155                  default, unless <b>--part=N</b> is used to select a specific part or
 156                  <b>--include-html</b>  is  used to include all &quot;text/html&quot; parts, no
 157                  part with content type &quot;text/html&quot; is included in the output.
 158
 159        A common use of <b>notmuch</b> <b>show</b> is to display a  single  thread  of  email
 160        messages. For this, use a search term of &quot;thread:&lt;thread-id&gt;&quot; as can be
 161        seen in the first column of output from the <b>notmuch</b> <b>search</b> command.
 162 </pre>
 163
 164 <h2>EXIT STATUS</h2>
 165 <pre>
 166        This command supports the following special exit status codes
 167
 168        <b>20</b>     The requested format version is too old.
 169
 170        <b>21</b>     The requested format version is too new.
 171 </pre>
 172
 173 <h2>SEE ALSO</h2>
 174 <pre>
 175        <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>
 176        <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),
 177        <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>
 178        <a href='../notmuch-tag-1/'>much-tag</a>(1)
 179 </pre>
 180
 181 <h2>AUTHOR</h2>
 182 <pre>
 183        Carl Worth and many others
 184 </pre>
 185
 186 <h2>COPYRIGHT</h2>
 187 <pre>
 188        2014, Carl Worth and many others
 189 </pre>
 190
 191 <h2>0.20.1</h2>