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

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