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
section below for more details on the supported syntax.
The
-.BR search " and "show
+.BR search ", " show " and " count
commands are used to query the email database.
.RS 4
.TP 4
include
.RS 4
.TP 4
-.BR \-\-max\-threads= <value>
-
-Restricts displayed search results to a subset of the complete results
-that would match the terms. With this option, no more than <value>
-thread results will be displayed. If this option is not used, then all
-matching threads will be displayed. See also the
-.B \-\-first
-option.
-
-.TP
-.BR \-\-first= <value>
-
-Omits the first <value> threads from the search results that would
-otherwise be displayed. Together with the
-.BR \-\-max\-threads
-option, this can be used to perform incremental searches. For example,
-the first 50 thread results can be displayed with
-.B "\-\-first=0 \-\-max\-threads=50"
-and the next 50 could be displayed with
-.B "\-\-first=50 \-\-max\-threads=50"
-etc.
+.BR \-\-format= ( json | text )
-.TP
+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=(text|json|mbox)
+
+.RS 4
+.TP 4
+.B text
+
+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
then either an opening or closing brace, ('{' or '}'), to either open
or close the component.
+.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. JSON output always includes all messages in a matching
+thread; in effect
+.B \-\-format=json
+implies
+.B \-\-entire\-thread
+
+.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:
+http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html
+
+.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
+.TP
+.BR count " <search-term>..."
+
+Count messages matching the search terms.
+
+The number of matching messages is output to stdout.
+
+With no search terms, a count of all messages in the database will be
+displayed.
+.RE
+.RE
The
.B reply
command is useful for preparing a template for an email reply.
-
-.TP
-.BR reply " <search-term>..."
+.RS 4
+.TP 4
+.BR reply " [options...] <search-term>..."
Constructs a reply template for a set of messages.
template. The Reply-to header (if any, otherwise From:) is used for
the To: address. Vales from the To: and Cc: headers are copied, but
not including any of the current user's email addresses (as configured
-in primary_mail or other_email in the .notmuch-config file) in the
+in primary_mail or other_email in the .notmuch\-config file) in the
recipient list
It also builds a suitable new subject, including Re: at the front (if
not already present), and adding the message IDs of the messages being
-replied to to the References list and setting the In-Reply-To: field
+replied to to the References list and setting the In\-Reply\-To: field
correctly.
Finally, the original contents of the emails are quoted by prefixing
The resulting message template is output to stdout.
+Supported options for
+.B reply
+include
+.RS
+.TP 4
+.BR \-\-format= ( default | headers\-only )
+.RS
+.TP 4
+.BR default
+Includes subject and quoted message body.
+.TP
+.BR headers\-only
+Only produces In\-Reply\-To, References, To, Cc, and Bcc headers.
+.RE
+
See the
.B "SEARCH SYNTAX"
section below for details of the supported syntax for <search-terms>.
thread, replying to the entire thread allows for the reply to comment
on issue found in multiple patches.
.RE
+.RE
The
.B tag
.RS 4
.TP 4
-.BR tag " +<tag>|-<tag> [...] [--] <search-term>..."
+.BR tag " +<tag>|\-<tag> [...] [\-\-] <search-term>..."
Add/remove tags for all messages matching the search terms.
-Tags prefixed by '+' are added while those prefixed by '-' are
+Tags prefixed by '+' are added while those prefixed by '\-' are
removed. For each message, tag removal is performed before tag
addition.
The beginning of <search-terms> is recognized by the first
-argument that begins with neither '+' nor '-'. Support for
-an initial search term beginning with '+' or '-' is provided
-by allowing the user to specify a "--" argument to separate
+argument that begins with neither '+' nor '\-'. Support for
+an initial search term beginning with '+' or '\-' is provided
+by allowing the user to specify a "\-\-" argument to separate
the tags from the search terms.
See the
.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
+
+The
+.B config
+command can be used to get settings from the notmuch configuration
+file.
+
+.RS 4
+.TP 4
+.BR "config get " <section> . <item>
+
+Get settings from the notmuch configuration file.
+
+The value of the specified configuration item is printed to stdout. If
+the item has multiple values, each value is separated by a newline
+character.
+
+Available configuration items include at least
+
+ database.path
+
+ user.name
+
+ user.primary_email
+
+ user.other_email
+
+ new.tags
+.RE
+
.SH SEARCH SYNTAX
Several notmuch commands accept a common syntax for search terms.
terms/phrases in the body, the subject, or any of the sender or
recipient headers.
+As a special case, a search string consisting of exactly a single
+asterisk ("*") will match all messages.
+
In addition to free text, the following prefixes can be used to force
terms to match against specific portions of an email, (where
<brackets> indicate user-supplied values):
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
For
.BR id: ,
-message ID values are the literal contents of the Message-ID: header
+message ID values are the literal contents of the Message\-ID: header
of email messages, but without the '<', '>' delimiters.
The
<intial-timestamp>..<final-timestamp>
Each timestamp is a number representing the number of seconds since
-1970-01-01 00:00:00 UTC. This is not the most convenient means of
+1970\-01\-01 00:00:00 UTC. This is not the most convenient means of
expressing date ranges, but until notmuch is fixed to accept a more
convenient form, one can use the date program to construct
timestamps. For example, with the bash shell the folowing syntax would
-specify a date range to return messages from 2009-10-01 until the
+specify a date range to return messages from 2009\-10\-01 until the
current time:
- $(date +%s -d 2009-10-01)..$(date +%s)
+ $(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
projects / notmuch / blobdiff