X-Git-Url: https://git.notmuchmail.org/git?a=blobdiff_plain;f=manpages%2Fnotmuch-search-terms-7.mdwn;h=e46c6b5e9d024f942e882bb74d8b954da719a911;hb=fc555c57dce98da6ab3bc92a4831a14c91807b6e;hp=f92b7c4e791b7d3b24bdcac5f7f2bbdd2d8006a4;hpb=46b88668029f0f014c4ecf7a220b7a99a13776f3;p=notmuch-wiki diff --git a/manpages/notmuch-search-terms-7.mdwn b/manpages/notmuch-search-terms-7.mdwn index f92b7c4..e46c6b5 100644 --- a/manpages/notmuch-search-terms-7.mdwn +++ b/manpages/notmuch-search-terms-7.mdwn @@ -9,9 +9,11 @@ 
        notmuch count [option ...] <search-term> ...
 
-       notmuch  dump  [--format=(batch-tag|sup)]  [--]  [--output=<file>] [--]
+       notmuch dump [--gzip] [--format=(batch-tag|sup)] [--output=<file>] [--]
        [<search-term> ...]
 
+       notmuch reindex [option ...] <search-term> ...
+
        notmuch search [option ...] <search-term> ...
 
        notmuch show [option ...] <search-term> ...
@@ -30,130 +32,145 @@
 
        As  a  special  case,  a  search  string consisting of exactly a single
        asterisk ("*") will match all messages.
+
+

  Search prefixes

