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>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                    Note that each message may have multiple filenames  associ-
  75                    ated  with  it.   All  of  them are included in the output,
  76                    unless limited with the --duplicate=N option.
  77
  78                <b>tags</b>
  79
  80                    Output all tags that appear on  any  message  matching  the
  81                    search  terms,  either  one per line (--format=text), sepa-
  82                    rated by null characters (--format=text0), as a JSON  array
  83                    (--format=json),   or   as  an  S-Expression  list  (--for-
  84                    mat=sexp).
  85
  86            <b>--sort=</b>(<b>newest-first</b>|<b>oldest-first</b>)
  87
  88                This option can be used to present results in either chronolog-
  89                ical   order  (<b>oldest-first</b>)  or  reverse  chronological  order
  90                (<b>newest-first</b>).
  91
  92                Note: The thread order  will  be  distinct  between  these  two
  93                options  (beyond  being  simply reversed). When sorting by <b>old-</b>
  94                <b>est-first</b> the threads will be sorted by the oldest  message  in
  95                each  thread, but when sorting by <b>newest-first</b> the threads will
  96                be sorted by the newest message in each thread.
  97
  98                By default, results will be displayed in reverse  chronological
  99                order, (that is, the newest results will be displayed first).
 100
 101            <b>--offset=[-]N</b>
 102
 103                Skip  displaying  the  first  N  results. With the leading &apos;-&apos;,
 104                start at the Nth result from the end.
 105
 106            <b>--limit=N</b>
 107
 108                Limit the number of displayed results to N.
 109
 110            <b>--exclude=(true|false|all|flag)</b>
 111
 112                A message is called &quot;excluded&quot; if it matches at least  one  tag
 113                in  search.tag_exclude  that  does not appear explicitly in the
 114                search terms.  This option specifies whether to  omit  excluded
 115                messages in the search process.
 116
 117                The default value, <b>true</b>, prevents excluded messages from match-
 118                ing the search terms.
 119
 120                <b>all</b> additionally prevents excluded messages from  appearing  in
 121                displayed  results,  in  effect behaving as though the excluded
 122                messages do not exist.
 123
 124                <b>false</b> allows excluded messages to match search terms and appear
 125                in displayed results. Excluded messages are still marked in the
 126                relevant outputs.
 127
 128                <b>flag</b> only has an effect when <b>--output=summary</b>.  The  output  is
 129                almost  identical to <b>false</b>, but the &quot;match count&quot; is the number
 130                of matching non-excluded messages in the  thread,  rather  than
 131                the number of matching messages.
 132
 133            <b>--duplicate=N</b>
 134
 135                Effective  with <b>--output=files</b>, output the Nth filename associ-
 136                ated with each message matching the query (N is 1-based). If  N
 137                is  greater  than  the number of files associated with the mes-
 138                sage, don&apos;t print anything.
 139
 140                Note that this option is orthogonal  with  the  <b>folder:</b>  search
 141                prefix.  The  prefix  matches messages based on filenames. This
 142                option filters filenames of the matching messages.
 143 </pre>
 144
 145 <h2>EXIT STATUS</h2>
 146 <pre>
 147        This command supports the following special exit status codes
 148
 149        <b>20</b>     The requested format version is too old.
 150
 151        <b>21</b>     The requested format version is too new.
 152 </pre>
 153
 154 <h2>SEE ALSO</h2>
 155 <pre>
 156        <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>
 157        <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),
 158        <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>
 159        <a href='../notmuch-tag-1/'>tag</a>(1)
 160 </pre>
 161
 162 <h2>Notmuch 0.17</h2>