X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=doc%2Fman7%2Fnotmuch-search-terms.rst;h=f8ad1edb2c7ab92122c45c59d11a2b845f1e47d2;hb=8ed6a172b35708428f84f30af44fa81c12852e43;hp=c602eadbe01b2dccfbcba02788c77b93f6135737;hpb=6499fce3911df2646db67c0f1ff65672324904f0;p=notmuch diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst index c602eadb..f8ad1edb 100644 --- a/doc/man7/notmuch-search-terms.rst +++ b/doc/man7/notmuch-search-terms.rst @@ -1,3 +1,5 @@ +.. _notmuch-search-terms(7): + ==================== notmuch-search-terms ==================== @@ -7,7 +9,7 @@ SYNOPSIS **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*> ... @@ -30,136 +32,145 @@ recipient headers. As a special case, a search string consisting of exactly a single asterisk ("\*") will match all messages. +Search prefixes +--------------- + In addition to free text, the following prefixes can be used to force terms to match against specific portions of an email, (where -indicate user-supplied values): - -- from: - -- from:// - -- to: - -- subject: - -- subject:// - -- attachment: - -- mimetype: - -- tag: (or is:) - -- id: - -- thread: - -- folder: - -- path: or path:/** - -- date:.. - -- lastmod:.. - -- query: - -- property:= - -The **from:** prefix is used to match the name or address of the sender -of an email message. - -The **to:** prefix is used to match the names or addresses of any -recipient of an email message, (whether To, Cc, or Bcc). - -Any term prefixed with **subject:** will match only text from the -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. - -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 added manually with **notmuch tag**. - -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 -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** - -The **path:** prefix searches for email messages that are in -particular directories within the mail store. The directory must be -specified relative 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 includes messages in the "new" and "cur" -subdirectories. The exact syntax 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 folders 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 is in the specific directory/folder. - -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: - -date:.. - -See **DATE AND TIME SEARCH** below for details on the range expression, -and supported syntax for and date and time expressions. - -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. +indicate user-supplied values). + +Some of the prefixes with 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: + Match terms in the body of messages. + +from: or from:// + The **from:** prefix is used to match the name or address of + the sender of an email message. + +to: + The **to:** prefix is used to match the names or addresses of any + recipient of an email message, (whether To, Cc, or Bcc). + +subject: or subject:// + Any term prefixed with **subject:** will match only text from the + subject of an email. Searching for a phrase in the subject is + supported by including quotation marks around the phrase, + immediately following **subject:**. + +attachment: + The **attachment:** prefix can be used to search for specific + filenames (or extensions) of attachments to email messages. + +mimetype: + The **mimetype:** prefix will be used to match text from the + content-types of MIME parts within email messages (as specified by + the sender). + +tag: or tag:// or is: or is:// + For **tag:** and **is:** valid tag values include **inbox** and + **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: or mid: or mid:// + For **id:** and **mid:**, message ID values are the literal + contents of the Message-ID: header of email messages, but without + the '<', '>' delimiters. + +thread: + 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 :any:`notmuch-search(1)` + +thread:{} + 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:{}** + as expanding to all of the thread IDs which match ****; + notmuch then performs a second search using the expanded query. + +path: or path:/** or path:// + The **path:** prefix searches for email messages that are in + particular directories within the mail store. The directory must + be specified relative 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. + + **path:** will find a message if *any* copy of that message is in + the specific directory. + +folder: or folder:// + The **folder:** prefix searches for email messages by maildir or + MH folder. For MH-style folders, this is equivalent to + **path:**. For maildir, this includes messages in the "new" and + "cur" subdirectories. The exact syntax 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 folders 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**. + + **folder:** will find a message if *any* copy of that message is + in the specific folder. + +date:.. or date: + The **date:** prefix can be used to restrict the results to only + messages within a particular time range (based on the Date: + header). + + See **DATE AND TIME SEARCH** below for details on the range + expression, and supported syntax for and date and + time expressions. + + The time range can also be specified using timestamps without + including the date prefix using a syntax of: + + .. + + Each timestamp is a number representing the number of seconds + since 1970-01-01 00:00:00 UTC. Specifying a time range this way + is considered legacy and predates the date prefix. + +lastmod:.. + 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 + :any:`notmuch-search(1)` to find messages that have changed since + an earlier query. + +query: + The **query:** prefix allows queries to refer to previously saved + queries added with :any:`notmuch-config(1)`. + +property:= + 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. + See :any:`notmuch-properties(7)` for more details. + +User defined prefixes are also supported, see :any:`notmuch-config(1)` for +details. Operators --------- @@ -244,7 +255,7 @@ follows. Boolean **tag:**, **id:**, **thread:**, **folder:**, **path:**, **property:** Probabilistic - **to:**, **attachment:**, **mimetype:** + **body:**, **to:**, **attachment:**, **mimetype:** Special **from:**, **query:**, **subject:** @@ -264,11 +275,13 @@ the same phrase. - 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 @@ -284,6 +297,33 @@ Both of these will match a subject "Free Delicious Pizza" while 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 ==================== @@ -308,23 +348,28 @@ 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..! +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: -Currently, we do not support spaces in range expressions. You can + date:@..@ + +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:.. 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. +Open-ended ranges are supported. I.e. it's possible to specify +date:.. or date:.. to not limit the start or +end time, respectively. + +Single expression +----------------- + +date: works as a shorthand for date:... +For example, date:monday matches from the beginning of Monday until +the end of Monday. Relative date and time ---------------------- @@ -401,36 +446,20 @@ 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-reindex(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)`