[notmuch-wiki] / manpages / notmuch-show-1.mdwn

<h1>NOTMUCH-SHOW(1)</h1>

<h2>NAME</h2>
<pre>
       notmuch-show - show messages matching the given search terms
</pre>

<h2>SYNOPSIS</h2>
<pre>
       <b>notmuch</b> <b>show</b> [<u>option</u> ...] &lt;<u>search-term</u>&gt; ...
</pre>

<h2>DESCRIPTION</h2>
<pre>
       Shows all messages matching the search terms.

       See  <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7)  for  details  of the supported syntax for
       &lt;search-terms&gt;.

       The messages will be grouped and sorted based  on  the  threading  (all
       replies to a particular message will appear immediately after that mes-
       sage in date order). The output is not indented by default,  but  depth
       tags  are  printed  so  that  proper  indentation can be performed by a
       post-processor (such as the emacs interface to notmuch).

       Supported options for <b>show</b> include

           <b>--entire-thread=(true|false)</b>

                  If true, <b>notmuch</b> <b>show</b> 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  --for-
                  mat=sexp  this  defaults  to  true.  For other formats, this
                  defaults to false.

           --format=(text|json|sexp|mbox|raw)

              <b>text</b> <b>(default</b> <b>for</b> <b>messages)</b>

                     The default plain-text format has all  text-content  MIME
                     parts  decoded.  Various  components in the output, (<b>mes-</b>
                     <b>sage</b>, <b>header</b>, <b>body</b>, <b>attachment</b>, and MIME <b>part</b>),  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,
                     (&apos;{&apos; or &apos;}&apos;), to either open or close the component.  For
                     a multipart MIME message, these parts will be nested.

              <b>json</b>

                     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 multi-
                     part 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.

              <b>sexp</b>

                     The output is formatted as the Lisp  s-expression  (sexp)
                     equivalent  of the JSON format above. Objects are format-
                     ted 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.

              <b>mbox</b>

                     All matching messages are output in the traditional, Unix
                     mbox format with each message being prefixed  by  a  line
                     beginning  with  &quot;From &quot; and a blank line separating each
                     message. Lines in  the  message  content  beginning  with
                     &quot;From &quot; (preceded by zero or more &apos;&gt;&apos; characters) have an
                     additional &apos;&gt;&apos; character added. This reversible  escaping
                     is termed &quot;mboxrd&quot; format and described in detail here:

                     <u>http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html</u>

              <b>raw</b> <b>(default</b> <b>if</b> <b>--part</b> <b>is</b> <b>given)</b>

                     Write the raw bytes of the given MIME part of  a  message
                     to standard out. For this format, it is an error to spec-
                     ify 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 decod-
                     ing (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.

           <b>--format-version=N</b>

                  Use the specified structured output format version. This  is
                  intended  for programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If
                  omitted, the latest supported version will be used.

           <b>--part=N</b>

                  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  &apos;json&apos;, &apos;sexp&apos; or
                  &apos;text&apos; 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 mes-
                  sage (headers and body) and part 1 is just the body.

           <b>--verify</b>

                  Compute and report the validity of  any  MIME  cryptographic
                  signatures  found  in  the  selected  content  (ie.  &quot;multi-
                  part/signed&quot;  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.

           <b>--decrypt</b>

                  Decrypt  any MIME encrypted parts found in the selected con-
                  tent  (ie.  &quot;multipart/encrypted&quot;  parts).  Status  of   the
                  decryption  will  be reported (currently only supported with
                  --format=json and --format=sexp) and on  successful  decryp-
                  tion  the  multipart/encrypted  part will be replaced by the
                  decrypted content.

                  Decryption expects a functioning <b>gpg-agent</b>(1) to provide any
                  needed credentials. Without one, the decryption will fail.

                  Implies --verify.

           <b>--exclude=(true|false)</b>

                  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 mes-
                  sage are not returned when --exclude=true.

                  The default is --exclude=true.

           <b>--body=(true|false)</b>

                  If true (the default) <b>notmuch</b> <b>show</b> includes  the  bodies  of
                  the  messages  in  the output; if false, bodies are omitted.
                  --body=false is only implemented for the json and sexp  for-
                  mats and it is incompatible with --part &gt; 0.

                  This  is  useful  if  the  caller  only needs the headers as
                  body-less output is much faster and substantially smaller.

           <b>--include-html</b>

                  Include &quot;text/html&quot; 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 &quot;text/html&quot; parts,
                  no part with content type &quot;text/html&quot;  is  included  in  the
                  output.

       A  common  use  of  <b>notmuch</b> <b>show</b> is to display a single thread of email
       messages. For this, use a search term of &quot;thread:&lt;thread-id&gt;&quot; as can be
       seen in the first column of output from the <b>notmuch</b> <b>search</b> command.
</pre>

<h2>EXIT STATUS</h2>
<pre>
       This command supports the following special exit status codes

       <b>20</b>

              The requested format version is too old.

       <b>21</b>

              The requested format version is too new.
</pre>

<h2>SEE ALSO</h2>
<pre>
       <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>
       <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),
       <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>
       <a href='../notmuch-tag-1/'>much-tag</a>(1)
</pre>

<h2>AUTHOR</h2>
<pre>
       Carl Worth and many others
</pre>

<h2>COPYRIGHT</h2>
<pre>
       2014, Carl Worth and many others
</pre>

<h2>0.18</h2>