+.. _notmuch-search-terms(7):
+
====================
notmuch-search-terms
====================
**notmuch** **count** [option ...] <*search-term*> ...
-**notmuch** **dump** [--format=(batch-tag|sup)] [--] [--output=<*file*>] [--] [<*search-term*> ...]
+**notmuch** **dump** [--gzip] [--format=(batch-tag|sup)] [--output=<*file*>] [--] [<*search-term*> ...]
**notmuch** **reindex** [option ...] <*search-term*> ...
terms to match against specific portions of an email, (where <brackets>
indicate user-supplied values).
-If notmuch is built with **Xapian Field Processors** (see below) some
-of the prefixes with <regex> forms can be also used to restrict the
-results to those whose value matches a regular expression (see
-**regex(7)**) delimited with //, for example::
+Some of the prefixes with <regex> forms can be also used to restrict
+the results to those whose value matches a regular expression (see
+:manpage:`regex(7)`) delimited with //, for example::
notmuch search 'from:"/bob@.*[.]example[.]com/"'
+body:<word-or-quoted-phrase>
+ Match terms in the body of messages.
+
from:<name-or-address> or from:/<regex>/
The **from:** prefix is used to match the name or address of
the sender of an email message.
tag:<tag> or tag:/<regex>/ or is:<tag> or is:/<regex>/
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**.
+ **unread** by default for new messages added by
+ :any:`notmuch-new(1)` as well as any other tag values added
+ manually with :any:`notmuch-tag(1)`.
id:<message-id> or mid:<message-id> or mid:/<regex>/
For **id:** and **mid:**, message ID values are the literal
The **thread:** prefix can be used with the thread ID values that
are generated 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**
+ of output from :any:`notmuch-search(1)`
+
+thread:{<notmuch query>}
+ Threads may be searched for indirectly by providing an arbitrary
+ notmuch query in **{}**. For example, the following returns
+ threads containing a message from mallory and one (not necessarily
+ the same message) with Subject containing the word "crypto".
+
+ ::
+
+ % notmuch search 'thread:"{from:mallory}" and thread:"{subject:crypto}"'
+
+ The performance of such queries can vary wildly. To understand
+ this, the user should think of the query **thread:{<something>}**
+ as expanding to all of the thread IDs which match **<something>**;
+ notmuch then performs a second search using the expanded query.
path:<directory-path> or path:<directory-path>/** or path:/<regex>/
The **path:** prefix searches for email messages that are in
lastmod:<initial-revision>..<final-revision>
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.
+ were added/removed or filenames changed). Negative revisions are
+ interpreted relative to the most recent database revision (see
+ :option:`count --lastmod`). This is usually used in conjunction
+ with the ``--uuid`` argument to :any:`notmuch-search(1)` to find
+ messages that have changed since an earlier query.
query:<name>
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).
+ queries added with :any:`notmuch-config(1)`.
property:<key>=<value>
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.
- See **notmuch-properties(7)** for more details.
+ See :any:`notmuch-properties(7)` for more details.
+
+sexp:<subquery>
+ The **sexp:** prefix allows subqueries in the format
+ documented in :any:`notmuch-sexp-queries(7)`. Note that subqueries containing
+ spaces must be quoted, and any embedded double quotes must be escaped
+ (see :any:`quoting`).
+
+User defined prefixes are also supported, see :any:`notmuch-config(1)` for
+details.
Operators
---------
Boolean
**tag:**, **id:**, **thread:**, **folder:**, **path:**, **property:**
Probabilistic
- **to:**, **attachment:**, **mimetype:**
+ **body:**, **to:**, **attachment:**, **mimetype:**
Special
- **from:**, **query:**, **subject:**
+ **from:**, **query:**, **subject:**, **sexp:**
Terms and phrases
-----------------
- a.list.of.words
Both parenthesised lists of terms and quoted phrases are ok with
-probabilistic prefixes such as **to:**, **from:**, and **subject:**. In particular
+probabilistic prefixes such as **to:**, **from:**, and **subject:**.
+For prefixes supporting regex search, the parenthesised list should be
+quoted. In particular
::
- subject:(pizza free)
+ subject:"(pizza free)"
is equivalent to
will not.
+.. _quoting:
+
Quoting
-------
Double quotes are also used by the notmuch query parser to protect
-boolean terms or regular expressions containing spaces or other
-special characters, e.g.
+boolean terms, regular expressions, or subqueries containing spaces or
+other special characters, e.g.
::
folder:"/^.*/(Junk|Spam)$/"
+::
+
+ thread:"{from:mallory and date:2009}"
+
As with phrases, you need to protect the double quotes from the shell
e.g.
::
% notmuch search 'folder:"/^.*/(Junk|Spam)$/"'
+ % notmuch search 'thread:"{from:mallory and date:2009}" and thread:{to:mallory}'
+
+Double quotes within query strings need to be doubled to escape them.
+
+::
+
+ % notmuch search 'tag:"""quoted tag"""'
+ % notmuch search 'sexp:"(or ""wizard"" ""php"")"'
DATE AND TIME SEARCH
====================
date:@<initial-timestamp>..@<final-timestamp>
-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, spaces in range expressions are not supported. 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.
-Open-ended ranges are supported (since Xapian 1.2.1), i.e. it's possible
-to specify date:..<until> or date:<since>.. 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.
+Open-ended ranges are supported. I.e. it's possible to specify
+date:..<until> or date:<since>.. to not limit the start or
+end time, respectively.
+
+Single expression
+-----------------
+
+date:<expr> works as a shorthand for date:<expr>..<expr>.
+For example, date:monday matches from the beginning of Monday until
+the end of Monday.
Relative date and time
----------------------
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-reindex(1)**,
-**notmuch-properties(1)**,
-***notmuch-reply(1)**,
-**notmuch-restore(1)**,
-**notmuch-search(1)**,
-***notmuch-show(1)**,
-**notmuch-tag(1)**
+:any:`notmuch(1)`,
+:any:`notmuch-config(1)`,
+:any:`notmuch-count(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-insert(1)`,
+:any:`notmuch-new(1)`,
+:any:`notmuch-properties(7)`,
+:any:`notmuch-reindex(1)`,
+:any:`notmuch-reply(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-search(1)`,
+:any:`notmuch-show(1)`,
+:any:`notmuch-tag(1)`
projects / notmuch / blobdiff