X-Git-Url: https://git.notmuchmail.org/git?p=notmuch;a=blobdiff_plain;f=doc%2Fman1%2Fnotmuch-search.rst;h=ed9ff4e5b96522751b056192bb7eabc5b0da75dd;hp=67c1ce904c0152d22a53b9b46ace5c6df67df84f;hb=HEAD;hpb=7ac96b149f5a0e5c03b64856d7c20789dab3c628 diff --git a/doc/man1/notmuch-search.rst b/doc/man1/notmuch-search.rst index 67c1ce90..b87737ea 100644 --- a/doc/man1/notmuch-search.rst +++ b/doc/man1/notmuch-search.rst @@ -1,3 +1,5 @@ +.. _notmuch-search(1): + ============== notmuch-search ============== @@ -19,123 +21,133 @@ 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 +See :any:`notmuch-search-terms(7)` for details of the supported syntax for . 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. In the case where a thread contains multiple files for - some messages, the total number of files is printed in parentheses - (see below for an example). - - **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). 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 these files alone would not match the - search. - - **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`` - For ``--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. - - For ``--output=messages``, only output message IDs of messages - matching the search terms that have at least N filenames - associated with them. - - 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. +.. program:: search + +.. option:: --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 :manpage:`xargs(1)` -0 + option where available). + +.. option:: --format-version=N + + Use the specified structured output format version. This is + intended for programs that invoke :any:`notmuch(1)` internally. If + omitted, the latest supported version will be used. + +.. option:: --output=(summary|threads|messages|files|tags) + + summary (default) + 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. In the case where a thread contains multiple files + for some messages, the total number of files is printed in + parentheses (see below for an example). + + 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). 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 + these files alone would not match the search. + + 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``). + +.. option:: --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). + +.. option:: --offset=[-]N + + Skip displaying the first N results. With the leading '-', start + at the Nth result from the end. + +.. option:: --limit=N + + Limit the number of displayed results to N. + +.. option:: --exclude=(true|false|all|flag) + + A message is called "excluded" if it matches at least one tag in + search.exclude\_tags that does not appear explicitly in the search + terms. This option specifies whether to omit excluded messages in + the search process. + + true (default) + Prevent excluded messages from matching the search terms. + + all + Additionally prevent excluded messages from appearing in + displayed results, in effect behaving as though the excluded + messages do not exist. + + false + Allow 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. + +.. option:: --duplicate=N + + For ``--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. + + For ``--output=messages``, only output message IDs of messages + matching the search terms that have at least N filenames + associated with them. + + 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. EXAMPLE ======= @@ -146,9 +158,9 @@ message having multiple filenames. :: % notmuch search date:today.. and tag:bad-news - thread:0000000000063c10 Today [1/1] Some Persun; To the bone (inbox unread) - thread:0000000000063c25 Today [1/1(2)] Ann Other; Bears (inbox unread) - thread:0000000000063c00 Today [1/1] A Thurd; Bites, stings, sad feelings (inbox unread) + thread:0000000000063c10 Today [1/1] Some Persun; To the bone (bad-news inbox unread) + thread:0000000000063c25 Today [1/1(2)] Ann Other; Bears (bad-news inbox unread) + thread:0000000000063c00 Today [1/1] A Thurd; Bites, stings, sad feelings (bad-news unread) EXIT STATUS =========== @@ -164,16 +176,16 @@ This command supports the following special exit status codes 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)`