man: document notmuch search --duplicate=N

[obsolete/notmuch-old] / man / man1 / notmuch-search.1

diff --git a/man/man1/notmuch-search.1 b/man/man1/notmuch-search.1
index 59e8f3416e0d0bb55abfb1abe621c5da4273ff1b..f69a4cd73a46e29d2ea0c7c25d76dd5737df9c61 100644 (file)
--- a/man/man1/notmuch-search.1
+++ b/man/man1/notmuch-search.1
@@ -1,4 +1,4 @@
-.TH NOTMUCH-SEARCH 1 2013-02-17 "Notmuch 0.15.2"
+.TH NOTMUCH-SEARCH 1 2013-08-03 "Notmuch 0.16"

 .SH NAME
 notmuch-search \- search for messages matching the given search terms
 .SH SYNOPSIS
 .SH NAME
 notmuch-search \- search for messages matching the given search terms
 .SH SYNOPSIS


@@ -80,6 +80,10 @@ Output the filenames of all messages matching the search terms, 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).
 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
 .RE
 .RS 4
 .TP 4


@@ -130,7 +134,7 @@ Limit the number of displayed results to N.
 
 .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.
 
 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.


@@ -141,15 +145,37 @@ The default value,
 .BR true ,
 prevents excluded messages from matching 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.
 
 .B flag
 only has an effect when
 .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

-.B --output=summary
-In this case all matching threads are returned but the "match count"
-is the number of matching non-excluded messages in the thread.
+.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
+
+.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
 .RE
 
 .SH EXIT STATUS


@@ -166,7 +192,8 @@ The requested format version is too new.
 .SH SEE ALSO
 
 \fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1),
 .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)
 \fBnotmuch-reply\fR(1), \fBnotmuch-restore\fR(1),
 \fBnotmuch-search-terms\fR(7), \fBnotmuch-show\fR(1),
 \fBnotmuch-tag\fR(1)