10 **notmuch** **search** [*option* ...] <*search-term*> ...
15 Search for messages matching the given search terms, and display as
16 results the threads containing the matched messages.
18 The output consists of one line per thread, giving a thread ID, the date
19 of the newest (or oldest, depending on the sort option) matched message
20 in the thread, the number of matched messages and total messages in the
21 thread, the names of all participants in the thread, and the subject of
22 the newest (or oldest) message.
24 See :any:`notmuch-search-terms(7)` for details of the supported syntax for
27 Supported options for **search** include
31 .. option:: --format=(json|sexp|text|text0)
33 Presents the results in either JSON, S-Expressions, newline
34 character separated plain-text (default), or null character
35 separated plain-text (compatible with :manpage:`xargs(1)` -0
36 option where available).
38 .. option:: --format-version=N
40 Use the specified structured output format version. This is
41 intended for programs that invoke :any:`notmuch(1)` internally. If
42 omitted, the latest supported version will be used.
44 .. option:: --output=(summary|threads|messages|files|tags)
47 Output a summary of each thread with any message matching the
48 search terms. The summary includes the thread ID, date, the
49 number of messages in the thread (both the number matched and
50 the total number), the authors of the thread and the
51 subject. In the case where a thread contains multiple files
52 for some messages, the total number of files is printed in
53 parentheses (see below for an example).
56 Output the thread IDs of all threads with any message matching
57 the search terms, either one per line (``--format=text``),
58 separated by null characters (``--format=text0``), as a JSON array
59 (``--format=json``), or an S-Expression list (``--format=sexp``).
62 Output the message IDs of all messages matching the search
63 terms, either one per line (``--format=text``), separated by null
64 characters (``--format=text0``), as a JSON array (``--format=json``),
65 or as an S-Expression list (``--format=sexp``).
68 Output the filenames of all messages matching the search
69 terms, either one per line (``--format=text``), separated by null
70 characters (``--format=text0``), as a JSON array (``--format=json``),
71 or as an S-Expression list (``--format=sexp``).
73 Note that each message may have multiple filenames associated
74 with it. All of them are included in the output (unless
75 limited with the ``--duplicate=N`` option). This may be
76 particularly confusing for **folder:** or **path:** searches
77 in a specified directory, as the messages may have duplicates
78 in other directories that are included in the output, although
79 these files alone would not match the search.
82 Output all tags that appear on any message matching the search
83 terms, either one per line (``--format=text``), separated by null
84 characters (``--format=text0``), as a JSON array (``--format=json``),
85 or as an S-Expression list (``--format=sexp``).
87 .. option:: --sort=(newest-first|oldest-first)
89 This option can be used to present results in either chronological
90 order (**oldest-first**) or reverse chronological order
93 Note: The thread order will be distinct between these two options
94 (beyond being simply reversed). When sorting by **oldest-first**
95 the threads will be sorted by the oldest message in each thread,
96 but when sorting by **newest-first** the threads will be sorted by
97 the newest message in each thread.
99 By default, results will be displayed in reverse chronological
100 order, (that is, the newest results will be displayed first).
102 .. option:: --offset=[-]N
104 Skip displaying the first N results. With the leading '-', start
105 at the Nth result from the end.
107 .. option:: --limit=N
109 Limit the number of displayed results to N.
111 .. option:: --exclude=(true|false|all|flag)
113 A message is called "excluded" if it matches at least one tag in
114 search.exclude\_tags that does not appear explicitly in the search
115 terms. This option specifies whether to omit excluded messages in
119 Prevent excluded messages from matching the search terms.
122 Additionally prevent excluded messages from appearing in
123 displayed results, in effect behaving as though the excluded
124 messages do not exist.
127 Allow excluded messages to match search terms and appear in
128 displayed results. Excluded messages are still marked in the
132 Only has an effect when ``--output=summary``. The output is
133 almost identical to **false**, but the "match count" is the
134 number of matching non-excluded messages in the thread, rather
135 than the number of matching messages.
137 .. option:: --duplicate=N
139 For ``--output=files``, output the Nth filename associated with
140 each message matching the query (N is 1-based). If N is greater
141 than the number of files associated with the message, don't print
144 For ``--output=messages``, only output message IDs of messages
145 matching the search terms that have at least N filenames
146 associated with them.
148 Note that this option is orthogonal with the **folder:** search
149 prefix. The prefix matches messages based on filenames. This
150 option filters filenames of the matching messages.
155 The following shows an example of the summary output format, with one
156 message having multiple filenames.
160 % notmuch search date:today.. and tag:bad-news
161 thread:0000000000063c10 Today [1/1] Some Persun; To the bone (bad-news inbox unread)
162 thread:0000000000063c25 Today [1/1(2)] Ann Other; Bears (bad-news inbox unread)
163 thread:0000000000063c00 Today [1/1] A Thurd; Bites, stings, sad feelings (bad-news unread)
168 This command supports the following special exit status codes
171 The requested format version is too old.
174 The requested format version is too new.
180 :any:`notmuch-address(1)`
181 :any:`notmuch-config(1)`,
182 :any:`notmuch-count(1)`,
183 :any:`notmuch-dump(1)`,
184 :any:`notmuch-hooks(5)`,
185 :any:`notmuch-insert(1)`,
186 :any:`notmuch-new(1)`,
187 :any:`notmuch-reply(1)`,
188 :any:`notmuch-restore(1)`,
189 :any:`notmuch-search-terms(7)`,
190 :any:`notmuch-show(1)`,
191 :any:`notmuch-tag(1)`