X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=manpages%2Fnotmuch-search-1.mdwn;h=e8b6c279d39d364d44f8556352293b1b90f2e058;hb=ad04c8c6b3d8c29a905d9f5f92256fc2bd64be5e;hp=88d9fbd77f49fd11927bcdbae4bbc8633ed52627;hpb=33b367e699bbcc8fecd001fab8033a4e91b13450;p=obsolete%2Fnotmuch-wiki
diff --git a/manpages/notmuch-search-1.mdwn b/manpages/notmuch-search-1.mdwn
index 88d9fbd..e8b6c27 100644
--- a/manpages/notmuch-search-1.mdwn
+++ b/manpages/notmuch-search-1.mdwn
@@ -1,163 +1,147 @@
NOTMUCH-SEARCH(1)
NAME
-
- notmuch-search - Search for messages matching the given search terms.
+ notmuch-search - search for messages matching the given search terms
SYNOPSIS
-
- notmuch search [options...] <search-term>...
+ 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 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
- .
-
+ See notmuch-search-terms(7) for details of the supported syntax for
+ <search-terms>.
-
Supported options for search include
-
-
- --format=(json|text)
-
+ --format=(json|sexp|text|text0)
-
- Presents the results in either JSON or plain-text (default).
-
+ 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
+ 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
+ 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 (--for-
- mat=text) or as a JSON array (--format=json).
-
+ 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) or as a JSON
- array (--format=json).
-
+ 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 (--for-
+ mat=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) or as a JSON
- array (--format=json).
-
+ 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).
-
tags
-
-
- Output all tags that appear on any message matching the
- search terms, either one per line (--format=text) or as a
- JSON array (--format=json).
-
+ 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 array
+ (--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 chronolog-
- ical order (oldest-first) or reverse chronological order
- (newest-first).
-
+ ical order (oldest-first) or reverse chronological order (new-
+ est-first).
-
- Note: The thread order will be distinct between these two
- options (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
+ Note: The thread order will be distinct between these two
+ options (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
+ 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 '-',
+ 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|flag)
+ --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 match-
+ ing 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.
+EXIT STATUS
- Specify whether to omit messages matching search.tag_exclude
- from the search results (the default) or not. The extra option
- flag only has an effect when --output=summary In this case all
- matching threads are returned but the "match count" is the num-
- ber of matching non-excluded messages in the thread.
+ 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-new(1), notmuch-reply(1), notmuch-restore(1),
- notmuch-search-terms(7), notmuch-show(1), notmuch-tag(1)
+ 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), notmuch-
+ tag(1)
-Notmuch 0.13.2
+Notmuch 0.16