[obsolete/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>options</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 <b>--format=json</b> this defaults to true.
               For other formats, this defaults to false.

           <b>--format=(text|json|mbox|raw)</b>

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

                   The  default  plain-text  format  has all text-content MIME
                   parts decoded. Various components in the output,  (<b>message</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  Con-
                   trol-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 mul-
                   tipart 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  multipart
                   MIME  messages  is  reflected  in  nested  JSON  output. By
                   default JSON output includes all  messages  in  a  matching
                   thread;   that   is,   by   default,   <b>--format=json</b>   sets
                   <b>--entire-thread</b> The caller can disable  this  behaviour  by
                   setting <b>--entire-thread=false</b>

               <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:

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

               <b>raw</b> (default for a single part, see --part)

                   For  a  message  or an attached message part, the original,
                   raw content of the email message is  output.  Consumers  of
                   this  format  should  expect to implement MIME decoding and
                   similar functions.

                   For a single part (--part) the raw part content  is  output
                   after  performing  any  necessary MIME decoding.  Note that
                   messages with a simple body still have two parts: part 0 is
                   the whole message and part 1 is the body.

                   For  a multipart part, the part headers and body (including
                   all child parts) is output.

                   The raw format must only be used with search terms matching
                   single message.

           <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 struc-
               ture, and are identified in the &apos;json&apos; or  &apos;text&apos;  output  for-
               mats.

           <b>--verify</b>

               Compute  and report the validity of any MIME cryptographic sig-
               natures found in the selected content  (ie.  &quot;multipart/signed&quot;
               parts). Status of the signature will be reported (currently on-
               ly supported with --format=json), and the multipart/signed part
               will be replaced by the signed data.

           <b>--decrypt</b>

               Decrypt  any MIME encrypted parts found in the selected content
               (ie. &quot;multipart/encrypted&quot; parts).  Status  of  the  decryption
               will  be reported (currently only supported with --format=json)
               and the multipart/encrypted part will be replaced  by  the  de-
               crypted content.  Implies --verify.

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

               Specify  whether  to  omit threads only matching search.tag_ex-
               clude 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 re-
               turned regardless (with the excluded flag being set when appro-
               priate)  but threads that only match in an excluded message are
               not returned when <b>--exclude=true.</b>

               The default is <b>--exclude=true.</b>

           <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.
               <b>--body=false</b> is only implemented for the json format and it  is
               incompatible with <b>--part</b> &gt<b>&</b>gt; <b>0.</b>

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

       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>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-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/'>notmuch-tag</a>(1)
</pre>

<h2>Notmuch 0.14</h2>