cli/reindex: destroy stashed session keys when --decrypt=false

[notmuch] / doc / man1 / notmuch-search.rst

diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst
index 7ac6c68e68acaa54592ca03ab36378281e7a4471..67c1ce904c0152d22a53b9b46ace5c6df67df84f 100644 (file)
--- a/doc/man1/notmuch-search.rst
+++ b/doc/man1/notmuch-search.rst
@@ -42,7 +42,9 @@ Supported options for **search** include
             the search terms. The summary includes the thread ID, date,
             the number of messages in the thread (both the number
             matched and the total number), the authors of the thread and
-            the subject.
+           the subject. In the case where a thread contains multiple files for
+           some messages, the total number of files is printed in parentheses
+           (see below for an example).
 
         **threads**
             Output the thread IDs of all threads with any message
@@ -64,8 +66,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,15 +124,32 @@ 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
         option filters filenames of the matching messages.
 
+EXAMPLE
+=======
+
+The following shows an example of the summary output format, with one
+message having multiple filenames.
+
+::
+
+  % notmuch search date:today.. and tag:bad-news
+  thread:0000000000063c10 Today [1/1] Some Persun; To the bone (inbox unread)
+  thread:0000000000063c25 Today [1/1(2)] Ann Other; Bears (inbox unread)
+  thread:0000000000063c00 Today [1/1] A Thurd; Bites, stings, sad feelings (inbox unread)
+
 EXIT STATUS
 ===========
 
@@ -140,7 +164,16 @@ This command supports the following special exit status codes
 SEE ALSO
 ========
 
-**notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
-**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(1)**,
+**notmuch-config(1)**,
+**notmuch-count(1)**,
+**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)**