+
        In addition to free text, the following prefixes can be used  to  force
        terms to match against specific portions of an email, (where <brackets>
-       indicate user-supplied values):
-
-       · from:<name-or-address>
-
-       · from:/<regex>/
-
-       · to:<name-or-address>
-
-       · subject:<word-or-quoted-phrase>
-
-       · subject:/<regex>/
-
-       · attachment:<word>
-
-       · mimetype:<word>
-
-       · tag:<tag> (or is:<tag>)
-
-       · id:<message-id>
-
-       · thread:<thread-id>
-
-       · folder:<maildir-folder>
-
-       · path:<directory-path> or path:<directory-path>/**
-
-       · date:<since>..<until>
-
-       · lastmod:<initial-revision>..<final-revision>
-
-       · query:<name>
-
-       · property:<key>=<value>
-
-       The from: prefix is used to match the name or address of the sender  of
-       an email message.
-
-       The to: 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 subject: 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 sub-
-       ject:.
-
-       If  notmuch is built with Xapian Field Processors (see below) the from:
-       and subject prefix can be also used to restrict the  results  to  those
-       whose  from/subject  value  matches a regular expression (see regex(7))
-       delimited with //.
-
-          notmuch search 'from:/bob@.*[.]example[.]com/'
-
-       The attachment: prefix can be used to search for specific filenames (or
-       extensions) of attachments to email messages.
-
-       The  mimetype: prefix will be used to match text from the content-types
-       of MIME parts within email messages (as specified by the sender).
-
-       For tag: and is: valid tag values include inbox and unread  by  default
-       for  new  messages added by notmuch new as well as any other tag values
-       added manually with notmuch tag.
-
-       For id:, message ID values are the literal contents of the  Message-ID:
-       header of email messages, but without the '<', '>' delimiters.
-
-       The  thread: 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
-       notmuch search
-
-       The path: prefix searches for email messages  that  are  in  particular
-       directories within the mail store. The directory must be specified rel‐
-       ative to the top-level maildir (and  without  the  leading  slash).  By
-       default,  path:  matches  messages in the specified directory only. The
-       "/**" suffix can be used to match messages in the  specified  directory
-       and  all  its  subdirectories recursively.  path:"" matches messages in
-       the root of the mail store and, likewise, path:** matches all messages.
-
-       The folder: prefix searches for email messages by maildir or MH folder.
-       For  MH-style  folders,  this is equivalent to path:. For maildir, this
-       includes messages in the "new" and "cur" subdirectories. The exact syn‐
-       tax  for  maildir  folders  depends  on  your  mail  configuration. For
-       maildir++, folder:"" matches the inbox folder (which  is  the  root  in
-       maildir++),  other folder names always start with ".", and nested fold‐
-       ers are separated by "."s, such as folder:.classes.topology. For  "file
-       system" maildir, the inbox is typically folder:INBOX and nested folders
-       are separated by slashes, such as folder:classes/topology.
-
-       Both path: and folder: will find a message if any copy of that  message
-       is in the specific directory/folder.
-
-       The  date:  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:<since>..<until>
-
-       See DATE AND TIME SEARCH below for details on the range expression, and
-       supported syntax for <since> and <until> date and time expressions.
-
-       The time range can also be specified using timestamps with a syntax of:
-
-       <initial-timestamp>..<final-timestamp>
-
-       Each timestamp is a number representing the  number  of  seconds  since
-       1970-01-01 00:00:00 UTC.
-
-       The  lastmod: prefix can be used to restrict the result by the database
-       revision  number  of  when  messages  were  last  modified  (tags  were
-       added/removed  or filenames changed).  This is usually used in conjunc‐
-       tion with the --uuid argument to notmuch search to find  messages  that
-       have changed since an earlier query.
-
-       The  query:  prefix allows queries to refer to previously saved queries
-       added with notmuch-config(1). Named queries are only available if  not‐
-       much is built with Xapian Field Processors (see below).
-
-       The   property:   prefix   searches  for  messages  with  a  particular
-       <key>=<value> property pair. Properties are used internally by  notmuch
-       (and  extensions)  to  add  metadata  to  messages.  A given key can be
-       present on a given message with several different values.
+       indicate user-supplied values).
+
+       If notmuch is built with Xapian Field Processors (see  below)  some  of
+       the  prefixes  with  <regex>  forms  can  be  also used to restrict the
+       results  to  those  whose  value  matches  a  regular  expression  (see
+       regex(7)) delimited with //, for example:
+
+          notmuch search 'from:"/bob@.*[.]example[.]com/"'
+
+       body:<word-or-quoted-phrase>
+              Match terms in the body of messages.
+
+       from:<name-or-address> or from:/<regex>/
+              The  from:  prefix  is  used to match the name or address of the
+              sender of an email message.
+
+       to:<name-or-address>
+              The to: prefix is used to match the names or  addresses  of  any
+              recipient of an email message, (whether To, Cc, or Bcc).
+
+       subject:<word-or-quoted-phrase> or subject:/<regex>/
+              Any  term  prefixed  with subject: 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, imme‐
+              diately following subject:.
+
+       attachment:<word>
+              The attachment: prefix can be used to search for specific  file‐
+              names (or extensions) of attachments to email messages.
+
+       mimetype:<word>
+              The  mimetype:  prefix  will be used to match text from the con‐
+              tent-types of MIME parts within email messages (as specified  by
+              the sender).
+
+       tag:<tag> or tag:/<regex>/ or is:<tag> or is:/<regex>/
+              For  tag:  and  is: valid tag values include inbox and unread by
+              default for new messages added by notmuch new  as  well  as  any
+              other tag values added manually with notmuch tag.
+
+       id:<message-id> or mid:<message-id> or mid:/<regex>/
+              For  id: and mid:, message ID values are the literal contents of
+              the Message-ID: header of email messages, but without  the  '<',
+              '>' delimiters.
+
+       thread:<thread-id>
+              The  thread:  prefix  can be used with the thread ID values that
+              are generated internally by notmuch (and do not appear in  email
+              messages).  These thread ID values can be seen in the first col‐
+              umn of output from notmuch search
+
+       thread:{<notmuch query>}
+              If notmuch is built with Xapian Field  Processors  (see  below),
+              threads may be searched for indirectly by providing an arbitrary
+              notmuch query in {}. For example, the following returns  threads
+              containing  a  message from mallory and one (not necessarily the
+              same message) with Subject containing the word "crypto".
+
+                 % notmuch search 'thread:"{from:mallory}" and thread:"{subject:crypto}"'
+
+              The performance of such queries can vary wildly.  To  understand
+              this, the user should think of the query thread:{<something>} as
+              expanding to all of the thread IDs which match <something>; not‐
+              much then performs a second search using the expanded query.
+
+       path:<directory-path> or path:<directory-path>/** or path:/<regex>/
+              The path: prefix searches for email messages that are in partic‐
+              ular directories within the mail store. The  directory  must  be
+              specified  relative  to  the  top-level maildir (and without the
+              leading slash). By default, path: matches messages in the speci‐
+              fied  directory only. The "/**" suffix can be used to match mes‐
+              sages in the specified  directory  and  all  its  subdirectories
+              recursively.  path:""  matches  messages in the root of the mail
+              store and, likewise, path:** matches all messages.
+
+              path: will find a message if any copy of that message is in  the
+              specific directory.
+
+       folder:<maildir-folder> or folder:/<regex>/
+              The  folder: prefix searches for email messages by maildir or MH
+              folder. For MH-style folders, this is equivalent to  path:.  For
+              maildir, this includes messages in the "new" and "cur" subdirec‐
+              tories. The exact syntax for maildir  folders  depends  on  your
+              mail  configuration.  For maildir++, folder:"" matches the inbox
+              folder (which is the root  in  maildir++),  other  folder  names
+              always start with ".", and nested folders are separated by "."s,
+              such as folder:.classes.topology. For "file system" maildir, the
+              inbox is typically folder:INBOX and nested folders are separated
+              by slashes, such as folder:classes/topology.
+
+              folder: will find a message if any copy of that  message  is  in
+              the specific folder.
+
+       date:<since>..<until> or date:<date>
+              The  date:  prefix  can  be used to restrict the results to only
+              messages within a particular time  range  (based  on  the  Date:
+              header).
+
+              See  DATE AND TIME SEARCH below for details on the range expres‐
+              sion, and supported syntax for <since> and <until> date and time
+              expressions.
+
+              The  time  range  can also be specified using timestamps without
+              including the date prefix using a syntax of:
+
+              <initial-timestamp>..<final-timestamp>
+
+              Each timestamp is a number representing the  number  of  seconds
+              since  1970-01-01 00:00:00 UTC. Specifying a time range this way
+              is considered legacy and predates the date prefix.
+
+       lastmod:<initial-revision>..<final-revision>
+              The lastmod: prefix can be used to restrict the  result  by  the
+              database  revision  number  of  when messages were last modified
+              (tags were added/removed or filenames changed). This is  usually
+              used  in  conjunction with the --uuid argument to notmuch search
+              to find messages that have changed since an earlier query.
+
+       query:<name>
+              The query: prefix allows queries to refer  to  previously  saved
+              queries  added  with  notmuch-config(1).  Named queries are only
+              available if notmuch is built with Xapian Field Processors  (see
+              below).
+
+       property:<key>=<value>
+              The  property:  prefix  searches  for messages with a particular
+              <key>=<value> property pair. Properties are used  internally  by
+              notmuch  (and  extensions)  to add metadata to messages. A given
+              key can be present on a given  message  with  several  different
+              values.  See notmuch-properties(7) for more details.
+
+       User  defined  prefixes  are  also supported, see notmuch-config(1) for
+       details.

  Operators

@@ -219,14 +236,14 @@ Xapian (and hence notmuch) prefixes are either boolean, supporting exact matches like "tag:inbox" or probabilistic, supporting a more flexible term based searching. Certain special prefixes are processed - by notmuch in a way not stricly fitting either of Xapian's built in + by notmuch in a way not strictly fitting either of Xapian's built in styles. The prefixes currently supported by notmuch are as follows. Boolean tag:, id:, thread:, folder:, path:, property: Probabilistic - to:, attachment:, mimetype: + body:, to:, attachment:, mimetype: Special from:, query:, subject: @@ -238,7 +255,7 @@ Phrases are indicated by double quotes (but beware you probably need to protect those from your shell) and insist that those unstemmed words occur in that order. One useful, but initially surprising feature is - that the following are equivalant ways to write the same phrase. + that the following are equivalent ways to write the same phrase. · "a list of words" @@ -249,7 +266,7 @@ · a.list.of.words Both parenthesised lists of terms and quoted phrases are ok with proba‐ - bilisitic prefixes such as to:, from:, and subject:. In particular + bilistic prefixes such as to:, from:, and subject:. In particular subject:(pizza free) @@ -264,13 +281,32 @@ will not. +

  Quoting

+
+       Double quotes are also used by the  notmuch  query  parser  to  protect
+       boolean  terms, regular expressions, or subqueries containing spaces or
+       other special characters, e.g.
+
+          tag:"a tag"
+
+          folder:"/^.*/(Junk|Spam)$/"
+
+          thread:"{from:mallory and date:2009}"
+
+       As with phrases, you need to protect the double quotes from  the  shell
+       e.g.
+
+          % notmuch search 'folder:"/^.*/(Junk|Spam)$/"'
+          % notmuch search 'thread:"{from:mallory and date:2009}" and thread:{to:mallory}'
+
+

