git.cworth.org Git - obsolete/notmuch-wiki/blob - manpages/notmuch-search-terms-7.mdwn

   1 <h1>NOTMUCH-SEARCH-TERMS(7)Miscellaneous Information ManualNOTMUCH-SEARCH-TERMS(7)</h1>
   2
   3 <h2>NAME</h2>
   4 <pre>
   5        notmuch-search-terms - syntax for notmuch queries
   6 </pre>
   7
   8 <h2>SYNOPSIS</h2>
   9 <pre>
  10        <b>notmuch</b> <b>count</b> [<u>options...</u>]  &lt;<u>search-term</u>&gt;...
  11
  12        <b>notmuch</b> <b>dump</b> [ &lt;<u>filename</u>&gt; ] [--] [ &lt;<u>search-term</u>&gt;...]
  13
  14        <b>notmuch</b> <b>search</b> [<u>options</u>...] &lt;<u>search-term</u>&gt;...
  15
  16        <b>notmuch</b> <b>show</b> [<u>options</u>...] &lt;<u>search-term</u>&gt;...
  17
  18        <b>notmuch</b> <b>tag</b> +&lt;<u>tag</u>&gt;|-&lt;<u>tag</u>&gt; [...] [--] &lt;<u>search-term</u>&gt;...
  19 </pre>
  20
  21 <h2>DESCRIPTION</h2>
  22 <pre>
  23        Several notmuch commands accept a common syntax for search terms.
  24
  25        The  search  terms  can  consist of free-form text (and quoted phrases)
  26        which  will  match  all  messages  that  contain  all  of   the   given
  27        terms/phrases in the body, the subject, or any of the sender or recipi-
  28        ent headers.
  29
  30        As a special case, a search  string  consisting  of  exactly  a  single
  31        asterisk (&quot;*&quot;) will match all messages.
  32
  33        In  addition  to free text, the following prefixes can be used to force
  34        terms to match against specific portions of an email, (where &lt;brackets&gt;
  35        indicate user-supplied values):
  36
  37             from:&lt;name-or-address&gt;
  38
  39             to:&lt;name-or-address&gt;
  40
  41             subject:&lt;word-or-quoted-phrase&gt;
  42
  43             attachment:&lt;word&gt;
  44
  45             tag:&lt;tag&gt; (or is:&lt;tag&gt;)
  46
  47             id:&lt;message-id&gt;
  48
  49             thread:&lt;thread-id&gt;
  50
  51             folder:&lt;directory-path&gt;
  52
  53             date:&lt;since&gt;..&lt;until&gt;
  54
  55        The  <b>from:</b> prefix is used to match the name or address of the sender of
  56        an email message.
  57
  58        The <b>to:</b> prefix is used to match the names or addresses of any recipient
  59        of an email message, (whether To, Cc, or Bcc).
  60
  61        Any  term  prefixed with <b>subject:</b> will match only text from the subject
  62        of an email. Searching for a phrase in  the  subject  is  supported  by
  63        including quotation marks around the phrase, immediately following <b>sub-</b>
  64        <b>ject:</b>.
  65
  66        The <b>attachment:</b> prefix can be used to search for specific filenames (or
  67        extensions) of attachments to email messages.
  68
  69        For  <b>tag:</b>  and <b>is:</b> valid tag values include <b>inbox</b> and <b>unread</b> by default
  70        for new messages added by <b>notmuch</b> <b>new</b> as well as any other  tag  values
  71        added manually with <b>notmuch</b> <b>tag</b>.
  72
  73        For  <b>id:</b>, message ID values are the literal contents of the Message-ID:
  74        header of email messages, but without the &apos;&lt;&apos;, &apos;&gt;&apos; delimiters.
  75
  76        The <b>thread:</b> prefix can be used with the thread ID values that are  gen-
  77        erated  internally  by  notmuch  (and do not appear in email messages).
  78        These thread ID values can be seen in the first column of  output  from
  79        <b>notmuch</b> <b>search</b>
  80
  81        The  <b>folder:</b>  prefix can be used to search for email message files that
  82        are contained within particular directories within the mail store. Only
  83        the  directory  components  below  the top-level mail database path are
  84        available to be searched.
  85
  86        The <b>date:</b> prefix can be used to restrict the results to  only  messages
  87        within a particular time range (based on the Date: header) with a range
  88        syntax of:
  89
  90             date:&lt;since&gt;..&lt;until&gt;
  91
  92        See <b>DATE</b> <b>AND</b> <b>TIME</b> <b>SEARCH</b> below for details on the range expression, and
  93        supported syntax for &lt;since&gt; and &lt;until&gt; date and time expressions.
  94
  95        The time range can also be specified using timestamps with a syntax of:
  96
  97             &lt;initial-timestamp&gt;..&lt;final-timestamp&gt;
  98
  99        Each  timestamp  is  a  number representing the number of seconds since
 100        1970-01-01 00:00:00 UTC.
 101
 102        In addition to individual terms, multiple terms can  be  combined  with
 103        Boolean  operators  ( <b>and</b>, <b>or</b>, <b>not</b> , etc.). Each term in the query will
 104        be implicitly connected by a logical AND if  no  explicit  operator  is
 105        provided,  (except  that  terms with a common prefix will be implicitly
 106        combined with OR until we get Xapian defect #402 fixed).
 107
 108        Parentheses can also be used to control the combination of the  Boolean
 109        operators,  but  will  have  to be protected from interpretation by the
 110        shell, (such as by putting quotation  marks  around  any  parenthesized
 111        expression).
 112 </pre>
 113
 114 <h2>DATE AND TIME SEARCH</h2>
 115 <pre>
 116        notmuch  understands a variety of standard and natural ways of express-
 117        ing dates and times, both in absolute terms (&quot;2012-10-24&quot;) and in rela-
 118        tive  terms (&quot;yesterday&quot;). Any number of relative terms can be combined
 119        (&quot;1 hour 25 minutes&quot;) and an absolute date/time can  be  combined  with
 120        relative  terms  to  further adjust it. A non-exhaustive description of
 121        the syntax supported for absolute and relative terms is given below.
 122
 123            <b>The</b> <b>range</b> <b>expression</b>
 124
 125                date:&lt;since&gt;..&lt;until&gt;
 126
 127                The above expression restricts the  results  to  only  messages
 128                from &lt;since&gt; to &lt;until&gt;, based on the Date: header.
 129
 130                &lt;since&gt; and &lt;until&gt; can describe imprecise times, such as &quot;yes-
 131                terday&quot;.  In this case, &lt;since&gt; is taken as the  earliest  time
 132                it  could  describe (the beginning of yesterday) and &lt;until&gt; is
 133                taken as the latest time it could describe (the end of  yester-
 134                day). Similarly, date:january..february matches from the begin-
 135                ning of January to the end of February.
 136
 137                Currently, we do not support spaces in range  expressions.  You
 138                can replace the spaces with &apos;_&apos;, or (in most cases) &apos;-&apos;, or (in
 139                some cases) leave the spaces out altogether. Examples  in  this
 140                man page use spaces for clarity.
 141
 142                Open-ended ranges are supported (since Xapian 1.2.1), i.e. it&apos;s
 143                possible to specify date:..&lt;until&gt;  or  date:&lt;since&gt;..  to  not
 144                limit  the  start  or  end time, respectively. Pre-1.2.1 Xapian
 145                does not report an error on open ended ranges, but it does  not
 146                work as expected either.
 147
 148                Entering  date:expr  without  &quot;..&quot; (for example date:yesterday)
 149                won&apos;t work, as it&apos;s not interpreted as a  range  expression  at
 150                all.  You  can  achieve  the expected result by duplicating the
 151                expr both sides of &quot;..&quot;  (for  example  date:yesterday..yester-
 152                day).
 153
 154            <b>Relative</b> <b>date</b> <b>and</b> <b>time</b>
 155                [N|number] (years|months|weeks|days|hours|hrs|minutes|mins|sec-
 156                onds|secs) [...]
 157
 158                All refer to past, can be repeated and will be accumulated.
 159
 160                Units can be abbreviated to  any  length,  with  the  otherwise
 161                ambiguous single m being m for minutes and M for months.
 162
 163                Number  can also be written out one, two, ..., ten, dozen, hun-
 164                dred. Additionally, the unit  may  be  preceded  by  &quot;last&quot;  or
 165                &quot;this&quot; (e.g., &quot;last week&quot; or &quot;this month&quot;).
 166
 167                When  combined  with  absolute date and time, the relative date
 168                and time specification will  be  relative  from  the  specified
 169                absolute date and time.
 170
 171                Examples: 5M2d, two weeks
 172
 173            <b>Supported</b> <b>absolute</b> <b>time</b> <b>formats</b>
 174                H[H]:MM[:SS] [(am|a.m.|pm|p.m.)]
 175
 176                H[H] (am|a.m.|pm|p.m.)
 177
 178                HHMMSS
 179
 180                now
 181
 182                noon
 183
 184                midnight
 185
 186                Examples: 17:05, 5pm
 187
 188            <b>Supported</b> <b>absolute</b> <b>date</b> <b>formats</b>
 189                YYYY-MM[-DD]
 190
 191                DD-MM[-[YY]YY]
 192
 193                MM-YYYY
 194
 195                M[M]/D[D][/[YY]YY]
 196
 197                M[M]/YYYY
 198
 199                D[D].M[M][.[YY]YY]
 200
 201                D[D][(st|nd|rd|th)] Mon[thname] [YYYY]
 202
 203                Mon[thname] D[D][(st|nd|rd|th)] [YYYY]
 204
 205                Wee[kday]
 206
 207                Month names can be abbreviated at three or more characters.
 208
 209                Weekday names can be abbreviated at three or more characters.
 210
 211                Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3
 212
 213            <b>Time</b> <b>zones</b>
 214                (+|-)HH:MM
 215
 216                (+|-)HH[MM]
 217
 218                Some time zone codes, e.g. UTC, EET.
 219 </pre>
 220
 221 <h2>SEE ALSO</h2>
 222 <pre>
 223        <a href='../notmuch-1/'>notmuch</a>(1),  <a href='../notmuch-config-1/'>notmuch-config</a>(1), <a href='../notmuch-count-1/'>notmuch-count</a>(1), <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>not-</a>
 224        <a href='../notmuch-hooks-5/'>much-hooks</a>(5),  <a href='../notmuch-new-1/'>notmuch-new</a>(1),  <a href='../notmuch-reply-1/'>notmuch-reply</a>(1),  <a href='../notmuch-restore-1/'>notmuch-restore</a>(1),
 225        <a href='../notmuch-search-1/'>notmuch-search</a>(1), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
 226 </pre>
 227
 228 <h2>Notmuch 0.15.2</h2>