X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=doc%2Fman1%2Fnotmuch-search.rst;h=4e660a6facbbb25295688795a28c8b7991627809;hb=caa9dcb70798bbd06bc52489109988ed1c01806c;hp=7ac6c68e68acaa54592ca03ab36378281e7a4471;hpb=d736260385a689b5c77d8121f48e29440e3adfa4;p=notmuch

diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst
index 7ac6c68e..4e660a6f 100644
--- a/doc/man1/notmuch-search.rst
+++ b/doc/man1/notmuch-search.rst
@@ -64,8 +64,13 @@ Supported options for **search** include
             (--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.
+            associated with it. All of them are included in the output
+            (unless limited with the --duplicate=N option). This may
+            be particularly confusing for **folder:** or **path:**
+            searches in a specified directory, as the messages may
+            have duplicates in other directories that are included in
+            the output, although these files alone would not match the
+            search.
 
         **tags**
             Output all tags that appear on any message matching the
@@ -117,10 +122,14 @@ Supported options for **search** include
         rather than the number of matching messages.
 
     ``--duplicate=N``
-        Effective with ``--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.
+        For ``--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.
+
+        For ``--output=messages``, only output message IDs of messages
+        matching the search terms that have at least N filenames
+        associated with them.
 
         Note that this option is orthogonal with the **folder:** search
         prefix. The prefix matches messages based on filenames. This
@@ -144,3 +153,4 @@ SEE ALSO
 **notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
 **notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
 **notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**
+**notmuch-address(1)**