-.TH NOTMUCH-SEARCH 1 2013-02-17 "Notmuch 0.15.2"
+.TH NOTMUCH-SEARCH 1 2013-11-20 "Notmuch 0.17~rc1"
.SH NAME
notmuch-search \- search for messages matching the given search terms
.SH SYNOPSIS
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).
+
+Note that each message may have multiple filenames associated with it.
+All of them are included in the output, unless limited with the
+\-\-duplicate=N option.
.RE
.RS 4
.TP 4
.RS 4
.TP 4
-.BR \-\-exclude=(true|false|flag)
+.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.
.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.
thread, rather than the number of matching messages.
.RE
+.RS 4
+.TP 4
+.BR \-\-duplicate=N
+
+Effective with
+.BR --output=files ,
+output the Nth filename associated with each message matching the
+query (N is 1-based). If N is greater than the number of files
+associated with the message, don't print anything.
+
+Note that this option is orthogonal with the
+.BR folder:
+search prefix. The prefix matches messages based on filenames. This
+option filters filenames of the matching messages.
+.RE
+
.SH EXIT STATUS
This command supports the following special exit status codes
.SH SEE ALSO
\fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1),
-\fBnotmuch-dump\fR(1), \fBnotmuch-hooks\fR(5), \fBnotmuch-new\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)