DATE AND TIME SEARCH

-       notmuch understands a variety of standard and natural ways of  express‐
+       notmuch  understands a variety of standard and natural ways of express‐
        ing dates and times, both in absolute terms ("2012-10-24") and in rela‐
-       tive terms ("yesterday"). Any number of relative terms can be  combined
-       ("1  hour  25  minutes") and an absolute date/time can be combined with
-       relative terms to further adjust it. A  non-exhaustive  description  of
+       tive  terms ("yesterday"). Any number of relative terms can be combined
+       ("1 hour 25 minutes") 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.
@@ -278,15 +314,21 @@ 
        date:<since>..<until>
 
-       The  above  expression  restricts  the  results  to  only messages from
+       The above expression  restricts  the  results  to  only  messages  from
        <since> to <until>, based on the Date: header.
 
-       <since> and <until> can describe imprecise times, such as  "yesterday".
-       In  this  case, <since> is taken as the earliest time it could describe
+       <since>  and <until> can describe imprecise times, such as "yesterday".
+       In this case, <since> is taken as the earliest time it  could  describe
        (the beginning of yesterday) and <until> is taken as the latest time it
-       could  describe (the end of yesterday). Similarly, date:january..febru‐
+       could describe (the end of yesterday). Similarly,  date:january..febru‐
        ary matches from the beginning of January to the end of February.
 
