cli: search: Add --output=count

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

diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst
index b6607c922cc083c35b9add629c771d6d3927da1b..4b408f6b99351aff8a212a1b0ba26ebb33f1149e 100644 (file)
--- a/doc/man1/notmuch-search.rst
+++ b/doc/man1/notmuch-search.rst
@@ -85,6 +85,9 @@ Supported options for **search** include
             (--format=text0), as a JSON array (--format=json), or as
             an S-Expression list (--format=sexp).
 
+            Duplicate addresses are filtered out. Filtering can be
+            configured with the --filter-by option.
+
            Note: Searching for **sender** should be much faster than
            searching for **recipients**, because sender addresses are
            cached directly in the database whereas other addresses
@@ -94,9 +97,14 @@ Supported options for **search** include
             Like **sender** but for addresses from *To*, *Cc* and
            *Bcc* headers.
 
+       **count**
+           Can be used in combination with **sender** or
+           **recipients** to print the count of how many times was
+           the address encountered during search.
+
        This option can be given multiple times to combine different
-       outputs. Currently, this is only supported for **sender** and
-       **recipients** outputs.
+       outputs. Currently, this is only supported for **sender**,
+       **recipients** and **count** outputs.
 
     ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
         This option can be used to present results in either
@@ -151,6 +159,41 @@ Supported options for **search** include
         prefix. The prefix matches messages based on filenames. This
         option filters filenames of the matching messages.
 
+    ``--filter-by=``\ (**nameaddr**\ \|\ **name** \|\ **addr**\ \|\ **addrfold**\ \|\ **nameaddrfold**\)
+
+       Can be used with ``--output=sender`` or
+       ``--output=recipients`` to filter out duplicate addresses. The
+       filtering algorithm receives a sequence of email addresses and
+       outputs the same sequence without the addresses that are
+       considered a duplicate of a previously output address. What is
+       considered a duplicate depends on how the two addresses are
+       compared and this can be controlled with the follwing flags:
+
+       **nameaddr** means that both name and address parts are
+       compared in case-sensitive manner. Therefore, all same looking
+       addresses strings are considered duplicate. This is the
+       default.
+
+       **name** means that only the name part is compared (in
+       case-sensitive manner). For example, the addresses "John Doe
+       <me@example.com>" and "John Doe <john@doe.name>" will be
+       considered duplicate.
+
+       **addr** means that only the address part is compared (in
+       case-sensitive manner). For example, the addresses "John Doe
+       <john@example.com>" and "Dr. John Doe <john@example.com>" will
+       be considered duplicate.
+
+       **addrfold** is like **addr**, but comparison is done in
+       canse-insensitive manner. For example, the addresses "John Doe
+       <john@example.com>" and "Dr. John Doe <JOHN@EXAMPLE.COM>" will
+       be considered duplicate.
+
+       **nameaddrfold** is like **nameaddr**, but address comparison
+       is done in canse-insensitive manner. For example, the
+       addresses "John Doe <john@example.com>" and "John Doe
+       <JOHN@EXAMPLE.COM>" will be considered duplicate.
+
 EXIT STATUS
 ===========