6003ed29cf32a913c6bf54138f496970574b514e
[notmuch] / doc / man1 / notmuch-address.rst
1 ===============
2 notmuch-address
3 ===============
4
5 SYNOPSIS
6 ========
7
8 **notmuch** **address** [*option* ...] <*search-term*> ...
9
10 DESCRIPTION
11 ===========
12
13 Search for messages matching the given search terms, and display the
14 addresses from them. Duplicate addresses are filtered out.
15
16 See **notmuch-search-terms(7)** for details of the supported syntax for
17 <search-terms>.
18
19 Supported options for **address** include
20
21     ``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
22         Presents the results in either JSON, S-Expressions, newline
23         character separated plain-text (default), or null character
24         separated plain-text (compatible with **xargs(1)** -0 option
25         where available).
26
27     ``--format-version=N``
28         Use the specified structured output format version. This is
29         intended for programs that invoke **notmuch(1)** internally. If
30         omitted, the latest supported version will be used.
31
32     ``--output=(sender|recipients|count)``
33
34         Controls which information appears in the output. This option
35         can be given multiple times to combine different outputs.
36         When neither --output=sender nor --output=recipients is
37         given, --output=sender is implied.
38
39         **sender**
40             Output all addresses from the *From* header.
41
42             Note: Searching for **sender** should be much faster than
43             searching for **recipients**, because sender addresses are
44             cached directly in the database whereas other addresses
45             need to be fetched from message files.
46
47         **recipients**
48             Output all addresses from the *To*, *Cc* and *Bcc*
49             headers.
50
51         **count**
52             Print the count of how many times was the address
53             encountered during search.
54
55             Note: With this option, addresses are printed only after
56             the whole search is finished. This may take long time.
57
58     ``--deduplicate=(no|mailbox)``
59
60         Control the deduplication of results.
61
62         **no**
63             Output all occurences of addresses in the matching
64             messages. This is not applicable with --output=count.
65
66         **mailbox**
67             Deduplicate addresses based on the full, case sensitive
68             name and email address, or mailbox. This is effectively
69             the same as piping the --deduplicate=no output to **sort |
70             uniq**, except for the order of results. This is the
71             default.
72
73     ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
74         This option can be used to present results in either
75         chronological order (**oldest-first**) or reverse chronological
76         order (**newest-first**).
77
78         By default, results will be displayed in reverse chronological
79         order, (that is, the newest results will be displayed first).
80
81         This option is not supported with --output=count.
82
83     ``--exclude=(true|false)``
84         A message is called "excluded" if it matches at least one tag in
85         search.tag\_exclude that does not appear explicitly in the
86         search terms. This option specifies whether to omit excluded
87         messages in the search process.
88
89         The default value, **true**, prevents excluded messages from
90         matching the search terms.
91
92         **false** allows excluded messages to match search terms and
93         appear in displayed results.
94
95 EXIT STATUS
96 ===========
97
98 This command supports the following special exit status codes
99
100 ``20``
101     The requested format version is too old.
102
103 ``21``
104     The requested format version is too new.
105
106 SEE ALSO
107 ========
108
109 **notmuch(1)**, **notmuch-config(1)**, **notmuch-count(1)**,
110 **notmuch-dump(1)**, **notmuch-hooks(5)**, **notmuch-insert(1)**,
111 **notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**,
112 **notmuch-search-terms(7)**, **notmuch-show(1)**, **notmuch-tag(1)**,
113 **notmuch-search(1)**