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
  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=(json|sexp|text|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
  34                   where 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            --output=(summary|threads|messages|files|tags)
  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,
  48                      date, the number of messages in the thread (both the num-
  49                      ber  matched  and  the  total number), the authors of the
  50                      thread 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
  63                      search  terms, either one per line (--format=text), sepa-
  64                      rated by null  characters  (--format=text0),  as  a  JSON
  65                      array (--format=json), or as an S-Expression list (--for-
  66                      mat=sexp).
  67
  68               <b>files</b>
  69
  70                      Output the filenames of all messages matching the  search
  71                      terms,  either one per line (--format=text), separated by
  72                      null characters (--format=text0), as a JSON array (--for-
  73                      mat=json), or as an S-Expression list (--format=sexp).
  74
  75                      Note  that each message may have multiple filenames asso-
  76                      ciated with it. All of them are included  in  the  output
  77                      (unless  limited with the --duplicate=N option). This may
  78                      be particularly confusing for <b>folder:</b> or  <b>path:</b>  searches
  79                      in a specified directory, as the messages may have dupli-
  80                      cates in other directories that are included in the  out-
  81                      put,  although  these  files  alone  would  not match the
  82                      search.
  83
  84               <b>tags</b>
  85
  86                      Output all tags that appear on any message  matching  the
  87                      search  terms, either one per line (--format=text), sepa-
  88                      rated by null  characters  (--format=text0),  as  a  JSON
  89                      array (--format=json), or as an S-Expression list (--for-
  90                      mat=sexp).
  91
  92            <b>--sort=(newest-first|oldest-first)</b>
  93
  94                   This option can be used to present results in either chrono-
  95                   logical  order (<b>oldest-first</b>) or reverse chronological order
  96                   (<b>newest-first</b>).
  97
  98                   Note: The thread order will be distinct  between  these  two
  99                   options (beyond being simply reversed). When sorting by <b>old-</b>
 100                   <b>est-first</b> the threads will be sorted by the  oldest  message
 101                   in each thread, but when sorting by <b>newest-first</b> the threads
 102                   will be sorted by the newest message in each thread.
 103
 104                   By default, results will be displayed in reverse chronologi-
 105                   cal  order,  (that  is, the newest results will be displayed
 106                   first).
 107
 108            <b>--offset=[-]N</b>
 109
 110                   Skip displaying the first N results. With the  leading  &apos;-&apos;,
 111                   start at the Nth result from the end.
 112
 113            <b>--limit=N</b>
 114
 115                   Limit the number of displayed results to N.
 116
 117            <b>--exclude=(true|false|all|flag)</b>
 118
 119                   A  message  is  called &quot;excluded&quot; if it matches at least one
 120                   tag in search.tag_exclude that does not appear explicitly in
 121                   the  search  terms.  This  option  specifies whether to omit
 122                   excluded messages in the search process.
 123
 124                   The default value, <b>true</b>,  prevents  excluded  messages  from
 125                   matching the search terms.
 126
 127                   <b>all</b>  additionally  prevents excluded messages from appearing
 128                   in displayed results,  in  effect  behaving  as  though  the
 129                   excluded messages do not exist.
 130
 131                   <b>false</b>  allows  excluded  messages  to match search terms and
 132                   appear in displayed results.  Excluded  messages  are  still
 133                   marked in the relevant outputs.
 134
 135                   <b>flag</b> only has an effect when --output=summary. The output is
 136                   almost identical to <b>false</b>, but the &quot;match count&quot; is the num-
 137                   ber  of matching non-excluded messages in the thread, rather
 138                   than the number of matching messages.
 139
 140            <b>--duplicate=N</b>
 141
 142                   Effective with --output=files, output the Nth filename asso-
 143                   ciated  with each message matching the query (N is 1-based).
 144                   If N is greater than the number of files associated with the
 145                   message, don&apos;t print anything.
 146
 147                   Note  that this option is orthogonal with the <b>folder:</b> search
 148                   prefix. The prefix matches messages based on filenames. This
 149                   option filters filenames of the matching messages.
 150 </pre>
 151
 152 <h2>EXIT STATUS</h2>
 153 <pre>
 154        This command supports the following special exit status codes
 155
 156        <b>20</b>
 157
 158               The requested format version is too old.
 159
 160        <b>21</b>
 161
 162               The requested format version is too new.
 163 </pre>
 164
 165 <h2>SEE ALSO</h2>
 166 <pre>
 167        <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>
 168        <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),
 169        <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/'>not-</a>
 170        <a href='../notmuch-tag-1/'>much-tag</a>(1)
 171 </pre>
 172
 173 <h2>AUTHOR</h2>
 174 <pre>
 175        Carl Worth and many others
 176 </pre>
 177
 178 <h2>COPYRIGHT</h2>
 179 <pre>
 180        2014, Carl Worth and many others
 181 </pre>
 182
 183 <h2>0.18</h2>