8 **notmuch** **search** [*option* ...] <*search-term*> ...
13 Search for messages matching the given search terms, and display as
14 results the threads containing the matched messages.
16 The output consists of one line per thread, giving a thread ID, the date
17 of the newest (or oldest, depending on the sort option) matched message
18 in the thread, the number of matched messages and total messages in the
19 thread, the names of all participants in the thread, and the subject of
20 the newest (or oldest) message.
22 See **notmuch-search-terms(7)** for details of the supported syntax for
25 Supported options for **search** include
27 ``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
28 Presents the results in either JSON, S-Expressions, newline
29 character separated plain-text (default), or null character
30 separated plain-text (compatible with **xargs(1)** -0 option where
33 ``--format-version=N``
34 Use the specified structured output format version. This is
35 intended for programs that invoke **notmuch(1)** internally. If
36 omitted, the latest supported version will be used.
38 ``--output=(summary|threads|messages|files|tags)``
40 Output a summary of each thread with any message matching the
41 search terms. The summary includes the thread ID, date, the
42 number of messages in the thread (both the number matched and
43 the total number), the authors of the thread and the
44 subject. In the case where a thread contains multiple files
45 for some messages, the total number of files is printed in
46 parentheses (see below for an example).
49 Output the thread IDs of all threads with any message matching
50 the search terms, either one per line (``--format=text``),
51 separated by null characters (``--format=text0``), as a JSON array
52 (``--format=json``), or an S-Expression list (``--format=sexp``).
55 Output the message IDs of all messages matching the search
56 terms, either one per line (``--format=text``), separated by null
57 characters (``--format=text0``), as a JSON array (``--format=json``),
58 or as an S-Expression list (``--format=sexp``).
61 Output the filenames of all messages matching the search
62 terms, either one per line (``--format=text``), separated by null
63 characters (``--format=text0``), as a JSON array (``--format=json``),
64 or as an S-Expression list (``--format=sexp``).
66 Note that each message may have multiple filenames associated
67 with it. All of them are included in the output (unless
68 limited with the ``--duplicate=N`` option). This may be
69 particularly confusing for **folder:** or **path:** searches
70 in a specified directory, as the messages may have duplicates
71 in other directories that are included in the output, although
72 these files alone would not match the search.
75 Output all tags that appear on any message matching the search
76 terms, either one per line (``--format=text``), separated by null
77 characters (``--format=text0``), as a JSON array (``--format=json``),
78 or as an S-Expression list (``--format=sexp``).
80 ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
81 This option can be used to present results in either chronological
82 order (**oldest-first**) or reverse chronological order
85 Note: The thread order will be distinct between these two options
86 (beyond being simply reversed). When sorting by **oldest-first**
87 the threads will be sorted by the oldest message in each thread,
88 but when sorting by **newest-first** the threads will be sorted by
89 the newest message in each thread.
91 By default, results will be displayed in reverse chronological
92 order, (that is, the newest results will be displayed first).
95 Skip displaying the first N results. With the leading '-', start
96 at the Nth result from the end.
99 Limit the number of displayed results to N.
101 ``--exclude=(true|false|all|flag)``
102 A message is called "excluded" if it matches at least one tag in
103 search.tag\_exclude that does not appear explicitly in the search
104 terms. This option specifies whether to omit excluded messages in
108 Prevent excluded messages from matching the search terms.
111 Additionally prevent excluded messages from appearing in
112 displayed results, in effect behaving as though the excluded
113 messages do not exist.
116 Allow excluded messages to match search terms and appear in
117 displayed results. Excluded messages are still marked in the
121 Only has an effect when ``--output=summary``. The output is
122 almost identical to **false**, but the "match count" is the
123 number of matching non-excluded messages in the thread, rather
124 than the number of matching messages.
127 For ``--output=files``, output the Nth filename associated with
128 each message matching the query (N is 1-based). If N is greater
129 than the number of files associated with the message, don't print
132 For ``--output=messages``, only output message IDs of messages
133 matching the search terms that have at least N filenames
134 associated with them.
136 Note that this option is orthogonal with the **folder:** search
137 prefix. The prefix matches messages based on filenames. This
138 option filters filenames of the matching messages.
143 The following shows an example of the summary output format, with one
144 message having multiple filenames.
148 % notmuch search date:today.. and tag:bad-news
149 thread:0000000000063c10 Today [1/1] Some Persun; To the bone (bad-news inbox unread)
150 thread:0000000000063c25 Today [1/1(2)] Ann Other; Bears (bad-news inbox unread)
151 thread:0000000000063c00 Today [1/1] A Thurd; Bites, stings, sad feelings (bad-news unread)
156 This command supports the following special exit status codes
159 The requested format version is too old.
162 The requested format version is too new.
168 **notmuch-config(1)**,
169 **notmuch-count(1)**,
171 **notmuch-hooks(5)**,
172 **notmuch-insert(1)**,
174 **notmuch-reply(1)**,
175 **notmuch-restore(1)**,
176 **notmuch-search-terms(7)**,
179 **notmuch-address(1)**