mirror of
https://git.notmuchmail.org/git/notmuch
synced 2024-11-25 20:38:08 +01:00
doc: arrange search prefix documentation in a definition list
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
David Bremner
parent
f3fc97c000
commit
89f651a403
1 changed files with 96 additions and 109 deletions
|
|
@ -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.
|
||||||
|
|
||||||
The **mimetype:** prefix will be used to match text from the
|
to:<name-or-address>
|
||||||
content-types of MIME parts within email messages (as specified by the
|
The **to:** prefix is used to match the names or addresses of any
|
||||||
sender).
|
recipient of an email message, (whether To, Cc, or Bcc).
|
||||||
|
|
||||||
For **tag:** and **is:** valid tag values include **inbox** and
|
subject:<word-or-quoted-phrase> or subject:/<regex>/
|
||||||
**unread** by default for new messages added by **notmuch new** as well
|
Any term prefixed with **subject:** will match only text from the
|
||||||
as any other tag values added manually with **notmuch tag**.
|
subject of an email. Searching for a phrase in the subject is
|
||||||
|
supported by including quotation marks around the phrase,
|
||||||
|
immediately following **subject:**.
|
||||||
|
|
||||||
For **id:**, message ID values are the literal contents of the
|
attachment:<word>
|
||||||
Message-ID: header of email messages, but without the '<', '>'
|
The **attachment:** prefix can be used to search for specific
|
||||||
delimiters.
|
filenames (or extensions) of attachments to email messages.
|
||||||
|
|
||||||
The **thread:** prefix can be used with the thread ID values that are
|
mimetype:<word>
|
||||||
generated internally by notmuch (and do not appear in email messages).
|
The **mimetype:** prefix will be used to match text from the
|
||||||
These thread ID values can be seen in the first column of output from
|
content-types of MIME parts within email messages (as specified by
|
||||||
**notmuch search**
|
the sender).
|
||||||
|
|
||||||
The **path:** prefix searches for email messages that are in
|
tag:<tag> or tag:/<regex>/ or is:<tag> or is:/<regex>/
|
||||||
particular directories within the mail store. The directory must be
|
For **tag:** and **is:** valid tag values include **inbox** and
|
||||||
specified relative to the top-level maildir (and without the leading
|
**unread** by default for new messages added by **notmuch new** as
|
||||||
slash). By default, **path:** matches messages in the specified
|
well as any other tag values added manually with **notmuch tag**.
|
||||||
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
|
id:<message-id> or mid:<message-id> or mid:/<regex>/
|
||||||
folder. For MH-style folders, this is equivalent to **path:**. For
|
For **id:** and **mid:**, message ID values are the literal
|
||||||
maildir, this includes messages in the "new" and "cur"
|
contents of the Message-ID: header of email messages, but without
|
||||||
subdirectories. The exact syntax for maildir folders depends on your
|
the '<', '>' delimiters.
|
||||||
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
|
thread:<thread-id>
|
||||||
that message is in the specific directory/folder.
|
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 **date:** prefix can be used to restrict the results to only
|
path:<directory-path> or path:<directory-path>/** or path:/<regex>/
|
||||||
messages within a particular time range (based on the Date: header) with
|
The **path:** prefix searches for email messages that are in
|
||||||
a range syntax of:
|
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.
|
||||||
|
|
||||||
date:<since>..<until>
|
**path:** will find a message if *any* copy of that message is in
|
||||||
|
the specific directory.
|
||||||
|
|
||||||
See **DATE AND TIME SEARCH** below for details on the range expression,
|
folder:<maildir-folder> or folder:/<regex>/
|
||||||
and supported syntax for <since> and <until> date and time expressions.
|
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**.
|
||||||
|
|
||||||
The time range can also be specified using timestamps with a syntax of:
|
**folder:** will find a message if *any* copy of that message is
|
||||||
|
in the specific folder.
|
||||||
|
|
||||||
<initial-timestamp>..<final-timestamp>
|
date:<since>..<until> or date:<date>
|
||||||
|
The **date:** prefix can be used to restrict the results to only
|
||||||
|
messages within a particular time range (based on the Date:
|
||||||
|
header).
|
||||||
|
|
||||||
Each timestamp is a number representing the number of seconds since
|
See **DATE AND TIME SEARCH** below for details on the range
|
||||||
1970-01-01 00:00:00 UTC.
|
expression, and supported syntax for <since> and <until> date and
|
||||||
|
time expressions.
|
||||||
|
|
||||||
The **lastmod:** prefix can be used to restrict the result by the
|
The time range can also be specified using timestamps with a
|
||||||
database revision number of when messages were last modified (tags
|
syntax of:
|
||||||
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
|
<initial-timestamp>..<final-timestamp>
|
||||||
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
|
Each timestamp is a number representing the number of seconds
|
||||||
<key>=<value> property pair. Properties are used internally by notmuch
|
since 1970-01-01 00:00:00 UTC.
|
||||||
(and extensions) to add metadata to messages. A given key can be
|
|
||||||
present on a given message with several different values. See
|
lastmod:<initial-revision>..<final-revision>
|
||||||
**notmuch-properties(7)** for more details.
|
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.
|
||||||
|
|
||||||
|
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).
|
||||||
|
|
||||||
|
property:<key>=<value>
|
||||||
|
The **property:** prefix searches for messages with a particular
|
||||||
|
<key>=<value> 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 **notmuch-properties(7)** for more details.
|
||||||
|
|
||||||
Operators
|
Operators
|
||||||
---------
|
---------
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue