debian/notmuch
1
0
Fork 0
mirror of https://git.notmuchmail.org/git/notmuch synced 2024-12-04 16:38:14 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
notmuch/doc/man1/notmuch-search.rst

192 lines
6.5 KiB
ReStructuredText
Raw Permalink Normal View History

doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
.. _notmuch-search(1):
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
==============
notmuch-search
==============
SYNOPSIS
========
**notmuch** **search** [*option* ...] <*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 messages in the
thread, the names of all participants in the thread, and the subject of
the newest (or oldest) message.
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
See :any:`notmuch-search-terms(7)` for details of the supported syntax for
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
<search-terms>.
Supported options for **search** include
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
.. 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)
doc: mark `--output=summary` as default `notmuch search` behaves differently depending on the output option: It either outputs information pertaining to all threads with matching messages (summary, threads) or to all matching messages (messages, files, tags). The man page refres solely to the former in the main description. Help the user by clearly marking `summary` as the default output option. Signed-off-by: Michael J Gruber <git@grubix.eu>
2022-11-30 14:58:34 +01:00
summary (default)
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
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).
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
threads
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
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``).
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
messages
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
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``).
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
files
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
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.
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
tags
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
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.
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
true (default)
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
Prevent excluded messages from matching the search terms.
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
all
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
Additionally prevent excluded messages from appearing in
displayed results, in effect behaving as though the excluded
messages do not exist.
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
false
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
Allow excluded messages to match search terms and appear in
displayed results. Excluded messages are still marked in the
relevant outputs.
doc: remove explicit formatting of terms in definition lists Sphinx-doc already formats the terms appropriately for a given backend (bold in html and man). `makeinfo` complains noisily about formatting inside a @item if we add our own explicit formatting. This change may change the formatting in the info output. On the other hand, the existing use of quotes for bold is not that great anyway. In some places blank lines were removed to preserve the logical structure of a definition list.
2021-10-11 14:56:14 +02:00
flag
doc: use program and option directives to document options Use the program and option directives to document the subcommand options. This unifies a lot of option documentation throughout. This also makes it possible to reference options with :option:`--foo` (within .. program::) or :option:`subcommand --foo` (globally). This is left for later work. See https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program Note: There is a lot of indentation change, but intentionally there is no reflow. Using 'git diff -w' or 'git show -w' to ignore white space changes makes this a very easy change to review.
2021-05-21 22:44:12 +02:00
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.
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
cli/search: print total number of files matched in summary output. The structured output formats already have all of the filenames. This is an easy bit of UI change to make the multiple files visible.
2017-06-04 14:32:32 +02:00
EXAMPLE
=======
The following shows an example of the summary output format, with one
message having multiple filenames.
::
% notmuch search date:today.. and tag:bad-news
doc: fix notmuch-search example For some reason the searched tag did not match the displayed results.
2018-05-08 17:12:55 +02:00
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)
cli/search: print total number of files matched in summary output. The structured output formats already have all of the filenames. This is an easy bit of UI change to make the multiple files visible.
2017-06-04 14:32:32 +02:00
doc: convert sphinx based docs This is the output from sphinx-quickstart, massaged a bit, along with our existing man pages converted to rst. A skeleton notmuch-emacs manual is also included. It is not suitable for end user use yet.
2014-01-28 17:12:37 +01:00
EXIT STATUS
===========
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
========
doc: cross-reference notmuch man pages with actual links Add internal hyperlink targets for man pages and cross-reference them using the any role reference. There are a number of alternatives to accomplish this, but this seems like the combination that retains the man page section number and the same boldface style in the man pages. As a bonus, we get sanity checking on the links; for example notmuch-search-terms.rst had a reference to notmuch-properties(1) i.e. the wrong section. The obvious semantic follow-up change would be to only have meaningful "see also" references instead of having them all everywhere.
2021-05-21 22:44:10 +02:00
: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)`
Reference in a new issue Copy permalink