git.notmuchmail.org Git - notmuch/blob - doc/man7/notmuch-search-terms.rst

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