mirror of
https://git.notmuchmail.org/git/notmuch
synced 2024-11-22 19:08:09 +01:00
ea0e75702d
Highlight "excluded messages" as a term with a meaning that may not be obvious. Be explicit about the effects of search --exclude=true and --exclude=false.
172 lines
4.6 KiB
Groff
172 lines
4.6 KiB
Groff
.TH NOTMUCH-SEARCH 1 2013-02-17 "Notmuch 0.15.2"
|
|
.SH NAME
|
|
notmuch-search \- search for messages matching the given search terms
|
|
.SH SYNOPSIS
|
|
|
|
.B notmuch search
|
|
.RI [ options "...] <" search-term ">..."
|
|
|
|
.SH 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.
|
|
|
|
See \fBnotmuch-search-terms\fR(7)
|
|
for details of the supported syntax for <search-terms>.
|
|
|
|
Supported options for
|
|
.B search
|
|
include
|
|
.RS 4
|
|
.TP 4
|
|
.BR \-\-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 \fBxargs\fR(1) -0 option where available).
|
|
.RE
|
|
|
|
.RS 4
|
|
.TP 4
|
|
.BR \-\-format-version=N
|
|
|
|
Use the specified structured output format version. This is intended
|
|
for programs that invoke \fBnotmuch\fR(1) internally. If omitted, the
|
|
latest supported version will be used.
|
|
.RE
|
|
|
|
.RS 4
|
|
.TP 4
|
|
.B \-\-output=(summary|threads|messages|files|tags)
|
|
|
|
.RS 4
|
|
.TP 4
|
|
.B 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.
|
|
.RE
|
|
.RS 4
|
|
.TP 4
|
|
.B 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).
|
|
.RE
|
|
.RS 4
|
|
.TP 4
|
|
.B 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).
|
|
.RE
|
|
.RS 4
|
|
.TP 4
|
|
.B 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).
|
|
.RE
|
|
.RS 4
|
|
.TP 4
|
|
.B 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).
|
|
.RE
|
|
.RE
|
|
|
|
.RS 4
|
|
.TP 4
|
|
.BR \-\-sort= ( newest\-first | oldest\-first )
|
|
|
|
This option can be used to present results in either chronological order
|
|
.RB ( oldest\-first )
|
|
or reverse chronological order
|
|
.RB ( newest\-first ).
|
|
|
|
Note: The thread order will be distinct between these two options
|
|
(beyond being simply reversed). When sorting by
|
|
.B oldest\-first
|
|
the threads will be sorted by the oldest message in each thread, but
|
|
when sorting by
|
|
.B 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).
|
|
.RE
|
|
|
|
.RS 4
|
|
.TP 4
|
|
.BR \-\-offset=[\-]N
|
|
|
|
Skip displaying the first N results. With the leading '\-', start at the Nth
|
|
result from the end.
|
|
.RE
|
|
|
|
.RS 4
|
|
.TP 4
|
|
.BR \-\-limit=N
|
|
|
|
Limit the number of displayed results to N.
|
|
.RE
|
|
|
|
.RS 4
|
|
.TP 4
|
|
.BR \-\-exclude=(true|false|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,
|
|
.BR true ,
|
|
prevents excluded messages from matching the search terms.
|
|
|
|
.B false
|
|
allows excluded messages to match search terms and appear in displayed
|
|
results. Excluded messages are still marked in the relevant outputs.
|
|
|
|
.B flag
|
|
only has an effect when
|
|
.B --output=summary
|
|
In this case all matching threads are returned but the "match count"
|
|
is the number of matching non-excluded messages in the thread.
|
|
.RE
|
|
|
|
.SH EXIT STATUS
|
|
|
|
This command supports the following special exit status codes
|
|
|
|
.TP
|
|
.B 20
|
|
The requested format version is too old.
|
|
.TP
|
|
.B 21
|
|
The requested format version is too new.
|
|
|
|
.SH SEE ALSO
|
|
|
|
\fBnotmuch\fR(1), \fBnotmuch-config\fR(1), \fBnotmuch-count\fR(1),
|
|
\fBnotmuch-dump\fR(1), \fBnotmuch-hooks\fR(5), \fBnotmuch-new\fR(1),
|
|
\fBnotmuch-reply\fR(1), \fBnotmuch-restore\fR(1),
|
|
\fBnotmuch-search-terms\fR(7), \fBnotmuch-show\fR(1),
|
|
\fBnotmuch-tag\fR(1)
|