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>text</b>)
  30
  31                Presents the results in either JSON or plain-text (default).
  32
  33            <b>--output=(summary|threads|messages|files|tags)</b>
  34
  35                <b>summary</b>
  36
  37                    Output  a  summary of each thread with any message matching
  38                    the search terms. The summary includes the thread ID, date,
  39                    the  number  of  messages  in  the  thread (both the number
  40                    matched and the total number), the authors  of  the  thread
  41                    and the subject.
  42
  43                <b>threads</b>
  44
  45                    Output  the  thread  IDs  of  all  threads with any message
  46                    matching the search terms,  either  one  per  line  (--for-
  47                    mat=text) or as a JSON array (--format=json).
  48
  49                <b>messages</b>
  50
  51                    Output  the message IDs of all messages matching the search
  52                    terms, either one per line (--format=text)  or  as  a  JSON
  53                    array (--format=json).
  54
  55                <b>files</b>
  56
  57                    Output  the  filenames  of all messages matching the search
  58                    terms, either one per line (--format=text)  or  as  a  JSON
  59                    array (--format=json).
  60
  61                <b>tags</b>
  62
  63                    Output  all  tags  that  appear on any message matching the
  64                    search terms, either one per line (--format=text) or  as  a
  65                    JSON array (--format=json).
  66
  67            <b>--sort=</b>(<b>newest-first</b>|<b>oldest-first</b>)
  68
  69                This option can be used to present results in either chronolog-
  70                ical  order  (<b>oldest-first</b>)  or  reverse  chronological   order
  71                (<b>newest-first</b>).
  72
  73                Note:  The  thread  order  will  be  distinct between these two
  74                options (beyond being simply reversed). When  sorting  by  <b>old-</b>
  75                <b>est-first</b>  the  threads will be sorted by the oldest message in
  76                each thread, but when sorting by <b>newest-first</b> the threads  will
  77                be sorted by the newest message in each thread.
  78
  79                By  default, results will be displayed in reverse chronological
  80                order, (that is, the newest results will be displayed first).
  81
  82            <b>--offset=[-]N</b>
  83
  84                Skip displaying the first N  results.  With  the  leading  &apos;-&apos;,
  85                start at the Nth result from the end.
  86
  87            <b>--limit=N</b>
  88
  89                Limit the number of displayed results to N.
  90
  91            <b>--exclude=(true|false|flag)</b>
  92
  93                Specify  whether  to  omit messages matching search.tag_exclude
  94                from the search results (the default) or not. The extra  option
  95                <b>flag</b>  only has an effect when <b>--output=summary</b> In this case all
  96                matching threads are returned but the &quot;match count&quot; is the num-
  97                ber of matching non-excluded messages in the thread.
  98 </pre>
  99
 100 <h2>SEE ALSO</h2>
 101 <pre>
 102        <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>
 103        <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),
 104        <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)
 105 </pre>
 106
 107 <h2>Notmuch 0.14</h2>