updated manpages using fingerterm on N9

[notmuch-wiki] / manpages / notmuch-search-terms-7.mdwn

<h1>NOTMUCH-SEARCH-TERMS(7)</h1>

<h2>NAME</h2>
<pre>
       notmuch-search-terms - syntax for notmuch queries
</pre>

<h2>SYNOPSIS</h2>
<pre>
       <b>notmuch</b> <b>count</b> [<u>options...</u>]  &lt;<u>search-term</u>&gt;...

       <b>notmuch</b> <b>dump</b> [ &lt;<u>filename</u>&gt; ] [--] [ &lt;<u>search-term</u>&gt;...]

       <b>notmuch</b> <b>search</b> [<u>options</u>...] &lt;<u>search-term</u>&gt;...

       <b>notmuch</b> <b>show</b> [<u>options</u>...] &lt;<u>search-term</u>&gt;...

       <b>notmuch</b> <b>tag</b> +&lt;<u>tag</u>&gt;|-&lt;<u>tag</u>&gt; [...] [--] &lt;<u>search-term</u>&gt;...
</pre>

<h2>DESCRIPTION</h2>
<pre>
       Several notmuch commands accept a common syntax for search terms.

       The  search  terms  can  consist of free-form text (and quoted phrases)
       which  will  match  all  messages  that  contain  all  of   the   given
       terms/phrases in the body, the subject, or any of the sender or recipi-
       ent headers.

       As a special case, a search  string  consisting  of  exactly  a  single
       asterisk (&quot;*&quot;) will match all messages.

       In  addition  to free text, the following prefixes can be used to force
       terms to match against specific portions of an email, (where &lt;brackets&gt;
       indicate user-supplied values):

            from:&lt;name-or-address&gt;

            to:&lt;name-or-address&gt;

            subject:&lt;word-or-quoted-phrase&gt;

            attachment:&lt;word&gt;

            tag:&lt;tag&gt; (or is:&lt;tag&gt;)

            id:&lt;message-id&gt;

            thread:&lt;thread-id&gt;

            folder:&lt;directory-path&gt;

            date:&lt;since&gt;..&lt;until&gt;

       The  <b>from:</b> prefix is used to match the name or address of the sender of
       an email message.

       The <b>to:</b> 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 <b>subject:</b> 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 <b>sub-</b>
       <b>ject:</b>.

       The <b>attachment:</b> prefix can be used to search for specific filenames (or
       extensions) of attachments to email messages.

       For  <b>tag:</b>  and <b>is:</b> valid tag values include <b>inbox</b> and <b>unread</b> by default
       for new messages added by <b>notmuch</b> <b>new</b> as well as any other  tag  values
       added manually with <b>notmuch</b> <b>tag</b>.

       For  <b>id:</b>, message ID values are the literal contents of the Message-ID:
       header of email messages, but without the &apos;&lt;&apos;, &apos;&gt;&apos; delimiters.

       The <b>thread:</b> prefix can be used with the thread ID values that are  gen-
       erated  internally  by  notmuch  (and do not appear in email messages).
       These thread ID values can be seen in the first column of  output  from
       <b>notmuch</b> <b>search</b>

       The  <b>folder:</b>  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&apos;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 <b>date:</b> prefix can be used to restrict the results to  only  messages
       within a particular time range (based on the Date: header) with a range
       syntax of:

            date:&lt;since&gt;..&lt;until&gt;

       See <b>DATE</b> <b>AND</b> <b>TIME</b> <b>SEARCH</b> below for details on the range expression, and
       supported syntax for &lt;since&gt; and &lt;until&gt; date and time expressions.

       The time range can also be specified using timestamps with a syntax of:

            &lt;initial-timestamp&gt;..&lt;final-timestamp&gt;

       Each timestamp is a number representing the  number  of  seconds  since
       1970-01-01 00:00:00 UTC.

       In  addition  to  individual terms, multiple terms can be combined with
       Boolean operators ( <b>and</b>, <b>or</b>, <b>not</b> , etc.). Each term in the  query  will
       be  implicitly  connected  by  a logical AND if no explicit operator is
       provided, (except that terms with a common prefix  will  be  implicitly
       combined with OR until we get Xapian defect #402 fixed).

       Parentheses  can also be used to control the combination of the Boolean
       operators, but will have to be protected  from  interpretation  by  the
       shell,  (such  as  by  putting quotation marks around any parenthesized
       expression).
</pre>

<h2>DATE AND TIME SEARCH</h2>
<pre>
       notmuch understands a variety of standard and natural ways of  express-
       ing dates and times, both in absolute terms (&quot;2012-10-24&quot;) and in rela-
       tive terms (&quot;yesterday&quot;). Any number of relative terms can be  combined
       (&quot;1  hour  25  minutes&quot;) and an absolute date/time can be combined with
       relative terms to further adjust it. A  non-exhaustive  description  of
       the syntax supported for absolute and relative terms is given below.

           <b>The</b> <b>range</b> <b>expression</b>

               date:&lt;since&gt;..&lt;until&gt;

               The  above  expression  restricts  the results to only messages
               from &lt;since&gt; to &lt;until&gt;, based on the Date: header.

               &lt;since&gt; and &lt;until&gt;  can  describe  imprecise  times,  such  as
               &quot;yesterday&quot;.   In  this  case, &lt;since&gt; is taken as the earliest
               time it could describe (the beginning of yesterday) and &lt;until&gt;
               is  taken as the latest time it could describe (the end of yes-
               terday). Similarly,  date:january..february  matches  from  the
               beginning of January to the end of February.

               Currently,  we  do not support spaces in range expressions. You
               can replace the spaces with &apos;_&apos;, or (in most cases) &apos;-&apos;, or (in
               some  cases)  leave the spaces out altogether. Examples in this
               man page use spaces for clarity.

               Open-ended ranges are supported (since Xapian 1.2.1), i.e. it&apos;s
               possible  to  specify  date:..&lt;until&gt;  or date:&lt;since&gt;.. to not
               limit the start or end  time,  respectively.  Pre-1.2.1  Xapian
               does  not report an error on open ended ranges, but it does not
               work as expected either.

               Entering date:expr without &quot;..&quot;  (for  example  date:yesterday)
               won&apos;t  work,  as  it&apos;s not interpreted as a range expression at
               all. You can achieve the expected  result  by  duplicating  the
               expr  both  sides of &quot;..&quot;  (for example date:yesterday..yester-
               day).

           <b>Relative</b> <b>date</b> <b>and</b> <b>time</b>
               [N|number] (years|months|weeks|days|hours|hrs|minutes|mins|sec-
               onds|secs) [...]

               All refer to past, can be repeated and will be accumulated.

               Units  can  be  abbreviated  to  any length, with the otherwise
               ambiguous single m being m for minutes and M for months.

               Number can also be written out one, two, ..., ten, dozen,  hun-
               dred.  Additionally,  the  unit  may  be  preceded by &quot;last&quot; or
               &quot;this&quot; (e.g., &quot;last week&quot; or &quot;this month&quot;).

               When combined with absolute date and time,  the  relative  date
               and  time  specification  will  be  relative from the specified
               absolute date and time.

               Examples: 5M2d, two weeks

           <b>Supported</b> <b>absolute</b> <b>time</b> <b>formats</b>
               H[H]:MM[:SS] [(am|a.m.|pm|p.m.)]

               H[H] (am|a.m.|pm|p.m.)

               HHMMSS

               now

               noon

               midnight

               Examples: 17:05, 5pm

           <b>Supported</b> <b>absolute</b> <b>date</b> <b>formats</b>
               YYYY-MM[-DD]

               DD-MM[-[YY]YY]

               MM-YYYY

               M[M]/D[D][/[YY]YY]

               M[M]/YYYY

               D[D].M[M][.[YY]YY]

               D[D][(st|nd|rd|th)] Mon[thname] [YYYY]

               Mon[thname] D[D][(st|nd|rd|th)] [YYYY]

               Wee[kday]

               Month names can be abbreviated at three or more characters.

               Weekday names can be abbreviated at three or more characters.

               Examples: 2012-07-31, 31-07-2012, 7/31/2012, August 3

           <b>Time</b> <b>zones</b>
               (+|-)HH:MM

               (+|-)HH[MM]

               Some time zone codes, e.g. UTC, EET.
</pre>

<h2>SEE ALSO</h2>
<pre>
       <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>
       <a href='../notmuch-hooks-5/'>much-hooks</a>(5),   <a href='../notmuch-insert-1/'>notmuch-insert</a>(1),  <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), <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)
</pre>

<h2>Notmuch 0.17</h2>