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

   1 <h1>NOTMUCH-SEARCH(1)</h1>
   2
   3 <h2>NAME</h2>
   4 <pre>
   5        notmuch-search - search for messages matching the given search terms
   6 </pre>
   7
   8 <h2>SYNOPSIS</h2>
   9 <pre>
  10        <b>notmuch</b> <b>search</b> [<u>options</u>...] &lt;<u>search-term</u>&gt;...
  11 </pre>
  12
  13 <h2>DESCRIPTION</h2>
  14 <pre>
  15        Search  for  messages  matching  the given search terms, and display as
  16        results the threads containing the matched messages.
  17
  18        The output consists of one line per thread, giving  a  thread  ID,  the
  19        date  of  the  newest (or oldest, depending on the sort option) matched
  20        message in the thread, the number of matched messages  and  total  mes-
  21        sages  in  the thread, the names of all participants in the thread, and
  22        the subject of the newest (or oldest) message.
  23
  24        See <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7) for details of  the  supported  syntax  for
  25        &lt;search-terms&gt;.
  26
  27        Supported options for <b>search</b> include
  28
  29            <b>--format=</b>(<b>json</b>|<b>sexp</b>|<b>text</b>|<b>text0</b>)
  30
  31                Presents  the  results  in  either JSON, S-Expressions, newline
  32                character separated plain-text  (default),  or  null  character
  33                separated  plain-text (compatible with <b>xargs</b>(1) -0 option where
  34                available).
  35
  36            <b>--format-version=N</b>
  37
  38                Use the specified structured output format  version.   This  is
  39                intended  for  programs  that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally.  If
  40                omitted, the latest supported version will be used.
  41
  42            <b>--output=(summary|threads|messages|files|tags)</b>
  43
  44                <b>summary</b>
  45
  46                    Output a summary of each thread with any  message  matching
  47                    the search terms. The summary includes the thread ID, date,
  48                    the number of messages  in  the  thread  (both  the  number
  49                    matched  and  the  total number), the authors of the thread
  50                    and the subject.
  51
  52                <b>threads</b>
  53
  54                    Output the thread IDs  of  all  threads  with  any  message
  55                    matching  the  search  terms,  either  one per line (--for-
  56                    mat=text), separated by null  characters  (--format=text0),
  57                    as  a  JSON  array (--format=json), or an S-Expression list
  58                    (--format=sexp).
  59
  60                <b>messages</b>
  61
  62                    Output the message IDs of all messages matching the  search
  63                    terms,  either  one  per line (--format=text), separated by
  64                    null characters (--format=text0), as a JSON  array  (--for-
  65                    mat=json), or as an S-Expression list (--format=sexp).
  66
  67                <b>files</b>
  68
  69                    Output  the  filenames  of all messages matching the search
  70                    terms, either one per line  (--format=text),  separated  by
  71                    null  characters  (--format=text0), as a JSON array (--for-
  72                    mat=json), or as an S-Expression list (--format=sexp).
  73
  74                <b>tags</b>
  75
  76                    Output all tags that appear on  any  message  matching  the
  77                    search  terms,  either  one per line (--format=text), sepa-
  78                    rated by null characters (--format=text0), as a JSON  array
  79                    (--format=json),   or   as  an  S-Expression  list  (--for-
  80                    mat=sexp).
  81
  82            <b>--sort=</b>(<b>newest-first</b>|<b>oldest-first</b>)
  83
  84                This option can be used to present results in either chronolog-
  85                ical   order  (<b>oldest-first</b>)  or  reverse  chronological  order
  86                (<b>newest-first</b>).
  87
  88                Note: The thread order  will  be  distinct  between  these  two
  89                options  (beyond  being  simply reversed). When sorting by <b>old-</b>
  90                <b>est-first</b> the threads will be sorted by the oldest  message  in
  91                each  thread, but when sorting by <b>newest-first</b> the threads will
  92                be sorted by the newest message in each thread.
  93
  94                By default, results will be displayed in reverse  chronological
  95                order, (that is, the newest results will be displayed first).
  96
  97            <b>--offset=[-]N</b>
  98
  99                Skip  displaying  the  first  N  results. With the leading &apos;-&apos;,
 100                start at the Nth result from the end.
 101
 102            <b>--limit=N</b>
 103
 104                Limit the number of displayed results to N.
 105
 106            <b>--exclude=(true|false|flag)</b>
 107
 108                Specify whether to omit  messages  matching  search.tag_exclude
 109                from  the search results (the default) or not. The extra option
 110                <b>flag</b> only has an effect when <b>--output=summary</b> In this case  all
 111                matching threads are returned but the &quot;match count&quot; is the num-
 112                ber of matching non-excluded messages in the thread.
 113 </pre>
 114
 115 <h2>EXIT STATUS</h2>
 116 <pre>
 117        This command supports the following special exit status codes
 118
 119        <b>20</b>     The requested format version is too old.
 120
 121        <b>21</b>     The requested format version is too new.
 122 </pre>
 123
 124 <h2>SEE ALSO</h2>
 125 <pre>
 126        <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>
 127        <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),
 128        <a href='../notmuch-search-terms-7/'>notmuch-search-terms</a>(7), <a href='../notmuch-show-1/'>notmuch-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
 129 </pre>
 130
 131 <h2>Notmuch 0.15.2</h2>