debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-11-22 02:48:08 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: arrange search prefix documentation in a definition list

Browse source 
Having first a list of prefixes followed by detailed descriptions was
viable when we didn't have all that many prefixes. Now, arranging the
prefix descriptions in a definition list makes more sense.

While at it, include all the supported prefix forms, especially some
missing regex ones.
This commit is contained in:
Jani Nikula 2017-11-02 22:01:17 +02:00 committed by David Bremner
parent f3fc97c000
commit 89f651a403
1 changed files with 96 additions and 109 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

185
doc/man7/notmuch-search-terms.rst
View file

@ -30,137 +30,124 @@ recipient headers.
As a special case, a search string consisting of exactly a single As a special case, a search string consisting of exactly a single
asterisk ("\*") will match all messages. asterisk ("\*") will match all messages.
Search prefixes
---------------
In addition to free text, the following prefixes can be used to force In addition to free text, the following prefixes can be used to force
terms to match against specific portions of an email, (where <brackets> terms to match against specific portions of an email, (where <brackets>
indicate user-supplied values): indicate user-supplied values).
- from:<name-or-address> If notmuch is built with **Xapian Field Processors** (see below) some
of the prefixes with <regex> forms can be also used to restrict the
- from:/<regex>/ results to those whose value matches a regular expression (see
**regex(7)**) delimited with //, for example::
- to:<name-or-address>
- subject:<word-or-quoted-phrase>
- subject:/<regex>/
- attachment:<word>
- mimetype:<word>
- tag:<tag> (or is:<tag>)
- id:<message-id>
- thread:<thread-id>
- folder:<maildir-folder>
- path:<directory-path> or path:<directory-path>/**
- date:<since>..<until>
- lastmod:<initial-revision>..<final-revision>
- query:<name>
- property:<key>=<value>
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/' notmuch search 'from:/bob@.*[.]example[.]com/'
The **attachment:** prefix can be used to search for specific filenames from:<name-or-address> or from:/<regex>/
(or extensions) of attachments to email messages. The **from:** prefix is used to match the name or address of
the sender of an email message.
to:<name-or-address>
The **to:** prefix is used to match the names or addresses of any
recipient of an email message, (whether To, Cc, or Bcc).
subject:<word-or-quoted-phrase> or subject:/<regex>/
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:<word>
The **attachment:** prefix can be used to search for specific
filenames (or extensions) of attachments to email messages.
mimetype:<word>
The **mimetype:** prefix will be used to match text from the The **mimetype:** prefix will be used to match text from the
content-types of MIME parts within email messages (as specified by the content-types of MIME parts within email messages (as specified by
sender). the sender).
tag:<tag> or tag:/<regex>/ or is:<tag> or is:/<regex>/
For **tag:** and **is:** valid tag values include **inbox** and For **tag:** and **is:** valid tag values include **inbox** and
**unread** by default for new messages added by **notmuch new** as well **unread** by default for new messages added by **notmuch new** as
as any other tag values added manually with **notmuch tag**. well as any other tag values added manually with **notmuch tag**.
For **id:**, message ID values are the literal contents of the id:<message-id> or mid:<message-id> or mid:/<regex>/
Message-ID: header of email messages, but without the '<', '>' For **id:** and **mid:**, message ID values are the literal
delimiters. 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 thread:<thread-id>
generated internally by notmuch (and do not appear in email messages). The **thread:** prefix can be used with the thread ID values that
These thread ID values can be seen in the first column of output from are generated internally by notmuch (and do not appear in email
**notmuch search** messages). These thread ID values can be seen in the first column
of output from **notmuch search**
path:<directory-path> or path:<directory-path>/** or path:/<regex>/
The **path:** prefix searches for email messages that are in The **path:** prefix searches for email messages that are in
particular directories within the mail store. The directory must be particular directories within the mail store. The directory must
specified relative to the top-level maildir (and without the leading be specified relative to the top-level maildir (and without the
slash). By default, **path:** matches messages in the specified leading slash). By default, **path:** matches messages in the
directory only. The "/\*\*" suffix can be used to match messages in specified directory only. The "/\*\*" suffix can be used to match
the specified directory and all its subdirectories recursively. messages in the specified directory and all its subdirectories
**path:""** matches messages in the root of the mail store and, recursively. **path:""** matches messages in the root of the mail
likewise, **path:\*\*** matches all messages. store and, likewise, **path:\*\*** matches all messages.
The **folder:** prefix searches for email messages by maildir or MH **path:** will find a message if *any* copy of that message is in
folder. For MH-style folders, this is equivalent to **path:**. For the specific directory.
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 folder:<maildir-folder> or folder:/<regex>/
that message is in the specific directory/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:<since>..<until> or date:<date>
The **date:** prefix can be used to restrict the results to only The **date:** prefix can be used to restrict the results to only
messages within a particular time range (based on the Date: header) with messages within a particular time range (based on the Date:
a range syntax of: header).
date:<since>..<until> See **DATE AND TIME SEARCH** below for details on the range
expression, and supported syntax for <since> and <until> date and
time expressions.
See **DATE AND TIME SEARCH** below for details on the range expression, The time range can also be specified using timestamps with a
and supported syntax for <since> and <until> date and time expressions. syntax of:
The time range can also be specified using timestamps with a syntax of:
<initial-timestamp>..<final-timestamp> <initial-timestamp>..<final-timestamp>
Each timestamp is a number representing the number of seconds since Each timestamp is a number representing the number of seconds
1970-01-01 00:00:00 UTC. since 1970-01-01 00:00:00 UTC.
lastmod:<initial-revision>..<final-revision>
The **lastmod:** prefix can be used to restrict the result by the The **lastmod:** prefix can be used to restrict the result by the
database revision number of when messages were last modified (tags database revision number of when messages were last modified (tags
were added/removed or filenames changed). This is usually used in were added/removed or filenames changed). This is usually used in
conjunction with the **--uuid** argument to **notmuch search** conjunction with the **--uuid** argument to **notmuch search** to
to find messages that have changed since an earlier query. find messages that have changed since an earlier query.
query:<name>
The **query:** prefix allows queries to refer to previously saved The **query:** prefix allows queries to refer to previously saved
queries added with **notmuch-config(1)**. Named queries are only queries added with **notmuch-config(1)**. Named queries are only
available if notmuch is built with **Xapian Field Processors** (see available if notmuch is built with **Xapian Field Processors**
below). (see below).
property:<key>=<value>
The **property:** prefix searches for messages with a particular The **property:** prefix searches for messages with a particular
<key>=<value> property pair. Properties are used internally by notmuch <key>=<value> property pair. Properties are used internally by
(and extensions) to add metadata to messages. A given key can be notmuch (and extensions) to add metadata to messages. A given key
present on a given message with several different values. See can be present on a given message with several different values.
**notmuch-properties(7)** for more details. See **notmuch-properties(7)** for more details.
Operators Operators
--------- ---------