database. These subsequent runs will be much quicker than the initial
run.
-Note:
-.B notmuch new
-runs (other than the first run) will skip any read-only directories,
-so you can use that to mark directories that will not receive any new
-mail (and make
-.B notmuch new
-even faster).
-
Invoking
.B notmuch
with no command argument will run
include
.RS 4
.TP 4
+.BR \-\-format= ( json | text )
+
+Presents the results in either JSON or plain-text (default).
+.RE
+.RS 4
+.TP 4
.BR \-\-sort= ( newest\-first | oldest\-first )
This option can be used to present results in either chronological order
.B newest\-first
the threads will be sorted by the newest message in each thread.
+.RE
+.RS 4
By default, results will be displayed in reverse chronological order,
(that is, the newest results will be displayed first).
section below for details of the supported syntax for <search-terms>.
.RE
.TP
-.BR show " <search-term>..."
+.BR show " [options...] <search-term>..."
Shows all messages matching the search terms.
depth tags are printed so that proper indentation can be performed by
a post-processor (such as the emacs interface to notmuch).
-The output format is plain-text, with all text-content MIME parts
+Supported options for
+.B show
+include
+.RS 4
+.TP 4
+.B \-\-entire\-thread
+
+By default only those messages that match the search terms will be
+displayed. With this option, all messages in the same thread as any
+matched message will be displayed.
+.RE
+
+.RS 4
+.TP 4
+.B \-\-format=(json|text)
+
+.RS 4
+.TP 4
+.B text
+
+The default plain-text format has 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
then either an opening or closing brace, ('{' or '}'), to either open
or close the component.
+.RE
+.RS 4
+.TP 4
+.B json
+
+Format output as Javascript Object Notation (JSON). JSON output always
+includes all messages in a matching thread; in effect
+.B \-\-format=json
+implies
+.B \-\-entire\-thread
+
+.RE
A common use of
.B notmuch show
is to display a single thread of email messages. For this, use a
.B "SEARCH SYNTAX"
section below for details of the supported syntax for <search-terms>.
.RE
+.RE
The
.B reply
.B "notmuch restore"
command provides you a way to import all of your tags (or labels as
sup calls them).
+.RE
+
+The
+.B part
+command can used to output a single part of a multi-part MIME message.
+
+.RS 4
+.TP 4
+.BR part " --part=<part-number> <search-term>..."
+
+Output a single MIME part of a message.
+
+A single decoded MIME part, with no encoding or framing, is output to
+stdout. The search terms must match only a single message, otherwise
+this command will fail.
+
+The part number should match the part "id" field output by the
+"--format=json" option of "notmuch show". If the message specified by
+the search terms does not include a part with the specified "id" there
+will be no output.
+
+See the
+.B "SEARCH SYNTAX"
+section below for details of the supported syntax for <search-terms>.
+.RE
+
.SH SEARCH SYNTAX
Several notmuch commands accept a common syntax for search terms.
attachment:<word>
- tag:<tag>
+ tag:<tag> (or is:<tag>)
id:<message-id>
attachments to email messages.
For
-.BR tag: ,
+.BR tag: " and " is:
valid tag values include
.BR inbox " and " unread
by default for new messages added by
current time:
$(date +%s -d 2009-10-01)..$(date +%s)
+.SH ENVIRONMENT
+The following environment variables can be used to control the
+behavior of notmuch.
+.TP
+.B NOTMUCH_CONFIG
+Specifies the location of the notmuch configuration file. Notmuch will
+use ${HOME}/.notmuch-config if this variable is not set.
.SH SEE ALSO
The emacs-based interface to notmuch (available as
.B notmuch.el