X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=manpages%2Fnotmuch-search-1.mdwn;h=b3afd65360ab5571478023a7ad0b3da79e6b49f7;hb=0add150ffd941ea7ed64a9116929aaf2daa927a5;hp=5afb0f731022dcdfc7166d5bfd22a11e48c30aa0;hpb=0b22ed1b4e640539ae8e6f78f1ea88e54426a50d;p=notmuch-wiki diff --git a/manpages/notmuch-search-1.mdwn b/manpages/notmuch-search-1.mdwn index 5afb0f7..b3afd65 100644 --- a/manpages/notmuch-search-1.mdwn +++ b/manpages/notmuch-search-1.mdwn @@ -7,7 +7,7 @@

SYNOPSIS

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

DESCRIPTION

@@ -26,106 +26,158 @@ Supported options for search include - --format=(json|sexp|text|text0) + --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). + 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. + 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) + --output=(summary|threads|messages|files|tags) - summary + 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. + 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. - threads + 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). + 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 + 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 (--for- - mat=json), or as an S-Expression list (--format=sexp). + 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 + array (--format=json), or as an S-Expression list (--for- + mat=sexp). - files + 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). + 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). - tags + 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. - 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). + tags - --sort=(newest-first|oldest-first) + 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). - This option can be used to present results in either chronolog- - ical order (oldest-first) or reverse chronological order - (newest-first). + --sort=(newest-first|oldest-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 - be sorted by the newest message in each thread. + This option can be used to present results in either chrono- + logical order (oldest-first) or reverse chronological order + (newest-first). - By default, results will be displayed in reverse chronological - order, (that is, the newest results will be displayed 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 be sorted by the newest message in each thread. + + By default, results will be displayed in reverse chronologi- + cal 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. + 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. + 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 num- + ber of matching non-excluded messages in the thread, rather + than the number of matching messages. + + --duplicate=N - --exclude=(true|false|flag) + Effective with --output=files, output the Nth filename asso- + ciated 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. - 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. + 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.
+       20
 
-       21     The requested format version is too new.
+              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),  not-
+       much-tag(1)
+
+ +

AUTHOR

+
+       Carl Worth and many others
+
+ +

COPYRIGHT

+
+       2014, Carl Worth and many others
-

Notmuch 0.15

+

0.18