1NOTMUCH-SEARCH-TERMS(7)             notmuch            NOTMUCH-SEARCH-TERMS(7)
2
3
4

NAME

6       notmuch-search-terms - syntax for notmuch queries
7

SYNOPSIS

9       notmuch count [option ...] <search-term> ...
10
11       notmuch dump [--gzip] [--format=(batch-tag|sup)] [--output=<file>] [--]
12       [<search-term> ...]
13
14       notmuch reindex [option ...] <search-term> ...
15
16       notmuch search [option ...] <search-term> ...
17
18       notmuch show [option ...] <search-term> ...
19
20       notmuch tag +<tag> ... -<tag> [--] <search-term> ...
21

DESCRIPTION

23       Several notmuch commands accept a common syntax for search terms.
24
25       The search terms can consist of free-form  text  (and  quoted  phrases)
26       which   will   match  all  messages  that  contain  all  of  the  given
27       terms/phrases in the body, the subject, or any of the sender or recipi‐
28       ent headers.
29
30       As  a  special case, a search string consisting of exactly a single as‐
31       terisk ("*") will match all messages.
32
33   Search prefixes
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).
37
38       Some of the prefixes with <regex> forms can be also  used  to  restrict
39       the  results  to  those  whose  value matches a regular expression (see
40       regex(7)) delimited with //, for example:
41
42          notmuch search 'from:"/bob@.*[.]example[.]com/"'
43
44       body:<word-or-quoted-phrase>
45              Match terms in the body of messages.
46
47       from:<name-or-address> or from:/<regex>/
48              The from: prefix is used to match the name  or  address  of  the
49              sender of an email message.
50
51       to:<name-or-address>
52              The  to:  prefix  is used to match the names or addresses of any
53              recipient of an email message, (whether To, Cc, or Bcc).
54
55       subject:<word-or-quoted-phrase> or subject:/<regex>/
56              Any term prefixed with subject: will match only  text  from  the
57              subject  of  an  email. Searching for a phrase in the subject is
58              supported by including quotation marks around the phrase,  imme‐
59              diately following subject:.
60
61       attachment:<word>
62              The  attachment: prefix can be used to search for specific file‐
63              names (or extensions) of attachments to email messages.
64
65       mimetype:<word>
66              The mimetype: prefix will be used to match text  from  the  con‐
67              tent-types  of MIME parts within email messages (as specified by
68              the sender).
69
70       tag:<tag> or tag:/<regex>/ or is:<tag> or is:/<regex>/
71              For tag: and is: valid tag values include inbox  and  unread  by
72              default  for  new  messages  added by notmuch new as well as any
73              other tag values added manually with notmuch tag.
74
75       id:<message-id> or mid:<message-id> or mid:/<regex>/
76              For id: and mid:, message ID values are the literal contents  of
77              the  Message-ID:  header of email messages, but without the '<',
78              '>' delimiters.
79
80       thread:<thread-id>
81              The thread: prefix can be used with the thread  ID  values  that
82              are  generated internally by notmuch (and do not appear in email
83              messages). These thread ID values can be seen in the first  col‐
84              umn of output from notmuch search
85
86       thread:{<notmuch query>}
87              Threads may be searched for indirectly by providing an arbitrary
88              notmuch query in {}. For example, the following returns  threads
89              containing  a  message from mallory and one (not necessarily the
90              same message) with Subject containing the word "crypto".
91
92                 % notmuch search 'thread:"{from:mallory}" and thread:"{subject:crypto}"'
93
94              The performance of such queries can vary wildly.  To  understand
95              this, the user should think of the query thread:{<something>} as
96              expanding to all of the thread IDs which match <something>; not‐
97              much then performs a second search using the expanded query.
98
99       path:<directory-path> or path:<directory-path>/** or path:/<regex>/
100              The path: prefix searches for email messages that are in partic‐
101              ular directories within the mail store. The  directory  must  be
102              specified  relative  to  the  top-level maildir (and without the
103              leading slash). By default, path: matches messages in the speci‐
104              fied  directory only. The "/**" suffix can be used to match mes‐
105              sages in the specified directory and all its subdirectories  re‐
106              cursively.  path:""  matches  messages  in  the root of the mail
107              store and, likewise, path:** matches all messages.
108
109              path: will find a message if any copy of that message is in  the
110              specific directory.
111
112       folder:<maildir-folder> or folder:/<regex>/
113              The  folder: prefix searches for email messages by maildir or MH
114              folder. For MH-style folders, this is equivalent to  path:.  For
115              maildir, this includes messages in the "new" and "cur" subdirec‐
116              tories. The exact syntax for maildir  folders  depends  on  your
117              mail  configuration.  For maildir++, folder:"" matches the inbox
118              folder (which is the root in maildir++), other folder names  al‐
119              ways  start  with ".", and nested folders are separated by "."s,
120              such as folder:.classes.topology. For "file system" maildir, the
121              inbox is typically folder:INBOX and nested folders are separated
122              by slashes, such as folder:classes/topology.
123
124              folder: will find a message if any copy of that  message  is  in
125              the specific folder.
126
127       date:<since>..<until> or date:<date>
128              The  date:  prefix  can  be used to restrict the results to only
129              messages within a particular time  range  (based  on  the  Date:
130              header).
131
132              See  DATE AND TIME SEARCH below for details on the range expres‐
133              sion, and supported syntax for <since> and <until> date and time
134              expressions.
135
136              The  time  range  can also be specified using timestamps without
137              including the date prefix using a syntax of:
138
139              <initial-timestamp>..<final-timestamp>
140
141              Each timestamp is a number representing the  number  of  seconds
142              since  1970-01-01 00:00:00 UTC. Specifying a time range this way
143              is considered legacy and predates the date prefix.
144
145       lastmod:<initial-revision>..<final-revision>
146              The lastmod: prefix can be used to restrict the  result  by  the
147              database  revision  number  of  when messages were last modified
148              (tags were added/removed or filenames changed). This is  usually
149              used  in  conjunction with the --uuid argument to notmuch search
150              to find messages that have changed since an earlier query.
151
152       query:<name>
153              The query: prefix allows queries to refer  to  previously  saved
154              queries added with notmuch-config(1).
155
156       property:<key>=<value>
157              The  property:  prefix  searches  for messages with a particular
158              <key>=<value> property pair. Properties are used  internally  by
159              notmuch  (and  extensions)  to add metadata to messages. A given
160              key can be present on a given  message  with  several  different
161              values.  See notmuch-properties(7) for more details.
162
163       User defined prefixes are also supported, see notmuch-config(1) for de‐
164       tails.
165
166   Operators
167       In addition to individual terms, multiple terms can  be  combined  with
168       Boolean  operators (and, or, not, and xor). Each term in the query will
169       be implicitly connected by a logical AND if  no  explicit  operator  is
170       provided  (except  that  terms  with a common prefix will be implicitly
171       combined with OR).  The  shorthand  '-<term>'  can  be  used  for  'not
172       <term>' but unfortunately this does not work at the start of an expres‐
173       sion.  Parentheses can also be used to control the combination  of  the
174       Boolean operators, but will have to be protected from interpretation by
175       the shell, (such as by putting quotation marks around any parenthesized
176       expression).
177
178       In  addition to the standard boolean operators, Xapian provides several
179       operators specific to text searching.
180
181          notmuch search term1 NEAR term2
182
183       will return results where term1  is  within  10  words  of  term2.  The
184       threshold can be set like this:
185
186          notmuch search term1 NEAR/2 term2
187
188       The search
189
190          notmuch search term1 ADJ term2
191
192       will return results where term1 is within 10 words of term2, but in the
193       same order as in the query. The threshold can be set the same  as  with
194       NEAR:
195
196          notmuch search term1 ADJ/7 term2
197
198   Stemming
199       Stemming in notmuch means that these searches
200
201          notmuch search detailed
202          notmuch search details
203          notmuch search detail
204
205       will  all  return identical results, because Xapian first "reduces" the
206       term to the common stem (here 'detail') and then performs the search.
207
208       There are two ways to turn this off: a search for  a  capitalized  word
209       will  be performed unstemmed, so that one can search for "John" and not
210       get results for "Johnson"; phrase searches are also unstemmed (see  be‐
211       low  for  details).   Stemming is currently only supported for English.
212       Searches for words in other languages will be performed unstemmed.
213
214   Wildcards
215       It is possible to use a trailing  '*'  as  a  wildcard.  A  search  for
216       'wildc*' will match 'wildcard', 'wildcat', etc.
217
218   Boolean and Probabilistic Prefixes
219       Xapian  (and hence notmuch) prefixes are either boolean, supporting ex‐
220       act matches like "tag:inbox" or probabilistic, supporting a more flexi‐
221       ble  term  based  searching.  Certain special prefixes are processed by
222       notmuch in a way not strictly  fitting  either  of  Xapian's  built  in
223       styles. The prefixes currently supported by notmuch are as follows.
224
225       Boolean
226              tag:, id:, thread:, folder:, path:, property:
227
228       Probabilistic
229              body:, to:, attachment:, mimetype:
230
231       Special
232              from:, query:, subject:
233
234   Terms and phrases
235       In  general  Xapian  distinguishes  between lists of terms and phrases.
236       Phrases are indicated by double quotes (but beware you probably need to
237       protect  those  from  your shell) and insist that those unstemmed words
238       occur in that order. One useful, but initially  surprising  feature  is
239       that the following are equivalent ways to write the same phrase.
240
241       • "a list of words"
242
243       • a-list-of-words
244
245       • a/list/of/words
246
247       • a.list.of.words
248
249       Both parenthesised lists of terms and quoted phrases are ok with proba‐
250       bilistic prefixes such as to:, from:, and subject:. In particular
251
252          subject:(pizza free)
253
254       is equivalent to
255
256          subject:pizza and subject:free
257
258       Both of these will match a subject "Free Delicious Pizza" while
259
260          subject:"pizza free"
261
262       will not.
263
264   Quoting
265       Double quotes are also used by the  notmuch  query  parser  to  protect
266       boolean  terms, regular expressions, or subqueries containing spaces or
267       other special characters, e.g.
268
269          tag:"a tag"
270
271          folder:"/^.*/(Junk|Spam)$/"
272
273          thread:"{from:mallory and date:2009}"
274
275       As with phrases, you need to protect the double quotes from  the  shell
276       e.g.
277
278          % notmuch search 'folder:"/^.*/(Junk|Spam)$/"'
279          % notmuch search 'thread:"{from:mallory and date:2009}" and thread:{to:mallory}'
280
282       notmuch  understands a variety of standard and natural ways of express‐
283       ing dates and times, both in absolute terms ("2012-10-24") and in rela‐
284       tive  terms ("yesterday"). Any number of relative terms can be combined
285       ("1 hour 25 minutes") and an absolute date/time can  be  combined  with
286       relative  terms  to  further adjust it. A non-exhaustive description of
287       the syntax supported for absolute and relative terms is given below.
288
289   The range expression
290       date:<since>..<until>
291
292       The above expression  restricts  the  results  to  only  messages  from
293       <since> to <until>, based on the Date: header.
294
295       <since>  and <until> can describe imprecise times, such as "yesterday".
296       In this case, <since> is taken as the earliest time it  could  describe
297       (the beginning of yesterday) and <until> is taken as the latest time it
298       could describe (the end of yesterday). Similarly,  date:january..febru‐
299       ary matches from the beginning of January to the end of February.
300
301       If  specifying  a  time  range using timestamps in conjunction with the
302       date prefix, each timestamp must be preceded by @ (ASCII  hex  40).  As
303       above,  each  timestamp  is a number representing the number of seconds
304       since 1970-01-01 00:00:00 UTC. For example:
305          date:@<initial-timestamp>..@<final-timestamp>
306
307       Currently, spaces in range expressions are not supported. You  can  re‐
308       place  the  spaces with '_', or (in most cases) '-', or (in some cases)
309       leave the spaces out altogether. Examples in this man page  use  spaces
310       for clarity.
311
312       Open-ended   ranges  are  supported.  I.e.  it's  possible  to  specify
313       date:..<until> or date:<since>.. to not limit the start  or  end  time,
314       respectively.
315
316   Single expression
317       date:<expr> works as a shorthand for date:<expr>..<expr>.  For example,
318       date:monday matches from the beginning of Monday until the end of  Mon‐
319       day.
320
321   Relative date and time
322       [N|number]         (years|months|weeks|days|hours|hrs|minutes|mins|sec‐
323       onds|secs) [...]
324
325       All refer to past, can be repeated and will be accumulated.
326
327       Units can be abbreviated to any length, with  the  otherwise  ambiguous
328       single m being m for minutes and M for months.
329
330       Number can also be written out one, two, ..., ten, dozen, hundred.  Ad‐
331       ditionally, the unit may be preceded by "last" or "this"  (e.g.,  "last
332       week" or "this month").
333
334       When  combined  with absolute date and time, the relative date and time
335       specification will be relative from the  specified  absolute  date  and
336       time.
337
338       Examples: 5M2d, two weeks
339
340   Supported absolute time formats
341       • H[H]:MM[:SS] [(am|a.m.|pm|p.m.)]
342
343       • H[H] (am|a.m.|pm|p.m.)
344
345       • HHMMSS
346
347       • now
348
349       • noon
350
351       • midnight
352
353       • Examples: 17:05, 5pm
354
355   Supported absolute date formats
356       • YYYY-MM[-DD]
357
358       • DD-MM[-[YY]YY]
359
360       • MM-YYYY
361
362       • M[M]/D[D][/[YY]YY]
363
364       • M[M]/YYYY
365
366       • D[D].M[M][.[YY]YY]
367
368       • D[D][(st|nd|rd|th)] Mon[thname] [YYYY]
369
370       • Mon[thname] D[D][(st|nd|rd|th)] [YYYY]
371
372       • Wee[kday]
373
374       Month names can be abbreviated at three or more characters.
375
376       Weekday names can be abbreviated at three or more characters.
377
378       Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3
379
380   Time zones
381       • (+|-)HH:MM
382
383       • (+|-)HH[MM]
384
385       Some time zone codes, e.g. UTC, EET.
386

SEE ALSO

388       notmuch(1),  notmuch-config(1), notmuch-count(1), notmuch-dump(1), not‐
389       much-hooks(5), notmuch-insert(1),  notmuch-new(1),  notmuch-reindex(1),
390       notmuch-properties(1),   *notmuch-reply(1),   notmuch-restore(1),  not‐
391       much-search(1), *notmuch-show(1), notmuch-tag(1)
392

AUTHOR

394       Carl Worth and many others
395
397       2009-2021, Carl Worth and many others
398
399
400
401
4020.32.1                           May 17, 2021          NOTMUCH-SEARCH-TERMS(7)
Impressum