X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=manpages%2Fnotmuch-search-terms-7.mdwn;h=f92b7c4e791b7d3b24bdcac5f7f2bbdd2d8006a4;hb=59f84c9ae70b6bd672660879e2be63f3c541082d;hp=b36c16b2fe0a7f3674f75d737c3f6b9ddc7944ee;hpb=bf4ac2a31d4b8220d28b36de018a4ad516d60baf;p=notmuch-wiki diff --git a/manpages/notmuch-search-terms-7.mdwn b/manpages/notmuch-search-terms-7.mdwn index b36c16b..f92b7c4 100644 --- a/manpages/notmuch-search-terms-7.mdwn +++ b/manpages/notmuch-search-terms-7.mdwn @@ -37,10 +37,14 @@ · from:<name-or-address> + · from:/<regex>/ + · to:<name-or-address> · subject:<word-or-quoted-phrase> + · subject:/<regex>/ + · attachment:<word> · mimetype:<word> @@ -59,6 +63,10 @@ · lastmod:<initial-revision>..<final-revision> + · query:<name> + + · property:<key>=<value> + The from: prefix is used to match the name or address of the sender of an email message. @@ -70,46 +78,53 @@ including quotation marks around the phrase, immediately following sub- ject:. + If notmuch is built with Xapian Field Processors (see below) the from: + and subject prefix can be also used to restrict the results to those + whose from/subject value matches a regular expression (see regex(7)) + delimited with //. + + notmuch search 'from:/bob@.*[.]example[.]com/' + The attachment: prefix can be used to search for specific filenames (or extensions) of attachments to email messages. - The mimetype: prefix will be used to match text from the content-types + The mimetype: prefix will be used to match text from the content-types of MIME parts within email messages (as specified by the sender). - For tag: and is: valid tag values include inbox and unread by default - for new messages added by notmuch new as well as any other tag values + For tag: and is: valid tag values include inbox and unread by default + for new messages added by notmuch new as well as any other tag values added manually with notmuch tag. - For id:, message ID values are the literal contents of the Message-ID: + For id:, message ID values are the literal contents of the Message-ID: header of email messages, but without the '<', '>' delimiters. - The thread: prefix can be used with the thread ID values that are gen‐ - erated internally by notmuch (and do not appear in email messages). - These thread ID values can be seen in the first column of output from + The thread: prefix can be used with the thread ID values that are gen‐ + erated internally by notmuch (and do not appear in email messages). + These thread ID values can be seen in the first column of output from notmuch search - The path: prefix searches for email messages that are in particular + The path: prefix searches for email messages that are in particular directories within the mail store. The directory must be specified rel‐ - ative to the top-level maildir (and without the leading slash). By - default, path: matches messages in the specified directory only. The - "/**" suffix can be used to match messages in the specified directory - and all its subdirectories recursively. path:"" matches messages in + ative to the top-level maildir (and without the leading slash). By + default, path: matches messages in the specified directory only. The + "/**" suffix can be used to match messages in the specified directory + and all its subdirectories recursively. path:"" matches messages in the root of the mail store and, likewise, path:** matches all messages. The folder: prefix searches for email messages by maildir or MH folder. - For MH-style folders, this is equivalent to path:. For maildir, this + For MH-style folders, this is equivalent to path:. For maildir, this includes messages in the "new" and "cur" subdirectories. The exact syn‐ - tax for maildir folders depends on your mail configuration. For - maildir++, folder:"" matches the inbox folder (which is the root in - maildir++), other folder names always start with ".", and nested fold‐ - ers are separated by "."s, such as folder:.classes.topology. For "file + tax for maildir folders depends on your mail configuration. For + maildir++, folder:"" matches the inbox folder (which is the root in + maildir++), other folder names always start with ".", and nested fold‐ + ers are separated by "."s, such as folder:.classes.topology. For "file system" maildir, the inbox is typically folder:INBOX and nested folders are separated by slashes, such as folder:classes/topology. - Both path: and folder: will find a message if any copy of that message + Both path: and folder: will find a message if any copy of that message is in the specific directory/folder. - The date: prefix can be used to restrict the results to only messages + The date: prefix can be used to restrict the results to only messages within a particular time range (based on the Date: header) with a range syntax of: @@ -122,14 +137,23 @@ <initial-timestamp>..<final-timestamp> - Each timestamp is a number representing the number of seconds since + Each timestamp is a number representing the number of seconds since 1970-01-01 00:00:00 UTC. - The lastmod: prefix can be used to restrict the result by the database + The lastmod: prefix can be used to restrict the result by the database revision number of when messages were last modified (tags were - added/removed or filenames changed). This is usually used in conjunc‐ - tion with the --uuid argument to notmuch search to find messages that + added/removed or filenames changed). This is usually used in conjunc‐ + tion with the --uuid argument to notmuch search to find messages that have changed since an earlier query. + + The query: prefix allows queries to refer to previously saved queries + added with notmuch-config(1). Named queries are only available if not‐ + much is built with Xapian Field Processors (see below). + + The property: prefix searches for messages with a particular + <key>=<value> property pair. Properties are used internally by notmuch + (and extensions) to add metadata to messages. A given key can be + present on a given message with several different values.

  Operators

@@ -194,25 +218,26 @@ 
        Xapian  (and  hence  notmuch)  prefixes  are either boolean, supporting
        exact matches like "tag:inbox"  or  probabilistic,  supporting  a  more
