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

   1 <h1>NOTMUCH-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        The  <b>from:</b> prefix is used to match the name or address of the sender of
  54        an email message.
  55
  56        The <b>to:</b> prefix is used to match the names or addresses of any recipient
  57        of an email message, (whether To, Cc, or Bcc).
  58
  59        Any  term  prefixed with <b>subject:</b> will match only text from the subject
  60        of an email. Searching for a phrase in  the  subject  is  supported  by
  61        including quotation marks around the phrase, immediately following <b>sub-</b>
  62        <b>ject:</b>.
  63
  64        The <b>attachment:</b> prefix can be used to search for specific filenames (or
  65        extensions) of attachments to email messages.
  66
  67        For  <b>tag:</b>  and <b>is:</b> valid tag values include <b>inbox</b> and <b>unread</b> by default
  68        for new messages added by <b>notmuch</b> <b>new</b> as well as any other  tag  values
  69        added manually with <b>notmuch</b> <b>tag</b>.
  70
  71        For  <b>id:</b>, message ID values are the literal contents of the Message-ID:
  72        header of email messages, but without the &apos;&lt;&apos;, &apos;&gt;&apos; delimiters.
  73
  74        The <b>thread:</b> prefix can be used with the thread ID values that are  gen-
  75        erated  internally  by  notmuch  (and do not appear in email messages).
  76        These thread ID values can be seen in the first column of  output  from
  77        <b>notmuch</b> <b>search</b>
  78
  79        The  <b>folder:</b>  prefix can be used to search for email message files that
  80        are contained within particular directories within the mail store. Only
  81        the  directory  components  below  the top-level mail database path are
  82        available to be searched.
  83
  84        In addition to individual terms, multiple terms can  be  combined  with
  85        Boolean  operators  ( <b>and</b>, <b>or</b>, <b>not</b> , etc.). Each term in the query will
  86        be implicitly connected by a logical AND if  no  explicit  operator  is
  87        provided,  (except  that  terms with a common prefix will be implicitly
  88        combined with OR until we get Xapian defect #402 fixed).
  89
  90        Parentheses can also be used to control the combination of the  Boolean
  91        operators,  but  will  have  to be protected from interpretation by the
  92        shell, (such as by putting quotation  marks  around  any  parenthesized
  93        expression).
  94
  95        Finally, results can be restricted to only messages within a particular
  96        time range, (based on the Date: header) with a syntax of:
  97
  98             &lt;initial-timestamp&gt;..&lt;final-timestamp&gt;
  99
 100        Each timestamp is a number representing the  number  of  seconds  since
 101        1970-01-01  00:00:00  UTC.  This  is  not  the most convenient means of
 102        expressing date ranges, but until notmuch is fixed  to  accept  a  more
 103        convenient  form, one can use the date program to construct timestamps.
 104        For example, with the bash shell the following syntax would  specify  a
 105        date range to return messages from 2009-10-01 until the current time:
 106
 107             $(date +%s -d 2009-10-01)..$(date +%s)
 108 </pre>
 109
 110 <h2>SEE ALSO</h2>
 111 <pre>
 112        <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>
 113        <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),
 114        <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)
 115 </pre>
 116
 117 <h2>Notmuch 0.14</h2>