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

   1 <h1>NOTMUCH-SEARCH(1)</h1>
   2
   3 <h2>NAME</h2>
   4
   5 <pre>
   6        notmuch-search - Search for messages matching the given search terms.
   7 </pre>
   8
   9 <h2>SYNOPSIS</h2>
  10
  11 <pre>
  12        <b>notmuch</b> <b>search</b> [<u>options</u>...] <<u>search-term</u>>...
  13 </pre>
  14
  15 <h2>DESCRIPTION</h2>
  16
  17 <pre>
  18        Search  for  messages  matching  the given search terms, and display as
  19        results the threads containing the matched messages.
  20 </pre>
  21
  22 <pre>
  23        The output consists of one line per thread, giving  a  thread  ID,  the
  24        date  of  the  newest (or oldest, depending on the sort option) matched
  25        message in the thread, the number of matched messages  and  total  mes-
  26        sages  in  the thread, the names of all participants in the thread, and
  27        the subject of the newest (or oldest) message.
  28 </pre>
  29
  30 <pre>
  31        See <b>notmuch-search-terms</b>(7) for details of  the  supported  syntax  for
  32        <search-terms>.
  33 </pre>
  34
  35 <pre>
  36        Supported options for <b>search</b> include
  37 </pre>
  38
  39 <pre>
  40            <b>--format=</b>(<b>json</b>|<b>text</b>)
  41 </pre>
  42
  43 <pre>
  44                Presents the results in either JSON or plain-text (default).
  45 </pre>
  46
  47 <pre>
  48            <b>--output=(summary|threads|messages|files|tags)</b>
  49 </pre>
  50
  51 <pre>
  52                <b>summary</b>
  53 </pre>
  54
  55 <pre>
  56                    Output  a  summary of each thread with any message matching
  57                    the search terms. The summary includes the thread ID, date,
  58                    the  number  of  messages  in  the  thread (both the number
  59                    matched and the total number), the authors  of  the  thread
  60                    and the subject.
  61 </pre>
  62
  63 <pre>
  64                <b>threads</b>
  65 </pre>
  66
  67 <pre>
  68                    Output  the  thread  IDs  of  all  threads with any message
  69                    matching the search terms,  either  one  per  line  (--for-
  70                    mat=text) or as a JSON array (--format=json).
  71 </pre>
  72
  73 <pre>
  74                <b>messages</b>
  75 </pre>
  76
  77 <pre>
  78                    Output  the message IDs of all messages matching the search
  79                    terms, either one per line (--format=text)  or  as  a  JSON
  80                    array (--format=json).
  81 </pre>
  82
  83 <pre>
  84                <b>files</b>
  85 </pre>
  86
  87 <pre>
  88                    Output  the  filenames  of all messages matching the search
  89                    terms, either one per line (--format=text)  or  as  a  JSON
  90                    array (--format=json).
  91 </pre>
  92
  93 <pre>
  94                <b>tags</b>
  95 </pre>
  96
  97 <pre>
  98                    Output  all  tags  that  appear on any message matching the
  99                    search terms, either one per line (--format=text) or  as  a
 100                    JSON array (--format=json).
 101 </pre>
 102
 103 <pre>
 104            <b>--sort=</b>(<b>newest-first</b>|<b>oldest-first</b>)
 105 </pre>
 106
 107 <pre>
 108                This option can be used to present results in either chronolog-
 109                ical order (<b>oldest-first</b>) or reverse chronological order  (<b>new-</b>
 110                <b>est-first</b>).
 111 </pre>
 112
 113 <pre>
 114                Note:  The  thread  order  will  be  distinct between these two
 115                options (beyond being simply reversed). When  sorting  by  <b>old-</b>
 116                <b>est-first</b>  the  threads will be sorted by the oldest message in
 117                each thread, but when sorting by <b>newest-first</b> the threads  will
 118                be sorted by the newest message in each thread.
 119 </pre>
 120
 121 <pre>
 122                By  default, results will be displayed in reverse chronological
 123                order, (that is, the newest results will be displayed first).
 124 </pre>
 125
 126 <pre>
 127            <b>--offset=[-]N</b>
 128 </pre>
 129
 130 <pre>
 131                Skip displaying the first N  results.  With  the  leading  '-',
 132                start at the Nth result from the end.
 133 </pre>
 134
 135 <pre>
 136            <b>--limit=N</b>
 137 </pre>
 138
 139 <pre>
 140                Limit the number of displayed results to N.
 141 </pre>
 142
 143 <pre>
 144            <b>--exclude=(true|false|flag)</b>
 145 </pre>
 146
 147 <pre>
 148                Specify  whether  to  omit messages matching search.tag_exclude
 149                from the search results (the default) or not. The extra  option
 150                <b>flag</b>  only has an effect when <b>--output=summary</b> In this case all
 151                matching threads are returned but the "match count" is the num-
 152                ber of matching non-excluded messages in the thread.
 153 </pre>
 154
 155 <h2>SEE ALSO</h2>
 156
 157 <pre>
 158        <b>notmuch</b>(1),  <b>notmuch-config</b>(1), <b>notmuch-count</b>(1), <b>notmuch-dump</b>(1), <b>not-</b>
 159        <b>much-hooks</b>(5),  <b>notmuch-new</b>(1),  <b>notmuch-reply</b>(1),  <b>notmuch-restore</b>(1),
 160        <b>notmuch-search-terms</b>(7), <b>notmuch-show</b>(1), <b>notmuch-tag</b>(1)
 161 </pre>
 162
 163 <h1>Notmuch 0.13.2</h1>