mirror of
https://git.notmuchmail.org/git/notmuch
synced 2024-11-26 20:57:58 +01:00
236 lines
6.5 KiB
Groff
236 lines
6.5 KiB
Groff
.TH NOTMUCH-SHOW 1 2013-02-17 "Notmuch 0.15.2"
|
|
.SH NAME
|
|
notmuch-show \- show messages matching the given search terms
|
|
.SH SYNOPSIS
|
|
|
|
.B notmuch show
|
|
.RI "[" options "...] <" search-term ">..."
|
|
|
|
.SH DESCRIPTION
|
|
|
|
Shows all messages matching the search terms.
|
|
|
|
See \fBnotmuch-search-terms\fR(7)
|
|
for details of the supported syntax for <search-terms>.
|
|
|
|
The messages will be grouped and sorted based on the threading (all
|
|
replies to a particular message will appear immediately after that
|
|
message 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
|
|
include
|
|
.RS 4
|
|
.TP 4
|
|
.B \-\-entire\-thread=(true|false)
|
|
|
|
If true,
|
|
.B notmuch show
|
|
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
|
|
and
|
|
.B --format=sexp
|
|
this defaults to true. For other formats, this defaults to false.
|
|
.RE
|
|
|
|
.RS 4
|
|
.TP 4
|
|
.B \-\-format=(text|json|sexp|mbox|raw)
|
|
|
|
.RS 4
|
|
.TP 4
|
|
.BR text " (default for messages)"
|
|
|
|
The default plain-text format has all text-content MIME parts
|
|
decoded. Various components in the output,
|
|
.RB ( message ", " header ", " body ", " attachment ", and MIME " part ),
|
|
will be delimited by easily-parsed markers. Each marker consists of a
|
|
Control-L character (ASCII decimal 12), the name of the marker, and
|
|
then either an opening or closing brace, ('{' or '}'), to either open
|
|
or close the component. For a multipart MIME message, these parts will
|
|
be nested.
|
|
.RE
|
|
.RS 4
|
|
.TP 4
|
|
.B json
|
|
|
|
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
|
|
sets
|
|
.B "\-\-entire\-thread"
|
|
The caller can disable this behaviour by setting
|
|
.B \-\-entire\-thread=false
|
|
.RE
|
|
.RS 4
|
|
.TP 4
|
|
.B sexp
|
|
|
|
The output is formatted as an S-Expression (sexp). This
|
|
format is more robust than the text format for automated
|
|
processing. The nested structure of multipart MIME messages is
|
|
reflected in nested S-Expression output. By default,
|
|
S-Expression output includes all messages in a matching thread;
|
|
that is, by default,
|
|
|
|
.B \-\-format=sexp
|
|
sets
|
|
.B "\-\-entire\-thread"
|
|
The caller can disable this behaviour by setting
|
|
.B \-\-entire\-thread=false
|
|
|
|
.RE
|
|
.RS 4
|
|
.TP 4
|
|
.B mbox
|
|
|
|
All matching messages are output in the traditional, Unix mbox format
|
|
with each message being prefixed by a line beginning with "From " and
|
|
a blank line separating each message. Lines in the message content
|
|
beginning with "From " (preceded by zero or more '>' characters) have
|
|
an additional '>' character added. This reversible escaping
|
|
is termed "mboxrd" format and described in detail here:
|
|
|
|
.nf
|
|
.nh
|
|
http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
|
|
.hy
|
|
.fi
|
|
.
|
|
.RE
|
|
.RS 4
|
|
.TP 4
|
|
.BR raw " (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.
|
|
.RE
|
|
.RE
|
|
|
|
.RS 4
|
|
.TP 4
|
|
.BR \-\-format-version=N
|
|
|
|
Use the specified structured output format version. This is intended
|
|
for programs that invoke \fBnotmuch\fR(1) internally. If omitted, the
|
|
latest supported version will be used.
|
|
.RE
|
|
|
|
.RS 4
|
|
.TP 4
|
|
.B \-\-part=N
|
|
|
|
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 structure, and are identified
|
|
in the 'json', 'sexp' or 'text' output formats.
|
|
.RE
|
|
|
|
.RS 4
|
|
.TP 4
|
|
.B \-\-verify
|
|
|
|
Compute and report the validity of any MIME cryptographic signatures
|
|
found in the selected content (ie. "multipart/signed" parts). Status
|
|
of the signature will be reported (currently only supported with
|
|
--format=json and --format=sexp), and the multipart/signed part
|
|
will be replaced by the signed data.
|
|
.RE
|
|
|
|
.RS 4
|
|
.TP 4
|
|
.B \-\-decrypt
|
|
|
|
Decrypt any MIME encrypted parts found in the selected content
|
|
(ie. "multipart/encrypted" parts). Status of the decryption will be
|
|
reported (currently only supported with --format=json and
|
|
--format=sexp) and on successful decryption the multipart/encrypted
|
|
part will be replaced by the decrypted content.
|
|
|
|
Decryption expects a functioning \fBgpg-agent\fR(1) to provide any
|
|
needed credentials. Without one, the decryption will fail.
|
|
|
|
Implies --verify.
|
|
.RE
|
|
|
|
.RS 4
|
|
.TP 4
|
|
.BR \-\-exclude=(true|false)
|
|
|
|
Specify whether to omit threads only matching search.tag_exclude 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 returned
|
|
regardless (with the excluded flag being set when appropriate) but
|
|
threads that only match in an excluded message are not returned when
|
|
.B --exclude=true.
|
|
|
|
The default is
|
|
.B --exclude=true.
|
|
|
|
.RE
|
|
|
|
.RS 4
|
|
.TP 4
|
|
.B \-\-body=(true|false)
|
|
|
|
If true (the default)
|
|
.B notmuch show
|
|
includes the bodies of the messages in the output; if false,
|
|
bodies are omitted.
|
|
.B --body=false
|
|
is only implemented for the json and sexp formats and it is incompatible with
|
|
.B --part > 0.
|
|
|
|
This is useful if the caller only needs the headers as body-less
|
|
output is much faster and substantially smaller.
|
|
.RE
|
|
|
|
A common use of
|
|
.B notmuch show
|
|
is to display a single thread of email messages. For this, use a
|
|
search term of "thread:<thread-id>" as can be seen in the first
|
|
column of output from the
|
|
.B notmuch search
|
|
command.
|
|
|
|
.SH EXIT STATUS
|
|
|
|
This command supports the following special exit status codes
|
|
|
|
.TP
|
|
.B 20
|
|
The requested format version is too old.
|
|
.TP
|
|
.B 21
|
|
The requested format version is too new.
|
|
|
|
.SH SEE ALSO
|
|
|
|
\fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1),
|
|
\fBnotmuch-dump\fR(1), \fBnotmuch-hooks\fR(5),
|
|
\fBnotmuch-insert\fR(1), \fBnotmuch-new\fR(1),
|
|
\fBnotmuch-reply\fR(1), \fBnotmuch-restore\fR(1),
|
|
\fBnotmuch-search\fR(1), \fBnotmuch-search-terms\fR(7),
|
|
\fBnotmuch-tag\fR(1)
|