-       flexible term based searching. The prefixes currently supported by not‐
-       much are as follows.
-
-              ┌───────────────────────────┬────────────────────────────┐
-              │Boolean
-              ├───────────────────────────┼────────────────────────────┤
-              │
-              │
-              │       thread:     folder: │        subject:    attach‐ │
-              │       path:               │        ment: mimetype:     │
-              └───────────────────────────┴────────────────────────────┘
+       flexible  term  based searching. Certain special prefixes are processed
+       by notmuch in a way not stricly fitting either  of  Xapian's  built  in
+       styles. The prefixes currently supported by notmuch are as follows.
+
+       Boolean
+              tag:, id:, thread:, folder:, path:, property:
+
+       Probabilistic
+              to:, attachment:, mimetype:
+
+       Special
+              from:, query:, subject:

  Terms and phrases

-       In general Xapian distinguishes between lists  of  terms  and  phrases.
+       In  general  Xapian  distinguishes  between lists of terms and phrases.
        Phrases are indicated by double quotes (but beware you probably need to
-       protect those from your shell) and insist that  those  unstemmed  words
-       occur  in  that  order. One useful, but initially surprising feature is
+       protect  those  from  your shell) and insist that those unstemmed words
+       occur in that order. One useful, but initially  surprising  feature  is
        that the following are equivalant ways to write the same phrase.
 
        · "a list of words"
@@ -241,11 +266,11 @@
 
 
DATE AND TIME SEARCH

 
-       notmuch  understands a variety of standard and natural ways of express‐
+       notmuch understands a variety of standard and natural ways of  express‐
        ing dates and times, both in absolute terms ("2012-10-24") and in rela‐
-       tive  terms ("yesterday"). Any number of relative terms can be combined
-       ("1 hour 25 minutes") and an absolute date/time can  be  combined  with
-       relative  terms  to  further adjust it. A non-exhaustive description of
+       tive terms ("yesterday"). Any number of relative terms can be  combined
+       ("1  hour  25  minutes") and an absolute date/time can be combined with
+       relative terms to further adjust it. A  non-exhaustive  description  of
        the syntax supported for absolute and relative terms is given below.
 

 
@@ -253,23 +278,23 @@
 
        date:<since>..<until>
 
-       The above expression  restricts  the  results  to  only  messages  from
+       The  above  expression  restricts  the  results  to  only messages from
        <since> to <until>, based on the Date: header.
 
-       <since>  and <until> can describe imprecise times, such as "yesterday".
-       In this case, <since> is taken as the earliest time it  could  describe
+       <since> and <until> can describe imprecise times, such as  "yesterday".
+       In  this  case, <since> is taken as the earliest time it could describe
        (the beginning of yesterday) and <until> is taken as the latest time it
-       could describe (the end of yesterday). Similarly,  date:january..febru‐
+       could  describe (the end of yesterday). Similarly, date:january..febru‐
        ary matches from the beginning of January to the end of February.
 
-       date:<expr>..!  can be used as a shorthand for date:<expr>..<expr>. The
-       expansion takes place before interpretation,  and  thus,  for  example,
-       date:monday..!  matches  from  the beginning of Monday until the end of
-       Monday. (Note that  entering  date:<expr>  without  "..",  for  example
-       date:yesterday,  won't work, as it's not interpreted as a range expres‐
-       sion at all. Again, use date:yesterday..!)
+       date:<expr>..! can be used as a shorthand for date:<expr>..<expr>.  The
+       expansion  takes  place  before  interpretation, and thus, for example,
+       date:monday..! matches from the beginning of Monday until  the  end  of
+       Monday.   With  Xapian  Field  Processor support (see below), non-range
+       date queries such as date:yesterday will work, but otherwise will  give
+       unexpected results; if in doubt use date:yesterday..!
 
-       Currently, we do not support  spaces  in  range  expressions.  You  can
+       Currently,  we  do  not  support  spaces  in range expressions. You can
        replace the spaces with '_', or (in most cases) '-', or (in some cases)
        leave  the  spaces out altogether. Examples in this man page use spaces
        for clarity.
@@ -287,15 +312,15 @@
 
        All refer to past, can be repeated and will be accumulated.
 
-       Units  can  be  abbreviated to any length, with the otherwise ambiguous
+       Units can be abbreviated to any length, with  the  otherwise  ambiguous
        single m being m for minutes and M for months.
 
-       Number can also be written out one,  two,  ...,  ten,  dozen,  hundred.
+       Number  can  also  be  written  out one, two, ..., ten, dozen, hundred.
        Additionally, the unit may be preceded by "last" or "this" (e.g., "last
        week" or "this month").
 
-       When combined with absolute date and time, the relative date  and  time
-       specification  will  be  relative  from the specified absolute date and
+       When  combined  with absolute date and time, the relative date and time
+       specification will be relative from the  specified  absolute  date  and
        time.
 
        Examples: 5M2d, two weeks
@@ -354,6 +379,24 @@
        Some time zone codes, e.g. UTC, EET.
 

 
+
XAPIAN FIELD PROCESSORS

+
+       Certain  optional  features  of the notmuch query processor rely on the
+       presence of the Xapian field processor API. You can determine  if  your
+       notmuch  was  built  against a sufficiently recent version of Xapian by
+       running
+
+          % notmuch config get built_with.field_processor
+
+       Currently the following features require field processor support:
+
+       · non-range date queries, e.g. "date:today"
+
+       · named queries e.g. "query:my_special_query"
+
+       · regular expression searches, e.g. "subject:/^\[SPAM\]/"
+

+
 
SEE ALSO

 
        notmuch(1), notmuch-config(1), notmuch-count(1), notmuch-dump(1),  not‐
@@ -368,7 +411,7 @@
 
 
COPYRIGHT

 
-       2009-2015, Carl Worth and many others
+       2009-2017, Carl Worth and many others
 

 
-
0.21

+
0.24