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 (<b>new-</b>
  86                <b>est-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|all|flag)</b>
 107
 108                A message is called &quot;excluded&quot; if it matches at least  one  tag
 109                in  search.tag_exclude  that  does not appear explicitly in the
 110                search terms.  This option specifies whether to  omit  excluded
 111                messages in the search process.
 112
 113                The default value, <b>true</b>, prevents excluded messages from match-
 114                ing the search terms.
 115
 116                <b>all</b> additionally prevents excluded messages from  appearing  in
 117                displayed  results,  in  effect behaving as though the excluded
 118                messages do not exist.
 119
 120                <b>false</b> allows excluded messages to match search terms and appear
 121                in displayed results. Excluded messages are still marked in the
 122                relevant outputs.
 123
 124                <b>flag</b> only has an effect when <b>--output=summary</b>.  The  output  is
 125                almost  identical to <b>false</b>, but the &quot;match count&quot; is the number
 126                of matching non-excluded messages in the  thread,  rather  than
 127                the number of matching messages.
 128 </pre>
 129
 130 <h2>EXIT STATUS</h2>
 131 <pre>
 132        This command supports the following special exit status codes
 133
 134        <b>20</b>     The requested format version is too old.
 135
 136        <b>21</b>     The requested format version is too new.
 137 </pre>
 138
 139 <h2>SEE ALSO</h2>
 140 <pre>
 141        <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>
 142        <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),
 143        <a href='../notmuch-restore-1/'>notmuch-restore</a>(1),  <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-</a>
 144        <a href='../notmuch-tag-1/'>tag</a>(1)
 145 </pre>
 146
 147 <h2>Notmuch 0.16</h2>