1 <h1>NOTMUCH-SHOW(1)</h1>
5 notmuch-show - show messages matching the given search terms
10 <b>notmuch</b> <b>show</b> [<u>options</u>...] <<u>search-term</u>>...
15 Shows all messages matching the search terms.
17 See <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of the supported syntax for
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).
26 Supported options for <b>show</b> include
28 <b>--entire-thread=(true|false)</b>
30 If true, <b>notmuch</b> <b>show</b> outputs all messages in the thread of any
31 message matching the search terms; if false, it outputs only
32 the matching messages. For <b>--format=json</b> and <b>--format=sexp</b> this
33 defaults to true. For other formats, this defaults to false.
35 <b>--format=(text|json|sexp|mbox|raw)</b>
37 <b>text</b> (default for messages)
39 The default plain-text format has all text-content MIME
40 parts decoded. Various components in the output, (<b>message</b>,
41 <b>header</b>, <b>body</b>, <b>attachment</b>, and MIME <b>part</b>), will be delimited
42 by easily-parsed markers. Each marker consists of a Con-
43 trol-L character (ASCII decimal 12), the name of the
44 marker, and then either an opening or closing brace, ('{'
45 or '}'), to either open or close the component. For a mul-
46 tipart MIME message, these parts will be nested.
50 The output is formatted with Javascript Object Notation
51 (JSON). This format is more robust than the text format for
52 automated processing. The nested structure of multipart
53 MIME messages is reflected in nested JSON output. By
54 default JSON output includes all messages in a matching
55 thread; that is, by default,
57 <b>--format=json</b> sets <b>--entire-thread</b> The caller can disable
58 this behaviour by setting <b>--entire-thread=false</b>
62 The output is formatted as an S-Expression (sexp). This
63 format is more robust than the text format for automated
64 processing. The nested structure of multipart MIME messages
65 is reflected in nested S-Expression output. By default, S-
66 Expression output includes all messages in a matching
67 thread; that is, by default,
69 <b>--format=sexp</b> sets <b>--entire-thread</b> The caller can disable
70 this behaviour by setting <b>--entire-thread=false</b>
74 All matching messages are output in the traditional, Unix
75 mbox format with each message being prefixed by a line
76 beginning with "From " and a blank line separating each
77 message. Lines in the message content beginning with "From
78 " (preceded by zero or more '>' characters) have an addi-
79 tional '>' character added. This reversible escaping is
80 termed "mboxrd" format and described in detail here:
82 http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
84 <b>raw</b> (default for a single part, see --part)
86 For a message or an attached message part, the original,
87 raw content of the email message is output. Consumers of
88 this format should expect to implement MIME decoding and
91 For a single part (--part) the raw part content is output
92 after performing any necessary MIME decoding. Note that
93 messages with a simple body still have two parts: part 0 is
94 the whole message and part 1 is the body.
96 For a multipart part, the part headers and body (including
97 all child parts) is output.
99 The raw format must only be used with search terms matching
102 <b>--format-version=N</b>
104 Use the specified structured output format version. This is
105 intended for programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If
106 omitted, the latest supported version will be used.
110 Output the single decoded MIME part N of a single message. The
111 search terms must match only a single message. Message parts
112 are numbered in a depth-first walk of the message MIME struc-
113 ture, and are identified in the 'json', 'sexp' or 'text' output
118 Compute and report the validity of any MIME cryptographic sig-
119 natures found in the selected content (ie. "multipart/signed"
120 parts). Status of the signature will be reported (currently on-
121 ly supported with --format=json and --format=sexp), and the
122 multipart/signed part will be replaced by the signed data.
126 Decrypt any MIME encrypted parts found in the selected content
127 (ie. "multipart/encrypted" parts). Status of the decryption
128 will be reported (currently only supported with --format=json
129 and --format=sexp) and on successful decryption the multi-
130 part/encrypted part will be replaced by the decrypted content.
132 Decryption expects a functioning <b>gpg-agent</b>(1) to provide any
133 needed credentials. Without one, the decryption will fail.
137 <b>--exclude=(true|false)</b>
139 Specify whether to omit threads only matching search.tag_ex-
140 clude from the search results (the default) or not. In either
141 case the excluded message will be marked with the exclude flag
142 (except when output=mbox when there is nowhere to put the
145 If --entire-thread is specified then complete threads are re-
146 turned regardless (with the excluded flag being set when appro-
147 priate) but threads that only match in an excluded message are
148 not returned when <b>--exclude=true.</b>
150 The default is <b>--exclude=true.</b>
152 <b>--body=(true|false)</b>
154 If true (the default) <b>notmuch</b> <b>show</b> includes the bodies of the
155 messages in the output; if false, bodies are omitted.
156 <b>--body=false</b> is only implemented for the json and sexp formats
157 and it is incompatible with <b>--part</b> ><b>&</b>gt; <b>0.</b>
159 This is useful if the caller only needs the headers as body-
160 less output is much faster and substantially smaller.
162 <b>--include-html</b>
164 Include "text/html" parts as part of the output (currently only
165 supported with --format=json and --format=sexp). By default,
166 unless <b>--part=N</b> is used to select a specific part or <b>--include-</b>
167 <b>html</b> is used to include all "text/html" parts, no part with
168 content type "text/html" is included in the output.
170 A common use of <b>notmuch</b> <b>show</b> is to display a single thread of email
171 messages. For this, use a search term of "thread:<thread-id>" as can be
172 seen in the first column of output from the <b>notmuch</b> <b>search</b> command.
177 This command supports the following special exit status codes
179 <b>20</b> The requested format version is too old.
181 <b>21</b> The requested format version is too new.
186 <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>
187 <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),
188 <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>
189 <a href='../notmuch-tag-1/'>much-tag</a>(1)
192 <h2>Notmuch 0.17</h2>