-.TH NOTMUCH-SEARCH 1 2011-12-04 "Notmuch 0.10.2"
+.TH NOTMUCH-SEARCH 1 2013-07-28 "Notmuch 0.16"
.SH NAME
-notmuch-search \- Search for messages matching the given search terms.
+notmuch-search \- search for messages matching the given search terms
.SH SYNOPSIS
.B notmuch search
include
.RS 4
.TP 4
-.BR \-\-format= ( json | text )
+.BR \-\-format= ( json | sexp | text | text0 )
-Presents the results in either JSON or plain-text (default).
+Presents the results in either JSON, S-Expressions, newline character
+separated plain-text (default), or null character separated plain-text
+(compatible with \fBxargs\fR(1) -0 option where available).
+.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
.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).
+search terms, either one per line (\-\-format=text), separated by null
+characters (\-\-format=text0), as a JSON array (\-\-format=json), or
+an S-Expression list (\-\-format=sexp).
.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).
+either one per line (\-\-format=text), separated by null characters
+(\-\-format=text0), as a JSON array (\-\-format=json), or as an
+S-Expression list (\-\-format=sexp).
.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).
+one per line (\-\-format=text), separated by null characters
+(\-\-format=text0), as a JSON array (\-\-format=json), or as an
+S-Expression list (\-\-format=sexp).
.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).
+either one per line (\-\-format=text), separated by null characters
+(\-\-format=text0), as a JSON array (\-\-format=json), or as an
+S-Expression list (\-\-format=sexp).
.RE
.RE
Limit the number of displayed results to N.
.RE
+.RS 4
+.TP 4
+.BR \-\-exclude=(true|false|all|flag)
+
+A message is called "excluded" if it matches at least one tag in
+search.tag_exclude that does not appear explicitly in the search terms.
+This option specifies whether to omit excluded messages in the search
+process.
+
+The default value,
+.BR true ,
+prevents excluded messages from matching the search terms.
+
+.B all
+additionally prevents excluded messages from appearing in displayed
+results, in effect behaving as though the excluded messages do not exist.
+
+.B false
+allows excluded messages to match search terms and appear in displayed
+results. Excluded messages are still marked in the relevant outputs.
+
+.B flag
+only has an effect when
+.BR --output=summary .
+The output is almost identical to
+.BR false ,
+but the "match count" is the number of matching non-excluded messages in the
+thread, rather than the number of matching messages.
+.RE
+
+.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(5), \fBnotmuch-hooks\fR(5), \fBnotmuch-part\fR(1),
-\fBnotmuch-reply\fR(1), \fBnotmuch-reply\fR(1),
-\fBnotmuch-restore\fR(1), \fBnotmuch-search-terms\fR(7),
-\fBnotmuch-show\fR(1), \fBnotmuch-tag\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-terms\fR(7), \fBnotmuch-show\fR(1),
+\fBnotmuch-tag\fR(1)
projects / notmuch / blobdiff