version: bump to 0.17~rc1

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

diff --git a/man/man1/notmuch-search.1 b/man/man1/notmuch-search.1
index da2f1dd1d179748b47159bc250249f9b565ce9db..a2cdc4aeb9e14a63972ef99d0e9de1c1c0811972 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-11-20 "Notmuch 0.17~rc1"

 .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,6 +145,10 @@ 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 false
 allows excluded messages to match search terms and appear in displayed
 results. Excluded messages are still marked in the relevant outputs.


@@ -154,6 +162,22 @@ but the "match count" is the number of matching non-excluded messages in the
 thread, rather than the number of matching messages.
 .RE
 
 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 EXIT STATUS
 
 This command supports the following special exit status codes


@@ -168,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)