**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
+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::
- notmuch search 'from:/bob@.*[.]example[.]com/'
+ 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
messages). These thread ID values can be seen in the first column
of output from **notmuch search**
+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
particular directories within the mail store. The directory must
expression, and supported syntax for <since> and <until> date and
time expressions.
- The time range can also be specified using timestamps with a
- syntax of:
+ The time range can also be specified using timestamps without
+ including the date prefix using a syntax of:
<initial-timestamp>..<final-timestamp>
Each timestamp is a number representing the number of seconds
- since 1970-01-01 00:00:00 UTC.
+ since 1970-01-01 00:00:00 UTC. Specifying a time range this way
+ is considered legacy and predates the date prefix.
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
+ conjunction with the ``--uuid`` argument to **notmuch search** 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 **notmuch-config(1)**.
property:<key>=<value>
The **property:** prefix searches for messages with a particular
can be present on a given message with several different values.
See **notmuch-properties(7)** for more details.
+User defined prefixes are also supported, see **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:**
will not.
+Quoting
+-------
+
+Double quotes are also used by the notmuch query parser to protect
+boolean terms, regular expressions, or subqueries containing spaces or
+other special characters, e.g.
+
+::
+
+ tag:"a tag"
+
+::
+
+ 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}'
+
DATE AND TIME SEARCH
====================
could describe (the end of yesterday). Similarly, date:january..february
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.
-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..!
+If specifying a time range using timestamps in conjunction with the
+date prefix, each timestamp must be preceded by @ (ASCII hex 40). As
+above, each timestamp is a number representing the number of seconds
+since 1970-01-01 00:00:00 UTC. For example:
+
+ date:@<initial-timestamp>..@<final-timestamp>
-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
========
projects / notmuch / blobdiff