git.notmuchmail.org Git - notmuch/blob - doc/man1/notmuch-search.rst

   1 ==============
   2 notmuch-search
   3 ==============
   4
   5 SYNOPSIS
   6 ========
   7
   8 **notmuch** **search** [*option* ...] <*search-term*> ...
   9
  10 DESCRIPTION
  11 ===========
  12
  13 Search for messages matching the given search terms, and display as
  14 results the threads containing the matched messages.
  15
  16 The output consists of one line per thread, giving a thread ID, the date
  17 of the newest (or oldest, depending on the sort option) matched message
  18 in the thread, the number of matched messages and total messages in the
  19 thread, the names of all participants in the thread, and the subject of
  20 the newest (or oldest) message.
  21
  22 See **notmuch-search-terms(7)** for details of the supported syntax for
  23 <search-terms>.
  24
  25 Supported options for **search** include
  26
  27 ``--format=``\ (**json**\ \|\ **sexp**\ \|\ **text**\ \|\ **text0**)
  28     Presents the results in either JSON, S-Expressions, newline
  29     character separated plain-text (default), or null character
  30     separated plain-text (compatible with **xargs(1)** -0 option where
  31     available).
  32
  33 ``--format-version=N``
  34     Use the specified structured output format version. This is
  35     intended for programs that invoke **notmuch(1)** internally. If
  36     omitted, the latest supported version will be used.
  37
  38 ``--output=(summary|threads|messages|files|tags)``
  39     **summary**
  40         Output a summary of each thread with any message matching the
  41         search terms. The summary includes the thread ID, date, the
  42         number of messages in the thread (both the number matched and
  43         the total number), the authors of the thread and the
  44         subject. In the case where a thread contains multiple files
  45         for some messages, the total number of files is printed in
  46         parentheses (see below for an example).
  47
  48     **threads**
  49         Output the thread IDs of all threads with any message matching
  50         the search terms, either one per line (--format=text),
  51         separated by null characters (--format=text0), as a JSON array
  52         (--format=json), or an S-Expression list (--format=sexp).
  53
  54     **messages**
  55         Output the message IDs of all messages matching the search
  56         terms, either one per line (--format=text), separated by null
  57         characters (--format=text0), as a JSON array (--format=json),
  58         or as an S-Expression list (--format=sexp).
  59
  60     **files**
  61         Output the filenames of all messages matching the search
  62         terms, either one per line (--format=text), separated by null
  63         characters (--format=text0), as a JSON array (--format=json),
  64         or as an S-Expression list (--format=sexp).
  65
  66         Note that each message may have multiple filenames associated
  67         with it. All of them are included in the output (unless
  68         limited with the --duplicate=N option). This may be
  69         particularly confusing for **folder:** or **path:** searches
  70         in a specified directory, as the messages may have duplicates
  71         in other directories that are included in the output, although
  72         these files alone would not match the search.
  73
  74     **tags**
  75         Output all tags that appear on any message matching the search
  76         terms, either one per line (--format=text), separated by null
  77         characters (--format=text0), as a JSON array (--format=json),
  78         or as an S-Expression list (--format=sexp).
  79
  80 ``--sort=``\ (**newest-first**\ \|\ **oldest-first**)
  81     This option can be used to present results in either chronological
  82     order (**oldest-first**) or reverse chronological order
  83     (**newest-first**).
  84
  85     Note: The thread order will be distinct between these two options
  86     (beyond being simply reversed). When sorting by **oldest-first**
  87     the threads will be sorted by the oldest message in each thread,
  88     but when sorting by **newest-first** the threads will be sorted by
  89     the newest message in each thread.
  90
  91     By default, results will be displayed in reverse chronological
  92     order, (that is, the newest results will be displayed first).
  93
  94 ``--offset=[-]N``
  95     Skip displaying the first N results. With the leading '-', start
  96     at the Nth result from the end.
  97
  98 ``--limit=N``
  99     Limit the number of displayed results to N.
 100
 101 ``--exclude=(true|false|all|flag)``
 102     A message is called "excluded" if it matches at least one tag in
 103     search.tag\_exclude that does not appear explicitly in the search
 104     terms. This option specifies whether to omit excluded messages in
 105     the search process.
 106
 107     **true** (default)
 108         Prevent excluded messages from matching the search terms.
 109
 110     **all**
 111         Additionally prevent excluded messages from appearing in
 112         displayed results, in effect behaving as though the excluded
 113         messages do not exist.
 114
 115     **false**
 116         Allow excluded messages to match search terms and appear in
 117         displayed results. Excluded messages are still marked in the
 118         relevant outputs.
 119
 120     **flag**
 121         Only has an effect when ``--output=summary``. The output is
 122         almost identical to **false**, but the "match count" is the
 123         number of matching non-excluded messages in the thread, rather
 124         than the number of matching messages.
 125
 126 ``--duplicate=N``
 127     For ``--output=files``, output the Nth filename associated with
 128     each message matching the query (N is 1-based). If N is greater
 129     than the number of files associated with the message, don't print
 130     anything.
 131
 132     For ``--output=messages``, only output message IDs of messages
 133     matching the search terms that have at least N filenames
 134     associated with them.
 135
 136     Note that this option is orthogonal with the **folder:** search
 137     prefix. The prefix matches messages based on filenames. This
 138     option filters filenames of the matching messages.
 139
 140 EXAMPLE
 141 =======
 142
 143 The following shows an example of the summary output format, with one
 144 message having multiple filenames.
 145
 146 ::
 147
 148   % notmuch search date:today.. and tag:bad-news
 149   thread:0000000000063c10 Today [1/1] Some Persun; To the bone (inbox unread)
 150   thread:0000000000063c25 Today [1/1(2)] Ann Other; Bears (inbox unread)
 151   thread:0000000000063c00 Today [1/1] A Thurd; Bites, stings, sad feelings (inbox unread)
 152
 153 EXIT STATUS
 154 ===========
 155
 156 This command supports the following special exit status codes
 157
 158 ``20``
 159     The requested format version is too old.
 160
 161 ``21``
 162     The requested format version is too new.
 163
 164 SEE ALSO
 165 ========
 166
 167 **notmuch(1)**,
 168 **notmuch-config(1)**,
 169 **notmuch-count(1)**,
 170 **notmuch-dump(1)**,
 171 **notmuch-hooks(5)**,
 172 **notmuch-insert(1)**,
 173 **notmuch-new(1)**,
 174 **notmuch-reply(1)**,
 175 **notmuch-restore(1)**,
 176 **notmuch-search-terms(7)**,
 177 **notmuch-show(1)**,
 178 **notmuch-tag(1)**
 179 **notmuch-address(1)**