git.notmuchmail.org Git - notmuch/blob - 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)