X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=doc%2Fman1%2Fnotmuch-address.rst;h=2a7df6f0d80f21133fee3f58902f907e83d7a34b;hp=01eb811e3d29c9b4b4040acfa287051048045243;hb=HEAD;hpb=4176e527fceb2c1f7a0b263fd8baac88be6fab4c diff --git a/doc/man1/notmuch-address.rst b/doc/man1/notmuch-address.rst index 01eb811e..c70dde35 100644 --- a/doc/man1/notmuch-address.rst +++ b/doc/man1/notmuch-address.rst @@ -1,3 +1,5 @@ +.. _notmuch-address(1): + =============== notmuch-address =============== @@ -13,60 +15,102 @@ DESCRIPTION Search for messages matching the given search terms, and display the addresses from them. Duplicate addresses are filtered out. -See **notmuch-search-terms(7)** for details of the supported syntax for +See :any:`notmuch-search-terms(7)` for details of the supported syntax for . Supported options for **address** include - ``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**) - Presents the results in either JSON, S-Expressions, newline - character separated plain-text (default), or null character - separated plain-text (compatible with **xargs(1)** -0 option - where available). +.. program:: address + +.. option:: --format=(json|sexp|text|text0) + + Presents the results in either JSON, S-Expressions, newline + character separated plain-text (default), or null character + separated plain-text (compatible with :manpage:`xargs(1)` -0 + option where available). + +.. option:: --format-version=N + + Use the specified structured output format version. This is + intended for programs that invoke :any:`notmuch(1)` internally. If + omitted, the latest supported version will be used. + +.. option:: --output=(sender|recipients|count|address) + + Controls which information appears in the output. This option can + be given multiple times to combine different outputs. When + neither ``--output=sender`` nor ``--output=recipients`` is + given, ``--output=sender`` is implied. + + sender + Output all addresses from the *From* header. + + Note: Searching for **sender** should be much faster than + searching for **recipients**, because sender addresses are + cached directly in the database whereas other addresses need + to be fetched from message files. + + recipients + Output all addresses from the *To*, *Cc* and *Bcc* headers. + + count + Print the count of how many times was the address encountered + during search. + + Note: With this option, addresses are printed only after the + whole search is finished. This may take long time. + + address + Output only the email addresses instead of the full mailboxes + with names and email addresses. This option has no effect on + the JSON or S-Expression output formats. + +.. option:: --deduplicate=(no|mailbox|address) + + Control the deduplication of results. - ``--format-version=N`` - Use the specified structured output format version. This is - intended for programs that invoke **notmuch(1)** internally. If - omitted, the latest supported version will be used. + no + Output all occurrences of addresses in the matching + messages. This is not applicable with ``--output=count``. - ``--output=(sender|recipients)`` + mailbox + Deduplicate addresses based on the full, case sensitive name + and email address, or mailbox. This is effectively the same as + piping the ``--deduplicate=no`` output to **sort | uniq**, except + for the order of results. This is the default. - Controls which information appears in the output. This option - can be given multiple times to combine different outputs. - Omitting this option is equivalent to - --output=sender --output=recipients. + address + Deduplicate addresses based on the case insensitive address + part of the mailbox. Of all the variants (with different name + or case), print the one occurring most frequently among the + matching messages. If ``--output=count`` is specified, include all + variants in the count. - **sender** - Output all addresses from the *From* header. +.. option:: --sort=(newest-first|oldest-first) - Note: Searching for **sender** should be much faster than - searching for **recipients**, because sender addresses are - cached directly in the database whereas other addresses - need to be fetched from message files. + This option can be used to present results in either chronological + order (**oldest-first**) or reverse chronological order + (**newest-first**). - **recipients** - Output all addresses from the *To*, *Cc* and *Bcc* - headers. + By default, results will be displayed in reverse chronological + order, (that is, the newest results will be displayed first). - ``--sort=``\ (**newest-first**\ \|\ **oldest-first**) - This option can be used to present results in either - chronological order (**oldest-first**) or reverse chronological - order (**newest-first**). + However, if either ``--output=count`` or ``--deduplicate=address`` is + specified, this option is ignored and the order of the results is + unspecified. - By default, results will be displayed in reverse chronological - order, (that is, the newest results will be displayed first). +.. option:: --exclude=(true|false) - ``--exclude=(true|false)`` - A message is called "excluded" if it matches at least one tag in - search.tag\_exclude that does not appear explicitly in the - search terms. This option specifies whether to omit excluded - messages in the search process. + A message is called "excluded" if it matches at least one tag in + search.exclude\_tags that does not appear explicitly in the search + terms. This option specifies whether to omit excluded messages in + the search process. - The default value, **true**, prevents excluded messages from - matching the search terms. + The default value, **true**, prevents excluded messages from + matching the search terms. - **false** allows excluded messages to match search terms and - appear in displayed results. + **false** allows excluded messages to match search terms and + appear in displayed results. EXIT STATUS =========== @@ -82,8 +126,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-search(1)** +:any:`notmuch(1)`, +:any:`notmuch-config(1)`, +:any:`notmuch-count(1)`, +:any:`notmuch-dump(1)`, +:any:`notmuch-hooks(5)`, +:any:`notmuch-insert(1)`, +:any:`notmuch-new(1)`, +:any:`notmuch-reply(1)`, +:any:`notmuch-restore(1)`, +:any:`notmuch-search(1)`, +:any:`notmuch-search-terms(7)`, +:any:`notmuch-show(1)`, +:any:`notmuch-tag(1)`