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