cli: Add configurable address deduplication for --output=addresses

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

diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst
index 7ac6c68e68acaa54592ca03ab36378281e7a4471..a92779a701d833ca4b356dd5d880ded09d0392a5 100644 (file)
--- a/doc/man1/notmuch-search.rst
+++ b/doc/man1/notmuch-search.rst
@@ -35,7 +35,7 @@ Supported options for **search** include
         intended for programs that invoke **notmuch(1)** internally. If
         omitted, the latest supported version will be used.
 
         intended for programs that invoke **notmuch(1)** internally. If
         omitted, the latest supported version will be used.
 

-    ``--output=(summary|threads|messages|files|tags)``
+    ``--output=(summary|threads|messages|files|tags|sender|recipients|addresses)``

 
         **summary**
             Output a summary of each thread with any message matching
 
         **summary**
             Output a summary of each thread with any message matching


@@ -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
             (--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
 
         **tags**
             Output all tags that appear on any message matching the


@@ -73,6 +78,29 @@ Supported options for **search** include
             by null characters (--format=text0), as a JSON array
             (--format=json), or as an S-Expression list (--format=sexp).
 
             by null characters (--format=text0), as a JSON array
             (--format=json), or as an S-Expression list (--format=sexp).
 

+       **sender**
+            Output all addresses from the *From* header that appear on
+            any message 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).
+
+            Handling of duplicate addresses and/or names can be
+            controlled with the --unique option.
+
+           Note: Searching for **sender** should much be faster than
+           searching for **recipients** or **addresses**, because
+           sender addresses are cached directly in the database
+           whereas other addresses need to be fetched from the
+           message file by parsing it.
+
+       **recipients**
+            Like **sender** but for addresses from *To*, *Cc* and
+           *Bcc* headers.
+
+       **addresses**
+           Like **sender** and **recipients** together.
+

     ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
         This option can be used to present results in either
         chronological order (**oldest-first**) or reverse chronological
     ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
         This option can be used to present results in either
         chronological order (**oldest-first**) or reverse chronological


@@ -126,6 +154,36 @@ Supported options for **search** include
         prefix. The prefix matches messages based on filenames. This
         option filters filenames of the matching messages.
 
         prefix. The prefix matches messages based on filenames. This
         option filters filenames of the matching messages.
 

+    ``--unique=``\ (**none**\ \|\ **addr**\ \|\ **addrfold**\ \|\ **name**)[,\ ...]
+
+        Can be used with ``--output=addresses``, ``--output=sender``
+        or ``--output=recipients`` to control the address
+        deduplication algorithm.
+
+       **none** means that no deduplication is performed. The same
+       address can appear multiple times in the output.
+
+       **addr** means that case-sensitive deduplication is performed
+       on the address part. For example, given the addresses "John
+       Doe <john@example.com>" and "Dr. John Doe <john@example.com>",
+       only one will be printed.
+
+       **addrfold** means that case-insensitive deduplication is
+       performed on the address part. For example, given the
+       addresses "John Doe <john@example.com>" and "John Doe
+       <JOHN@EXAMPLE.COM>", only one will be printed. This is the
+       default.
+
+       **name** means that case-sensitive deduplication is performed
+       on the name part. For example, given the addresses "John Doe
+       <john@example.com>" and "John Doe <john@doe.name>", only one
+       will be printed.
+
+       It is possible to combine the above flags (except **none**) by
+       separating them with comma. For example,
+       ``--unique=name,addr`` will print unique case-sensitive
+       combinations of name and address.
+

 EXIT STATUS
 ===========
 
 EXIT STATUS
 ===========