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
Presents the results in either JSON or plain-text (default).
.RE
+
+.RS 4
+.TP 4
+.B \-\-output=(summary|threads|messages|files|tags)
+
+.RS 4
+.TP 4
+.B summary
+
+Output a summary of each thread with any message matching the search
+terms. The summary includes the thread ID, date, the number of
+messages in the thread (both the number matched and the total number),
+the authors of the thread and the subject.
+.RE
+.RS 4
+.TP 4
+.B threads
+
+Output the thread IDs of all threads with any message matching the
+search terms, either one per line (--format=text) or as a JSON array
+(--format=json).
+.RE
+.RS 4
+.TP 4
+.B messages
+
+Output the message IDs of all messages matching the search terms,
+either one per line (--format=text) or as a JSON array
+(--format=json).
+.RE
+.RS 4
+.TP 4
+.B files
+
+Output the filenames of all messages matching the search terms, either
+one per line (--format=text) or as a JSON array (--format=json).
+.RE
+.RS 4
+.TP 4
+.B tags
+
+Output all tags that appear on any message matching the search terms,
+either one per line (--format=text) or as a JSON array
+(--format=json).
+.RE
+.RE
+
.RS 4
.TP 4
.BR \-\-sort= ( newest\-first | oldest\-first )
.RS 4
.TP 4
-.B \-\-format=(json|text)
+.B \-\-format=(text|json|mbox)
.RS 4
.TP 4
.B text
-The default plain-text format has text-content MIME parts
+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.
-
.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
+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
.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
section below for details of the supported syntax for <search-terms>.
.RE
+The
+.B config
+command can be used to get or set settings int the notmuch
+configuration file.
+
+.RS 4
+.TP 4
+.BR "config get " <section> . <item>
+
+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
+
+.RS 4
+.TP 4
+.BR "config set " <section> . "<item> [values ...]"
+
+The specified configuration item is set to the given value. To
+specify a multiple-value item, provide each value as a separate
+command-line argument.
+
+If no values are provided, the specified configuration item will be
+removed from the configuration file.
+.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):