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

XAPIAN FIELD PROCESSORS

389       Certain optional features of the notmuch query processor  rely  on  the
390       presence  of  the Xapian field processor API. You can determine if your
391       notmuch was built against a sufficiently recent version  of  Xapian  by
392       running
393
394          % notmuch config get built_with.field_processor
395
396       Currently the following features require field processor support:
397
398       · non-range date queries, e.g. "date:today"
399
400       · named queries e.g. "query:my_special_query"
401
402       · regular expression searches, e.g. "subject:/^\[SPAM\]/"
403
404       · thread subqueries, e.g. "thread:{from:bob}"
405

SEE ALSO

407       notmuch(1),  notmuch-config(1), notmuch-count(1), notmuch-dump(1), not‐
408       much-hooks(5), notmuch-insert(1),  notmuch-new(1),  notmuch-reindex(1),
409       notmuch-properties(1),   *notmuch-reply(1),   notmuch-restore(1),  not‐
410       much-search(1), *notmuch-show(1), notmuch-tag(1)
411

AUTHOR

413       Carl Worth and many others
414
416       2009-2018, Carl Worth and many others
417
418
419
420
4210.27                             Jul 16, 2018          NOTMUCH-SEARCH-TERMS(7)
Impressum