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