+       If  specifying  a  time  range using timestamps in conjunction with the
+       date prefix, each timestamp must be preceded by @ (ASCII  hex  40).  As
+       above,  each  timestamp  is a number representing the number of seconds
+       since 1970-01-01 00:00:00 UTC. For example:
+          date:@<initial-timestamp>..@<final-timestamp>
+
        date:<expr>..! can be used as a shorthand for date:<expr>..<expr>.  The
        expansion  takes  place  before  interpretation, and thus, for example,
        date:monday..! matches from the beginning of Monday until  the  end  of
@@ -395,13 +437,16 @@
        · named queries e.g. "query:my_special_query"
 
        · regular expression searches, e.g. "subject:/^\[SPAM\]/"
+
+       · thread subqueries, e.g. "thread:{from:bob}"

SEE ALSO

        notmuch(1), notmuch-config(1), notmuch-count(1), notmuch-dump(1),  not‐
-       much-hooks(5),   notmuch-insert(1),  notmuch-new(1),  notmuch-reply(1),
-       notmuch-restore(1), notmuch-search(1), notmuch-show(1), notmuch-tag(1)
+       much-hooks(5),  notmuch-insert(1),  notmuch-new(1), notmuch-reindex(1),
+       notmuch-properties(1),  *notmuch-reply(1),   notmuch-restore(1),   not‐
+       much-search(1), *notmuch-show(1), notmuch-tag(1)

AUTHOR

@@ -411,7 +456,7 @@

COPYRIGHT

-       2009-2017, Carl Worth and many others
+       2009-2019, Carl Worth and many others
-

0.24

+

0.29