initial splitting of notmuch.1
[notmuch] / man / man7 / notmuch-search-terms.7
1 .TH NOTMUCH-SEARCH-TERMS 7 2011-12-04 "Notmuch 0.10.2"
2
3 .SH NAME
4 notmuch-search-terms \- Syntax for notmuch queries
5
6 .SH SYNOPSIS
7
8 .B notmuch count
9 .RI  [ options... ]
10 .RI  < search-term ">..."
11
12 .B "notmuch dump"
13 .RI "[ <" filename "> ] [--]"
14 .RI "[ <" search-term ">...]"
15
16 .B notmuch part
17 .BI "\-\-part=" "<part-number>"
18 .RI < search-term ">..."
19
20 .B notmuch search
21 .RI  [  options "...] <" search-term ">..."
22
23 .B notmuch show
24 .RI "[" options "...] <" search-term ">..."
25
26 .B notmuch tag
27 .RI  "+<" tag> "|\-<" tag "> [...] [\-\-] <" search-term ">..."
28
29
30 .SH DESCRIPTION
31 Several notmuch commands accept a common syntax for search terms.
32
33 The search terms can consist of free-form text (and quoted phrases)
34 which will match all messages that contain all of the given
35 terms/phrases in the body, the subject, or any of the sender or
36 recipient headers.
37
38 As a special case, a search string consisting of exactly a single
39 asterisk ("*") will match all messages.
40
41 In addition to free text, the following prefixes can be used to force
42 terms to match against specific portions of an email, (where
43 <brackets> indicate user-supplied values):
44
45         from:<name-or-address>
46
47         to:<name-or-address>
48
49         subject:<word-or-quoted-phrase>
50
51         attachment:<word>
52
53         tag:<tag> (or is:<tag>)
54
55         id:<message-id>
56
57         thread:<thread-id>
58
59         folder:<directory-path>
60
61 The
62 .B from:
63 prefix is used to match the name or address of the sender of an email
64 message.
65
66 The
67 .B to:
68 prefix is used to match the names or addresses of any recipient of an
69 email message, (whether To, Cc, or Bcc).
70
71 Any term prefixed with
72 .B subject:
73 will match only text from the subject of an email. Searching for a
74 phrase in the subject is supported by including quotation marks around
75 the phrase, immediately following
76 .BR subject: .
77
78 The
79 .B attachment:
80 prefix can be used to search for specific filenames (or extensions) of
81 attachments to email messages.
82
83 For
84 .BR tag: " and " is:
85 valid tag values include
86 .BR inbox " and " unread
87 by default for new messages added by
88 .B notmuch new
89 as well as any other tag values added manually with
90 .BR "notmuch tag" .
91
92 For
93 .BR id: ,
94 message ID values are the literal contents of the Message\-ID: header
95 of email messages, but without the '<', '>' delimiters.
96
97 The
98 .B thread:
99 prefix can be used with the thread ID values that are generated
100 internally by notmuch (and do not appear in email messages). These
101 thread ID values can be seen in the first column of output from
102 .B "notmuch search"
103
104 The
105 .B folder:
106 prefix can be used to search for email message files that are
107 contained within particular directories within the mail store. Only
108 the directory components below the top-level mail database path are
109 available to be searched.
110
111 In addition to individual terms, multiple terms can be
112 combined with Boolean operators (
113 .BR and ", " or ", " not
114 , etc.). Each term in the query will be implicitly connected by a
115 logical AND if no explicit operator is provided, (except that terms
116 with a common prefix will be implicitly combined with OR until we get
117 Xapian defect #402 fixed).
118
119 Parentheses can also be used to control the combination of the Boolean
120 operators, but will have to be protected from interpretation by the
121 shell, (such as by putting quotation marks around any parenthesized
122 expression).
123
124 Finally, results can be restricted to only messages within a
125 particular time range, (based on the Date: header) with a syntax of:
126
127         <initial-timestamp>..<final-timestamp>
128
129 Each timestamp is a number representing the number of seconds since
130 1970\-01\-01 00:00:00 UTC. This is not the most convenient means of
131 expressing date ranges, but until notmuch is fixed to accept a more
132 convenient form, one can use the date program to construct
133 timestamps. For example, with the bash shell the following syntax would
134 specify a date range to return messages from 2009\-10\-01 until the
135 current time:
136
137         $(date +%s \-d 2009\-10\-01)..$(date +%s)