git.notmuchmail.org Git - notmuch-wiki/blob - manpages/notmuch-search-terms-7.mdwn

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