]> git.cworth.org Git - obsolete/notmuch-wiki/blobdiff - manpages/notmuch-search-terms-7.mdwn
Update news & manpages to notmuch version 0.16
[obsolete/notmuch-wiki] / manpages / notmuch-search-terms-7.mdwn
index ff513235932d33c6105b02c09f83935516522d6e..c4fe11db2ce7020458bd7ca13940cfb0f386fccd 100644 (file)
@@ -2,7 +2,7 @@
 
 <h2>NAME</h2>
 <pre>
 
 <h2>NAME</h2>
 <pre>
-       notmuch-search-terms - Syntax for notmuch queries
+       notmuch-search-terms - syntax for notmuch queries
 </pre>
 
 <h2>SYNOPSIS</h2>
 </pre>
 
 <h2>SYNOPSIS</h2>
@@ -15,7 +15,7 @@
 
        <b>notmuch</b> <b>show</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;...
+       <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>
 
 <h2>DESCRIPTION</h2>
@@ -50,6 +50,8 @@
 
             folder:&lt;directory-path&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>from:</b> prefix is used to match the name or address of the sender of
        an email message.
 
        the  directory  components  below  the top-level mail database path are
        available to be searched.
 
        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
        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
        operators,  but  will  have  to be protected from interpretation by the
        shell, (such as by putting quotation  marks  around  any  parenthesized
        expression).
        operators,  but  will  have  to be protected from interpretation by the
        shell, (such as by putting quotation  marks  around  any  parenthesized
        expression).
+</pre>
 
 
-       Finally, results can be restricted to only messages within a particular
-       time range, (based on the Date: header) with a syntax of:
+<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.
 
 
-            &lt;initial-timestamp&gt;..&lt;final-timestamp&gt;
+           <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;yes-
+               terday&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  yester-
+               day). Similarly, date:january..february matches from the begin-
+               ning 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
 
 
-       Each timestamp is a number representing the  number  of  seconds  since
-       1970-01-01  00:00:00  UTC.  This  is  not  the most convenient means of
-       expressing date ranges, but until notmuch is fixed  to  accept  a  more
-       convenient  form, one can use the date program to construct timestamps.
-       For example, with the bash shell the following syntax would  specify  a
-       date range to return messages from 2009-10-01 until the current time:
+               (+|-)HH[MM]
 
 
-            $(date +%s -d 2009-10-01)..$(date +%s)
+               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>
 </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-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)
+       <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>
 
 </pre>
 
-<h2>Notmuch 0.13.2</h2>
+<h2>Notmuch 0.16</h2>