+.. _notmuch-search(1):
+
==============
notmuch-search
==============
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
+See :any:`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).
+ separated plain-text (compatible with :manpage:`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
+ intended for programs that invoke :any:`notmuch(1)` internally. If
omitted, the latest supported version will be used.
``--output=(summary|threads|messages|files|tags)``
**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).
+ 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).
+ 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).
+ 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). This may be
+ 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 duplicates
in other directories that are included in the output, although
**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).
+ 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
``--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
+ search.exclude\_tags that does not appear explicitly in the search
terms. This option specifies whether to omit excluded messages in
the search process.
SEE ALSO
========
-**notmuch(1)**,
-**notmuch-config(1)**,
-**notmuch-count(1)**,
-**notmuch-dump(1)**,
-**notmuch-hooks(5)**,
-**notmuch-insert(1)**,
-**notmuch-new(1)**,
-**notmuch-reply(1)**,
-**notmuch-restore(1)**,
-**notmuch-search-terms(7)**,
-**notmuch-show(1)**,
-**notmuch-tag(1)**
-**notmuch-address(1)**
+:any:`notmuch(1)`,
+:any:`notmuch-address(1)`
+:any:`notmuch-config(1)`,
+:any:`notmuch-count(1)`,
+:any:`notmuch-dump(1)`,
+:any:`notmuch-hooks(5)`,
+:any:`notmuch-insert(1)`,
+:any:`notmuch-new(1)`,
+:any:`notmuch-reply(1)`,
+:any:`notmuch-restore(1)`,
+:any:`notmuch-search-terms(7)`,
+:any:`notmuch-show(1)`,
+:any:`notmuch-tag(1)`