X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=doc%2Fman7%2Fnotmuch-search-terms.rst;h=2fbc16d133722bec317352278f71e068bd6a158f;hp=20bc6f1e1488da9e2843a24f0b50b47d834093aa;hb=bf719963a74df77581409439c38ad4a76d84db62;hpb=d736260385a689b5c77d8121f48e29440e3adfa4 diff --git a/doc/man7/notmuch-search-terms.rst b/doc/man7/notmuch-search-terms.rst index 20bc6f1e..2fbc16d1 100644 --- a/doc/man7/notmuch-search-terms.rst +++ b/doc/man7/notmuch-search-terms.rst @@ -40,16 +40,22 @@ indicate user-supplied values): - attachment: +- mimetype: + - tag: (or is:) - id: - thread: -- folder: +- folder: + +- path: or path:/** - date:.. +- lastmod:.. + The **from:** prefix is used to match the name or address of the sender of an email message. @@ -64,6 +70,10 @@ by including quotation marks around the phrase, immediately following 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**. @@ -77,12 +87,28 @@ 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 **folder:** prefix can be used to search for email message files -that are contained within particular directories within the mail store. -If the same email message has multiple message files associated with it, -it's sufficient for a match that at least one of the files is contained -within a matching directory. Only the directory components below the -top-level mail database path are available to be searched. +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 @@ -100,16 +126,133 @@ 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. + +Operators +--------- + In addition to individual terms, multiple terms can be combined with -Boolean operators ( **and**, **or**, **not** , etc.). Each term in the -query will be implicitly connected by a logical AND if no explicit -operator is provided, (except that terms with a common prefix will be -implicitly combined with OR until we get Xapian defect #402 fixed). +Boolean operators (**and**, **or**, **not**, and **xor**). Each term +in the query will be implicitly connected by a logical AND if no +explicit operator is provided (except that terms with a common prefix +will be implicitly combined with OR). The shorthand '-' can be +used for 'not ' but unfortunately this does not work at the +start of an expression. Parentheses can also be used to control the +combination of the Boolean operators, but will have to be protected +from interpretation by the shell, (such as by putting quotation marks +around any parenthesized expression). + +In addition to the standard boolean operators, Xapian provides several +operators specific to text searching. + +:: + + notmuch search term1 NEAR term2 + +will return results where term1 is within 10 words of term2. The +threshold can be set like this: + +:: + + notmuch search term1 NEAR/2 term2 + +The search + +:: + + notmuch search term1 ADJ term2 + +will return results where term1 is within 10 words of term2, but in the +same order as in the query. The threshold can be set the same as with +NEAR: + +:: + + notmuch search term1 ADJ/7 term2 + + +Stemming +-------- + +**Stemming** in notmuch means that these searches + +:: + + notmuch search detailed + notmuch search details + notmuch search detail -Parentheses can also be used to control the combination of the Boolean -operators, but will have to be protected from interpretation by the -shell, (such as by putting quotation marks around any parenthesized -expression). +will all return identical results, because Xapian first "reduces" the +term to the common stem (here 'detail') and then performs the search. + +There are two ways to turn this off: a search for a capitalized word +will be performed unstemmed, so that one can search for "John" and not +get results for "Johnson"; phrase searches are also unstemmed (see +below for details). Stemming is currently only supported for +English. Searches for words in other languages will be performed unstemmed. + +Wildcards +--------- + +It is possible to use a trailing '\*' as a wildcard. A search for +'wildc\*' will match 'wildcard', 'wildcat', etc. + + +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:** |**mimetype:** | +| | | ++------------------+-----------------------+ + +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 that the following are equivalant ways to write +the same phrase. + +- "a list of words" +- a-list-of-words +- a/list/of/words +- a.list.of.words + +Both parenthesised lists of terms and quoted phrases are ok with +probabilisitic prefixes such as **to:**, **from:**, and **subject:**. In particular + +:: + + subject:(pizza free) + +is equivalent to + +:: + + subject:pizza and subject:free + +Both of these will match a subject "Free Delicious Pizza" while + +:: + + subject:"pizza free" + +will not. DATE AND TIME SEARCH ==================== @@ -135,6 +278,13 @@ 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. (Note that entering date: without "..", for example +date:yesterday, won't work, as it's not interpreted as a range +expression at all. Again, 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 @@ -145,11 +295,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 ----------------------