1 <h1>NOTMUCH-SEARCH-TERMS(7)</h1>
5 notmuch-search-terms - syntax for notmuch queries
10 <b>notmuch</b> <b>count</b> [option ...] <<u>search-term</u>> ...
12 <b>notmuch</b> <b>dump</b> [--format=(batch-tag|sup)] [--] [--output=<<u>file</u>>] [--]
13 [<<u>search-term</u>> ...]
15 <b>notmuch</b> <b>search</b> [option ...] <<u>search-term</u>> ...
17 <b>notmuch</b> <b>show</b> [option ...] <<u>search-term</u>> ...
19 <b>notmuch</b> <b>tag</b> +<<u>tag</u>> ... -<<u>tag</u>> [--] <<u>search-term</u>> ...
24 Several notmuch commands accept a common syntax for search terms.
26 The search terms can consist of free-form text (and quoted phrases)
27 which will match all messages that contain all of the given
28 terms/phrases in the body, the subject, or any of the sender or recipi‐
31 As a special case, a search string consisting of exactly a single
32 asterisk ("*") will match all messages.
34 In addition to free text, the following prefixes can be used to force
35 terms to match against specific portions of an email, (where <brackets>
36 indicate user-supplied values):
38 · from:<name-or-address>
40 · to:<name-or-address>
42 · subject:<word-or-quoted-phrase>
44 · attachment:<word>
46 · tag:<tag> (or is:<tag>)
48 · id:<message-id>
50 · thread:<thread-id>
52 · folder:<maildir-folder>
54 · path:<directory-path> or path:<directory-path>/**
56 · date:<since>..<until>
58 The <b>from:</b> prefix is used to match the name or address of the sender of
61 The <b>to:</b> prefix is used to match the names or addresses of any recipient
62 of an email message, (whether To, Cc, or Bcc).
64 Any term prefixed with <b>subject:</b> will match only text from the subject
65 of an email. Searching for a phrase in the subject is supported by
66 including quotation marks around the phrase, immediately following <b>sub-</b>
69 The <b>attachment:</b> prefix can be used to search for specific filenames (or
70 extensions) of attachments to email messages.
72 For <b>tag:</b> and <b>is:</b> valid tag values include <b>inbox</b> and <b>unread</b> by default
73 for new messages added by <b>notmuch</b> <b>new</b> as well as any other tag values
74 added manually with <b>notmuch</b> <b>tag</b>.
76 For <b>id:</b>, message ID values are the literal contents of the Message-ID:
77 header of email messages, but without the '<', '>' delimiters.
79 The <b>thread:</b> prefix can be used with the thread ID values that are gen‐
80 erated internally by notmuch (and do not appear in email messages).
81 These thread ID values can be seen in the first column of output from
82 <b>notmuch</b> <b>search</b>
84 The <b>path:</b> prefix searches for email messages that are in particular
85 directories within the mail store. The directory must be specified rel‐
86 ative to the top-level maildir (and without the leading slash). By
87 default, <b>path:</b> matches messages in the specified directory only. The
88 "/**" suffix can be used to match messages in the specified directory
89 and all its subdirectories recursively. <b>path:""</b> matches messages in
90 the root of the mail store and, likewise, <b>path:**</b> matches all messages.
92 The <b>folder:</b> prefix searches for email messages by maildir or MH folder.
93 For MH-style folders, this is equivalent to <b>path:</b>. For maildir, this
94 includes messages in the "new" and "cur" subdirectories. The exact syn‐
95 tax for maildir folders depends on your mail configuration. For
96 maildir++, <b>folder:""</b> matches the inbox folder (which is the root in
97 maildir++), other folder names always start with ".", and nested fold‐
98 ers are separated by "."s, such as <b>folder:.classes.topology</b>. For "file
99 system" maildir, the inbox is typically <b>folder:INBOX</b> and nested folders
100 are separated by slashes, such as <b>folder:classes/topology</b>.
102 Both <b>path:</b> and <b>folder:</b> will find a message if <u>any</u> copy of that message
103 is in the specific directory/folder.
105 The <b>date:</b> prefix can be used to restrict the results to only messages
106 within a particular time range (based on the Date: header) with a range
109 date:<since>..<until>
111 See <b>DATE</b> <b>AND</b> <b>TIME</b> <b>SEARCH</b> below for details on the range expression, and
112 supported syntax for <since> and <until> date and time expressions.
114 The time range can also be specified using timestamps with a syntax of:
116 <initial-timestamp>..<final-timestamp>
118 Each timestamp is a number representing the number of seconds since
119 1970-01-01 00:00:00 UTC.
121 In addition to individual terms, multiple terms can be combined with
122 Boolean operators ( <b>and</b>, <b>or</b>, <b>not</b> , etc.). Each term in the query will
123 be implicitly connected by a logical AND if no explicit operator is
124 provided, (except that terms with a common prefix will be implicitly
125 combined with OR until we get Xapian defect #402 fixed).
127 Parentheses can also be used to control the combination of the Boolean
128 operators, but will have to be protected from interpretation by the
129 shell, (such as by putting quotation marks around any parenthesized
133 <h2>DATE AND TIME SEARCH</h2>
135 notmuch understands a variety of standard and natural ways of express‐
136 ing dates and times, both in absolute terms ("2012-10-24") and in rela‐
137 tive terms ("yesterday"). Any number of relative terms can be combined
138 ("1 hour 25 minutes") and an absolute date/time can be combined with
139 relative terms to further adjust it. A non-exhaustive description of
140 the syntax supported for absolute and relative terms is given below.
143 <h3> The range expression</h3>
145 date:<since>..<until>
147 The above expression restricts the results to only messages from
148 <since> to <until>, based on the Date: header.
150 <since> and <until> can describe imprecise times, such as "yesterday".
151 In this case, <since> is taken as the earliest time it could describe
152 (the beginning of yesterday) and <until> is taken as the latest time it
153 could describe (the end of yesterday). Similarly, date:january..febru‐
154 ary matches from the beginning of January to the end of February.
156 Currently, we do not support spaces in range expressions. You can
157 replace the spaces with '_', or (in most cases) '-', or (in some cases)
158 leave the spaces out altogether. Examples in this man page use spaces
161 Open-ended ranges are supported (since Xapian 1.2.1), i.e. it's possi‐
162 ble to specify date:..<until> or date:<since>.. to not limit the start
163 or end time, respectively. Pre-1.2.1 Xapian does not report an error on
164 open ended ranges, but it does not work as expected either.
166 Entering date:expr without ".." (for example date:yesterday) won't
167 work, as it's not interpreted as a range expression at all. You can
168 achieve the expected result by duplicating the expr both sides of ".."
169 (for example date:yesterday..yesterday).
172 <h3> Relative date and time</h3>
174 [N|number] (years|months|weeks|days|hours|hrs|minutes|mins|sec‐
177 All refer to past, can be repeated and will be accumulated.
179 Units can be abbreviated to any length, with the otherwise ambiguous
180 single m being m for minutes and M for months.
182 Number can also be written out one, two, ..., ten, dozen, hundred.
183 Additionally, the unit may be preceded by "last" or "this" (e.g., "last
184 week" or "this month").
186 When combined with absolute date and time, the relative date and time
187 specification will be relative from the specified absolute date and
190 Examples: 5M2d, two weeks
193 <h3> Supported absolute time formats</h3>
195 · H[H]:MM[:SS] [(am|a.m.|pm|p.m.)]
197 · H[H] (am|a.m.|pm|p.m.)
207 · Examples: 17:05, 5pm
210 <h3> Supported absolute date formats</h3>
224 · D[D][(st|nd|rd|th)] Mon[thname] [YYYY]
226 · Mon[thname] D[D][(st|nd|rd|th)] [YYYY]
230 Month names can be abbreviated at three or more characters.
232 Weekday names can be abbreviated at three or more characters.
234 Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3
237 <h3> Time zones</h3>
243 Some time zone codes, e.g. UTC, EET.
248 <a href='../notmuch-1/'>notmuch</a>(1), <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not‐</a>
249 <a href='../notmuch-hooks-5/'>much-hooks</a>(5), <a href='../notmuch-insert-1/'>notmuch-insert</a>(1), <a href='../notmuch-new-1/'>notmuch-new</a>(1), <a href='../notmuch-reply-1/'>notmuch-reply</a>(1),
250 <a href='../notmuch-restore-1/'>notmuch-restore</a>(1), <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
255 Carl Worth and many others
260 2014, Carl Worth and many others