- attachment:<word>
+- mimetype:<word>
+
- tag:<tag> (or is:<tag>)
- id:<message-id>
- thread:<thread-id>
-- folder:<directory-path>
+- folder:<maildir-folder>
+
+- path:<directory-path> or path:<directory-path>/**
- date:<since>..<until>
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**.
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
shell, (such as by putting quotation marks around any parenthesized
expression).
+Stemming
+--------
+
+**Stemming** in notmuch means that these searches
+
+::
+
+ notmuch search detailed
+ notmuch search details
+ notmuch search detail
+
+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 most flexible **term** based searching. The prefixes currently supported by notmuch are as follows.
+
++------------------+-----------------------+
+|Boolean |Probabilistic |
++------------------+-----------------------+
+| **tag:** **id:** | **from:** **to:** |
+|**thread:** |**subject:** |
+|**folder:** |**attachment** |
+|**path:** | |
+| | |
++------------------+-----------------------+
+
+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
====================
projects / notmuch / blobdiff