git.cworth.org Git - 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>option</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 re‐
  16        sults 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=(json|sexp|text|text0)</b>
  30               Presents  the  results  in  either  JSON, S-Expressions, newline
  31               character separated plain-text (default), or null character sep‐
  32               arated  plain-text  (compatible  with  <b>xargs</b>(1)  -0 option where
  33               available).
  34
  35        <b>--format-version=N</b>
  36               Use the specified structured output format version. This is  in‐
  37               tended  for programs that invoke <a href='../notmuch-1/'>notmuch</a>(1) internally. If omit‐
  38               ted, the latest supported version will be used.
  39
  40        <b>--output=(summary|threads|messages|files|tags)</b>
  41
  42               <b>summary</b>
  43                      Output a summary of each thread with any message matching
  44                      the  search  terms.  The  summary includes the thread ID,
  45                      date, the number of messages in the thread (both the num‐
  46                      ber  matched  and  the  total number), the authors of the
  47                      thread and the subject. In the case where a  thread  con‐
  48                      tains  multiple files for some messages, the total number
  49                      of files is printed in parentheses (see below for an  ex‐
  50                      ample).
  51
  52               <b>threads</b>
  53                      Output  the  thread  IDs  of all threads with any message
  54                      matching the search terms, either one  per  line  (<b>--for-</b>
  55                      <b>mat=text</b>), separated by null characters (<b>--format=text0</b>),
  56                      as a JSON array (<b>--format=json</b>), or an S-Expression  list
  57                      (<b>--format=sexp</b>).
  58
  59               <b>messages</b>
  60                      Output  the  message  IDs  of  all  messages matching the
  61                      search terms, either one per line (<b>--format=text</b>),  sepa‐
  62                      rated  by null characters (<b>--format=text0</b>), as a JSON ar‐
  63                      ray (<b>--format=json</b>), or as an S-Expression  list  (<b>--for-</b>
  64                      <b>mat=sexp</b>).
  65
  66               <b>files</b>  Output  the filenames of all messages matching the search
  67                      terms, either one per line (<b>--format=text</b>), separated  by
  68                      null characters (<b>--format=text0</b>), as a JSON array (<b>--for-</b>
  69                      <b>mat=json</b>), or as an S-Expression list (<b>--format=sexp</b>).
  70
  71                      Note that each message may have multiple filenames  asso‐
  72                      ciated  with  it.  All of them are included in the output
  73                      (unless limited with the <b>--duplicate=N</b> option). This  may
  74                      be  particularly  confusing for <b>folder:</b> or <b>path:</b> searches
  75                      in a specified directory, as the messages may have dupli‐
  76                      cates  in other directories that are included in the out‐
  77                      put, although these  files  alone  would  not  match  the
  78                      search.
  79
  80               <b>tags</b>   Output  all  tags that appear on any message matching the
  81                      search terms, either one per line (<b>--format=text</b>),  sepa‐
  82                      rated  by null characters (<b>--format=text0</b>), as a JSON ar‐
  83                      ray (<b>--format=json</b>), or as an S-Expression  list  (<b>--for-</b>
  84                      <b>mat=sexp</b>).
  85
  86        <b>--sort=(newest-first|oldest-first)</b>
  87               This option can be used to present results in either chronologi‐
  88               cal order (<b>oldest-first</b>) or reverse  chronological  order  (<b>new-</b>
  89               <b>est-first</b>).
  90
  91               Note:  The  thread  order will be distinct between these two op‐
  92               tions (beyond being  simply  reversed).  When  sorting  by  <b>old-</b>
  93               <b>est-first</b>  the  threads  will be sorted by the oldest message in
  94               each thread, but when sorting by <b>newest-first</b> the  threads  will
  95               be sorted by the newest message in each thread.
  96
  97               By  default,  results will be displayed in reverse chronological
  98               order, (that is, the newest results will be displayed first).
  99
 100        <b>--offset=[-]N</b>
 101               Skip displaying the first N results. With the leading &apos;-&apos;, start
 102               at the Nth result from the end.
 103
 104        <b>--limit=N</b>
 105               Limit the number of displayed results to N.
 106
 107        <b>--exclude=(true|false|all|flag)</b>
 108               A message is called &quot;excluded&quot; if it matches at least one tag in
 109               search.exclude_tags 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               <b>true</b> <b>(default)</b>
 114                      Prevent excluded messages from matching the search terms.
 115
 116               <b>all</b>    Additionally prevent excluded messages from appearing  in
 117                      displayed  results,  in effect behaving as though the ex‐
 118                      cluded messages do not exist.
 119
 120               <b>false</b>  Allow excluded messages to match search terms and  appear
 121                      in  displayed results. Excluded messages are still marked
 122                      in the 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
 126                      number of matching non-excluded messages in  the  thread,
 127                      rather than the number of matching messages.
 128
 129        <b>--duplicate=N</b>
 130               For <b>--output=files</b>, output the Nth filename associated with each
 131               message matching the query (N is 1-based). If N is greater  than
 132               the  number  of  files  associated with the message, don&apos;t print
 133               anything.
 134
 135               For <b>--output=messages</b>,  only  output  message  IDs  of  messages
 136               matching the search terms that have at least N filenames associ‐
 137               ated with them.
 138
 139               Note that this option is orthogonal with the <b>folder:</b> search pre‐
 140               fix. The prefix matches messages based on filenames. This option
 141               filters filenames of the matching messages.
 142 </pre>
 143
 144 <h2>EXAMPLE</h2>
 145 <pre>
 146        The following shows an example of the summary output format,  with  one
 147        message having multiple filenames.
 148
 149           % notmuch search date:today.. and tag:bad-news
 150           thread:0000000000063c10 Today [1/1] Some Persun; To the bone (bad-news inbox unread)
 151           thread:0000000000063c25 Today [1/1(2)] Ann Other; Bears (bad-news inbox unread)
 152           thread:0000000000063c00 Today [1/1] A Thurd; Bites, stings, sad feelings (bad-news unread)
 153 </pre>
 154
 155 <h2>EXIT STATUS</h2>
 156 <pre>
 157        This command supports the following special exit status codes
 158
 159        <b>20</b>     The requested format version is too old.
 160
 161        <b>21</b>     The requested format version is too new.
 162 </pre>
 163
 164 <h2>SEE ALSO</h2>
 165 <pre>
 166        <a href='../notmuch-1/'>notmuch</a>(1),   <a href='../notmuch-address-1/'>notmuch-address</a>(1)  <a href='../notmuch-config-1/'>notmuch-config</a>(1),  <a href='../notmuch-count-1/'>notmuch-count</a>(1),
 167        <a href='../notmuch-dump-1/'>notmuch-dump</a>(1), <a href='../notmuch-hooks-5/'>notmuch-hooks</a>(5),  <a href='../notmuch-insert-1/'>notmuch-insert</a>(1),  <a href='../notmuch-new-1/'>notmuch-new</a>(1),
 168        <a href='../notmuch-reply-1/'>notmuch-reply</a>(1),   <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/'>not‐</a>
 169        <a href='../notmuch-show-1/'>much-show</a>(1), <a href='../notmuch-tag-1/'>notmuch-tag</a>(1)
 170 </pre>
 171
 172 <h2>AUTHOR</h2>
 173 <pre>
 174        Carl Worth and many others
 175 </pre>
 176
 177 <h2>COPYRIGHT</h2>
 178 <pre>
 179        2009-2022, Carl Worth and many others
 180 </pre>
 181
 182 <h2>0.35</h2>