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>options</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 post-
  24        processor (such as the emacs interface to notmuch).
  25
  26        Supported options for <b>show</b> include
  27
  28            <b>--entire-thread</b>
  29
  30                By default only those messages that match the search terms will
  31                be displayed. With this option, all messages in the same thread
  32                as any matched message will be displayed.
  33
  34            <b>--format=(text|json|mbox|raw)</b>
  35
  36                <b>text</b> (default for messages)
  37
  38                    The default plain-text format  has  all  text-content  MIME
  39                    parts  decoded. Various components in the output, (<b>message</b>,
  40                    <b>header</b>, <b>body</b>, <b>attachment</b>, and MIME <b>part</b>), will be delimited
  41                    by  easily-parsed  markers.  Each marker consists of a Con-
  42                    trol-L character  (ASCII  decimal  12),  the  name  of  the
  43                    marker,  and  then either an opening or closing brace, (&apos;{&apos;
  44                    or &apos;}&apos;), to either open or close the component. For a  mul-
  45                    tipart MIME message, these parts will be nested.
  46
  47                <b>json</b>
  48
  49                    The  output  is  formatted  with Javascript Object Notation
  50                    (JSON). This format is more robust than the text format for
  51                    automated  processing.  The  nested  structure of multipart
  52                    MIME messages is reflected in nested JSON output. JSON out-
  53                    put  always  includes all messages in a matching thread; in
  54                    effect <b>--format=json</b> implies <b>--entire-thread</b>
  55
  56                <b>mbox</b>
  57
  58                    All matching messages are output in the  traditional,  Unix
  59                    mbox  format  with  each  message  being prefixed by a line
  60                    beginning with &quot;From &quot; and a  blank  line  separating  each
  61                    message.  Lines in the message content beginning with &quot;From
  62                    &quot; (preceded by zero or more &apos;&gt;&apos; characters) have  an  addi-
  63                    tional  &apos;&gt;&apos;  character  added.  This reversible escaping is
  64                    termed &quot;mboxrd&quot; format and described in detail here:
  65
  66                    http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
  67
  68                <b>raw</b> (default for a single part, see --part)
  69
  70                    For a message or an attached message  part,  the  original,
  71                    raw  content  of  the email message is output. Consumers of
  72                    this format should expect to implement  MIME  decoding  and
  73                    similar functions.
  74
  75                    For  a  single part (--part) the raw part content is output
  76                    after performing any necessary MIME  decoding.   Note  that
  77                    messages with a simple body still have two parts: part 0 is
  78                    the whole message and part 1 is the body.
  79
  80                    For a multipart part, the part headers and body  (including
  81                    all child parts) is output.
  82
  83                    The raw format must only be used with search terms matching
  84                    single message.
  85
  86            <b>--part=N</b>
  87
  88                Output the single decoded MIME part N of a single message.  The
  89                search  terms  must match only a single message.  Message parts
  90                are numbered in a depth-first walk of the message  MIME  struc-
  91                ture,  and  are  identified in the &apos;json&apos; or &apos;text&apos; output for-
  92                mats.
  93
  94            <b>--verify</b>
  95
  96                Compute and report the validity of any MIME cryptographic  sig-
  97                natures  found  in the selected content (ie. &quot;multipart/signed&quot;
  98                parts). Status of the signature will be reported (currently on-
  99                ly supported with --format=json), and the multipart/signed part
 100                will be replaced by the signed data.
 101
 102            <b>--decrypt</b>
 103
 104                Decrypt any MIME encrypted parts found in the selected  content
 105                (ie.  &quot;multipart/encrypted&quot;  parts).  Status  of the decryption
 106                will be reported (currently only supported with  --format=json)
 107                and  the  multipart/encrypted  part will be replaced by the de-
 108                crypted content.  Implies --verify.
 109
 110            <b>--exclude=(true|false)</b>
 111
 112                Specify whether to omit threads  only  matching  search.tag_ex-
 113                clude  from  the search results (the default) or not. In either
 114                case the excluded message will be marked with the exclude  flag
 115                (except  when  output=mbox  when  there  is  nowhere to put the
 116                flag).
 117
 118                If --entire-thread is specified then complete threads  are  re-
 119                turned regardless (with the excluded flag being set when appro-
 120                priate) but threads that only match in an excluded message  are
 121                not returned when <b>--exclude=true.</b>
 122
 123                The default is <b>--exclude=true.</b>
 124
 125        A  common  use  of  <b>notmuch</b> <b>show</b> is to display a single thread of email
 126        messages. For this, use a search term of &quot;thread:&lt;thread-id&gt;&quot; as can be
 127        seen in the first column of output from the <b>notmuch</b> <b>search</b> command.
 128 </pre>
 129
 130 <h2>SEE ALSO</h2>
 131 <pre>
 132        <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>
 133        <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),
 134        <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)
 135 </pre>
 136
 137 <h2>Notmuch 0.13.2</h2>