NOTMUCH-SEARCH(1)

NAME

       notmuch-search - search for messages matching the given search terms

SYNOPSIS

       notmuch search [option ...] <search-term> ...

DESCRIPTION

       Search for messages matching the given search terms, and display as re‐
       sults the threads containing the matched messages.

       The output consists of one line per thread, giving  a  thread  ID,  the
       date  of  the  newest (or oldest, depending on the sort option) matched
       message in the thread, the number of matched messages  and  total  mes‐
       sages  in  the thread, the names of all participants in the thread, and
       the subject of the newest (or oldest) message.

       See notmuch-search-terms(7) for details of  the  supported  syntax  for
       <search-terms>.

       Supported options for search include

       --format=(json|sexp|text|text0)
              Presents  the  results  in  either  JSON, S-Expressions, newline
              character separated plain-text (default), or null character sep‐
              arated  plain-text  (compatible  with  xargs(1)  -0 option where
              available).

       --format-version=N
              Use the specified structured output format version. This is  in‐
              tended  for programs that invoke notmuch(1) internally. If omit‐
              ted, the latest supported version will be used.

       --output=(summary|threads|messages|files|tags)

              summary
                     Output a summary of each thread with any message matching
                     the  search  terms.  The  summary includes the thread ID,
                     date, the number of messages in the thread (both the num‐
                     ber  matched  and  the  total number), the authors of the
                     thread and the subject. In the case where a  thread  con‐
                     tains  multiple files for some messages, the total number
                     of files is printed in parentheses (see below for an  ex‐
                     ample).

              threads
                     Output  the  thread  IDs  of all threads with any message
                     matching the search terms, either one  per  line  (--for-
                     mat=text), separated by null characters (--format=text0),
                     as a JSON array (--format=json), or an S-Expression  list
                     (--format=sexp).

              messages
                     Output  the  message  IDs  of  all  messages matching the
                     search terms, either one per line (--format=text),  sepa‐
                     rated  by null characters (--format=text0), as a JSON ar‐
                     ray (--format=json), or as an S-Expression  list  (--for-
                     mat=sexp).

              files  Output  the filenames of all messages matching the search
                     terms, either one per line (--format=text), separated  by
                     null characters (--format=text0), as a JSON array (--for-
                     mat=json), or as an S-Expression list (--format=sexp).

                     Note that each message may have multiple filenames  asso‐
                     ciated  with  it.  All of them are included in the output
                     (unless limited with the --duplicate=N option). This  may
                     be  particularly  confusing for folder: or path: searches
                     in a specified directory, as the messages may have dupli‐
                     cates  in other directories that are included in the out‐
                     put, although these  files  alone  would  not  match  the
                     search.

              tags   Output  all  tags that appear on any message matching the
                     search terms, either one per line (--format=text),  sepa‐
                     rated  by null characters (--format=text0), as a JSON ar‐
                     ray (--format=json), or as an S-Expression  list  (--for-
                     mat=sexp).

       --sort=(newest-first|oldest-first)
              This option can be used to present results in either chronologi‐
              cal order (oldest-first) or reverse  chronological  order  (new-
              est-first).

              Note:  The  thread  order will be distinct between these two op‐
              tions (beyond being  simply  reversed).  When  sorting  by  old-
              est-first  the  threads  will be sorted by the oldest message in
              each thread, but when sorting by newest-first the  threads  will
              be sorted by the newest message in each thread.

              By  default,  results will be displayed in reverse chronological
              order, (that is, the newest results will be displayed first).

       --offset=[-]N
              Skip displaying the first N results. With the leading '-', start
              at the Nth result from the end.

       --limit=N
              Limit the number of displayed results to N.

       --exclude=(true|false|all|flag)
              A message is called "excluded" if it matches at least one tag in
              search.exclude_tags that  does  not  appear  explicitly  in  the
              search  terms.  This  option  specifies whether to omit excluded
              messages in the search process.

              true (default)
                     Prevent excluded messages from matching the search terms.

              all    Additionally prevent excluded messages from appearing  in
                     displayed  results,  in effect behaving as though the ex‐
                     cluded messages do not exist.

              false  Allow excluded messages to match search terms and  appear
                     in  displayed results. Excluded messages are still marked
                     in the relevant outputs.

              flag   Only has an effect when --output=summary. The  output  is
                     almost  identical  to false, but the "match count" is the
                     number of matching non-excluded messages in  the  thread,
                     rather than the number of matching messages.

       --duplicate=N
              For --output=files, output the Nth filename associated with each
              message matching the query (N is 1-based). If N is greater  than
              the  number  of  files  associated with the message, don't print
              anything.

              For --output=messages,  only  output  message  IDs  of  messages
              matching the search terms that have at least N filenames associ‐
              ated with them.

              Note that this option is orthogonal with the folder: search pre‐
              fix. The prefix matches messages based on filenames. This option
              filters filenames of the matching messages.

EXAMPLE

       The following shows an example of the summary output format,  with  one
       message having multiple filenames.

          % notmuch search date:today.. and tag:bad-news
          thread:0000000000063c10 Today [1/1] Some Persun; To the bone (bad-news inbox unread)
          thread:0000000000063c25 Today [1/1(2)] Ann Other; Bears (bad-news inbox unread)
          thread:0000000000063c00 Today [1/1] A Thurd; Bites, stings, sad feelings (bad-news unread)

EXIT STATUS

       This command supports the following special exit status codes

       20     The requested format version is too old.

       21     The requested format version is too new.

SEE ALSO

       notmuch(1),  notmuch-config(1), notmuch-count(1), notmuch-dump(1), not‐
       much-hooks(5),  notmuch-insert(1),  notmuch-new(1),   notmuch-reply(1),
       notmuch-restore(1),   notmuch-search-terms(7),   notmuch-show(1),  not‐
       much-tag(1) notmuch-address(1)

AUTHOR

       Carl Worth and many others

COPYRIGHT

       2009-2021, Carl Worth and many others

0.32