1NOTMUCH-SHOW(1)                     notmuch                    NOTMUCH-SHOW(1)
2
3
4

NAME

6       notmuch-show - show messages matching the given search terms
7

SYNOPSIS

9       notmuch show [option ...] <search-term> ...
10

DESCRIPTION

12       Shows all messages matching the search terms.
13
14       See  notmuch-search-terms(7)  for  details  of the supported syntax for
15       <search-terms>.
16
17       The messages will be grouped and sorted based  on  the  threading  (all
18       replies to a particular message will appear immediately after that mes‐
19       sage in date order). The output is not indented by default,  but  depth
20       tags  are  printed  so  that  proper  indentation can be performed by a
21       post-processor (such as the emacs interface to notmuch).
22
23       Supported options for show include
24
25       --entire-thread=(true|false)
26              If true, notmuch show outputs all messages in the thread of  any
27              message matching the search terms; if false, it outputs only the
28              matching messages.  For  --format=json  and  --format=sexp  this
29              defaults to true. For other formats, this defaults to false.
30
31       --format=(text|json|sexp|mbox|raw)
32
33              text (default for messages)
34                     The  default  plain-text format has all text-content MIME
35                     parts decoded. Various components in  the  output,  (mes‐
36                     sage,  header,  body, attachment, and MIME part), will be
37                     delimited by easily-parsed markers. Each marker  consists
38                     of  a Control-L character (ASCII decimal 12), the name of
39                     the marker, and then either an opening or closing  brace,
40                     ('{'  or '}'), to either open or close the component. For
41                     a multipart MIME message, these parts will be nested.
42
43              json   The output is formatted with Javascript  Object  Notation
44                     (JSON).  This  format is more robust than the text format
45                     for automated processing. The nested structure of  multi‐
46                     part MIME messages is reflected in nested JSON output. By
47                     default JSON output includes all messages in  a  matching
48                     thread;   that   is,   by   default,  --format=json  sets
49                     --entire-thread. The caller can disable this behaviour by
50                     setting --entire-thread=false.  The JSON output is always
51                     encoded as UTF-8 and any message content included in  the
52                     output will be charset-converted to UTF-8.
53
54              sexp   The  output  is formatted as the Lisp s-expression (sexp)
55                     equivalent of the JSON format above. Objects are  format‐
56                     ted  as  property  lists whose keys are keywords (symbols
57                     preceded by a colon). True is formatted  as  t  and  both
58                     false  and  null  are  formatted as nil. As for JSON, the
59                     s-expression output is always encoded as UTF-8.
60
61              mbox   All matching messages are output in the traditional, Unix
62                     mbox  format  with  each message being prefixed by a line
63                     beginning with "From " and a blank line  separating  each
64                     message.  Lines  in  the  message  content beginning with
65                     "From " (preceded by zero or more '>' characters) have an
66                     additional  '>' character added. This reversible escaping
67                     is termed "mboxrd" format and described in detail here:
68                        http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
69
70              raw (default if --part is given)
71                     Write  the  raw bytes of the given MIME part of a message
72                     to standard out. For this format, it is an error to spec‐
73                     ify a query that matches more than one message.
74
75                     If  the  specified  part is a leaf part, this outputs the
76                     body of the part after performing content transfer decod‐
77                     ing  (but  no  charset  conversion). This is suitable for
78                     saving attachments, for example.
79
80                     For a multipart or message part, the output includes  the
81                     part  headers  as  well  as the body (including all child
82                     parts). No decoding is performed  because  multipart  and
83                     message  parts  cannot  have non-trivial content transfer
84                     encoding. Consumers of this may need  to  implement  MIME
85                     decoding and similar functions.
86
87       --format-version=N
88              Use  the  specified  structured  output  format version. This is
89              intended for programs  that  invoke  notmuch(1)  internally.  If
90              omitted, the latest supported version will be used.
91
92       --part=N
93              Output  the  single decoded MIME part N of a single message. The
94              search terms must match only a single message. Message parts are
95              numbered  in  a  depth-first walk of the message MIME structure,
96              and are identified in the 'json', 'sexp' or 'text'  output  for‐
97              mats.
98
99              Note that even a message with no MIME structure or a single body
100              part still has two MIME parts:  part  0  is  the  whole  message
101              (headers and body) and part 1 is just the body.
102
103       --verify
104              Compute and report the validity of any MIME cryptographic signa‐
105              tures found in the selected  content  (e.g.,  "multipart/signed"
106              parts). Status of the signature will be reported (currently only
107              supported with --format=json and --format=sexp), and the  multi‐
108              part/signed part will be replaced by the signed data.
109
110       --decrypt=(false|auto|true|stash)
111              If  true, decrypt any MIME encrypted parts found in the selected
112              content  (e.g.,  "multipart/encrypted"  parts).  Status  of  the
113              decryption  will  be  reported  (currently  only  supported with
114              --format=json and --format=sexp) and  on  successful  decryption
115              the  multipart/encrypted  part will be replaced by the decrypted
116              content.
117
118              stash behaves like true, but upon successful decryption it  will
119              also  stash the message's session key in the database, and index
120              the cleartext of the message, enabling automatic  decryption  in
121              the future.
122
123              If  auto,  and  a  session key is already known for the message,
124              then it will be decrypted, but notmuch will not  try  to  access
125              the user's keys.
126
127              Use false to avoid even automatic decryption.
128
129              Non-automatic  decryption  (stash  or  true, in the absence of a
130              stashed session key) expects a functioning gpg-agent(1) to  pro‐
131              vide  any  needed  credentials. Without one, the decryption will
132              fail.
133
134              Note: setting either true or stash here implies --verify.
135
136              Here is a table that summarizes each of these policies:
137
138                       ┌──────────────┬───────┬──────┬──────┬───────┐
139                       │              │ false │ auto │ true │ stash │
140                       ├──────────────┼───────┼──────┼──────┼───────┤
141                       │Show  cleart‐ │       │ X    │ X    │ X     │
142                       │ext  if  ses‐ │       │      │      │       │
143                       │sion  key  is │       │      │      │       │
144                       │already known │       │      │      │       │
145                       ├──────────────┼───────┼──────┼──────┼───────┤
146                       │Use    secret │       │      │ X    │ X     │
147                       │keys to  show │       │      │      │       │
148                       │cleartext     │       │      │      │       │
149                       ├──────────────┼───────┼──────┼──────┼───────┤
150                       │Stash     any │       │      │      │ X     │
151                       │newly  recov‐ │       │      │      │       │
152                       │ered  session │       │      │      │       │
153                       │keys,   rein‐ │       │      │      │       │
154                       │dexing   mes‐ │       │      │      │       │
155                       │sage if found │       │      │      │       │
156                       └──────────────┴───────┴──────┴──────┴───────┘
157
158              Note: --decrypt=stash requires write  access  to  the  database.
159              Otherwise, notmuch show operates entirely in read-only mode.
160
161              Default: auto
162
163       --exclude=(true|false)
164              Specify     whether    to    omit    threads    only    matching
165              search.exclude_tags from the search  results  (the  default)  or
166              not. In either case the excluded message will be marked with the
167              exclude flag (except when output=mbox when there is  nowhere  to
168              put the flag).
169
170              If  --entire-thread  is  specified  then  complete  threads  are
171              returned regardless (with  the  excluded  flag  being  set  when
172              appropriate)  but threads that only match in an excluded message
173              are not returned when --exclude=true.
174
175              The default is --exclude=true.
176
177       --body=(true|false)
178              If true (the default) notmuch show includes the  bodies  of  the
179              messages   in   the   output;  if  false,  bodies  are  omitted.
180              --body=false is only implemented for the  text,  json  and  sexp
181              formats and it is incompatible with --part > 0.
182
183              This is useful if the caller only needs the headers as body-less
184              output is much faster and substantially smaller.
185
186       --include-html
187              Include "text/html" parts as part of the output (currently  only
188              supported  with --format=text, --format=json and --format=sexp).
189              By default, unless --part=N is used to select a specific part or
190              --include-html is used to include all "text/html" parts, no part
191              with content type "text/html" is included in the output.
192
193       A common use of notmuch show is to display a  single  thread  of  email
194       messages. For this, use a search term of "thread:<thread-id>" as can be
195       seen in the first column of output from the notmuch search command.
196

EXIT STATUS

198       This command supports the following special exit status codes
199
200       20     The requested format version is too old.
201
202       21     The requested format version is too new.
203

SEE ALSO

205       notmuch(1), notmuch-config(1), notmuch-count(1), notmuch-dump(1),  not‐
206       much-hooks(5),   notmuch-insert(1),  notmuch-new(1),  notmuch-reply(1),
207       notmuch-restore(1),  notmuch-search(1),  notmuch-search-terms(7),  not‐
208       much-tag(1)
209

AUTHOR

211       Carl Worth and many others
212
214       2009-2020, Carl Worth and many others
215
216
217
218
2190.31.3                           Dec 25, 2020                  NOTMUCH-SHOW(1)
Impressum