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 90160f21e23c12161876d019b07ca9a0c8dc7bfc..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.
 
-    ``--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
@@ -78,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).
 
+       **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
@@ -131,6 +154,36 @@ Supported options for **search** include
         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
 ===========