X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=doc%2Fman7%2Fnotmuch-search-terms.rst;h=dd76972ee3893fe369d508fd4f7e92ec5ad2622a;hb=aa2abd2958f941caba6ffc8052dd00550f7e7e39;hp=910390417ec7cf24ab7b089a72be266926d26ae9;hpb=682a362c85475623a208dc7c9f2fb63af4bfb793;p=notmuch diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst index 91039041..dd76972e 100644 --- a/doc/man7/notmuch-search-terms.rst +++ b/doc/man7/notmuch-search-terms.rst @@ -9,6 +9,8 @@ SYNOPSIS **notmuch** **dump** [--format=(batch-tag|sup)] [--] [--output=<*file*>] [--] [<*search-term*> ...] +**notmuch** **reindex** [option ...] <*search-term*> ... + **notmuch** **search** [option ...] <*search-term*> ... **notmuch** **show** [option ...] <*search-term*> ... @@ -34,10 +36,14 @@ indicate user-supplied values): - from: +- from:// + - to: - subject: +- subject:// + - attachment: - mimetype: @@ -54,6 +60,12 @@ indicate user-supplied values): - date:.. +- lastmod:.. + +- query: + +- property:= + The **from:** prefix is used to match the name or address of the sender of an email message. @@ -65,6 +77,15 @@ subject of an email. Searching for a phrase in the subject is supported by including quotation marks around the phrase, immediately following **subject:**. +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. @@ -124,6 +145,22 @@ The time range can also be specified using timestamps with a syntax of: 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 revision number of when messages were last modified (tags +were added/removed or filenames changed). This is usually used in +conjunction 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 notmuch is built with **Xapian Field Processors** (see +below). + +The **property:** prefix searches for messages with a particular += 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 --------- @@ -198,17 +235,18 @@ Boolean and Probabilistic Prefixes ---------------------------------- 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 notmuch are as follows. - -+------------------+-----------------------+ -|Boolean |Probabilistic | -+------------------+-----------------------+ -| **tag:** **id:** | **from:** **to:** | -|**thread:** |**subject:** | -|**folder:** |**attachment** | -|**path:** | | -| | | -+------------------+-----------------------+ +exact matches like "tag:inbox" or **probabilistic**, supporting a more +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 ----------------- @@ -270,6 +308,14 @@ In this case, is taken as the earliest time it could describe could describe (the end of yesterday). Similarly, date:january..february matches from the beginning of January to the end of February. +date:..! can be used as a shorthand for date:... 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 replace the spaces with '\_', or (in most cases) '-', or (in some cases) leave the spaces out altogether. Examples in this man page use spaces @@ -280,11 +326,6 @@ to specify date:.. or date:.. to not limit the start or end time, respectively. Pre-1.2.1 Xapian does not report an error on open ended ranges, but it does not work as expected either. -Entering date:expr without ".." (for example date:yesterday) won't work, -as it's not interpreted as a range expression at all. You can achieve -the expected result by duplicating the expr both sides of ".." (for -example date:yesterday..yesterday). - Relative date and time ---------------------- @@ -360,10 +401,28 @@ Time zones 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)**, **notmuch-hooks(5)**, **notmuch-insert(1)**, -**notmuch-new(1)**, **notmuch-reply(1)**, **notmuch-restore(1)**, -**notmuch-search(1)**, **notmuch-show(1)**, **notmuch-tag(1)** +**notmuch-new(1)**, **notmuch-reindex(1)**, **notmuch-reply(1)**, +**notmuch-restore(1)**, **notmuch-search(1)**, **notmuch-show(1)**, +**notmuch-tag(1)**