Ubuntu Manpage: notmuch-search - search for messages matching the given search terms

NAME

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

SYNOPSIS

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

DESCRIPTION

       Search  for  messages  matching the given search terms, and display as results 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
       messages 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 separated plain-text  (compatible  with  xargs(1)  -0  option  where
               available).

           --format-version=N

               Use  the  specified  structured output format version.  This is intended for programs that invoke
               notmuch(1) internally.  If omitted, 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 number matched
                   and the total number), the authors of the thread and the subject.

               threads

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

                   Note that each message may have multiple filenames associated  with  it.   All  of  them  are
                   included in the output, unless limited with the --duplicate=N option.

               tags

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

           --sort=(newest-first|oldest-first)

               This  option  can  be  used  to  present  results in either chronological order (oldest-first) or
               reverse chronological order (newest-first).

               Note: The thread order will be distinct between these two options (beyond being simply reversed).
               When sorting by oldest-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.tag_exclude that does not
               appear  explicitly  in the search terms.  This option specifies whether to omit excluded messages
               in the search process.

               The default value, true, prevents excluded messages from matching the search terms.

               all additionally prevents excluded messages  from  appearing  in  displayed  results,  in  effect
               behaving as though the excluded messages do not exist.

               false  allows  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

               Effective with --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.

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

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.

NAME

SYNOPSIS

DESCRIPTION

EXIT STATUS

SEE ALSO