X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=manpages%2Fnotmuch-search-1.mdwn;h=e8b6c279d39d364d44f8556352293b1b90f2e058;hb=ad04c8c6b3d8c29a905d9f5f92256fc2bd64be5e;hp=af5fe518573c7e1ccd93eeae6be987eac05eac05;hpb=e9e606f333685696ecc9979b8813b0838b9e969e;p=obsolete%2Fnotmuch-wiki diff --git a/manpages/notmuch-search-1.mdwn b/manpages/notmuch-search-1.mdwn index af5fe51..e8b6c27 100644 --- a/manpages/notmuch-search-1.mdwn +++ b/manpages/notmuch-search-1.mdwn @@ -2,7 +2,7 @@

NAME

-       notmuch-search - Search for messages matching the given search terms.
+       notmuch-search - search for messages matching the given search terms

SYNOPSIS

@@ -26,82 +26,122 @@ 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 (new- + 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

+
+       This command supports the following special exit status codes
+
+       20     The requested format version is too old.
 
-               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.
+       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)
+       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