From c48797b498ba8dc46fb323a8a7f2cde4d41d3123 Mon Sep 17 00:00:00 2001 From: David Bremner Date: Sun, 18 Dec 2011 22:38:24 -0400 Subject: initial splitting of notmuch.1 We mostly just cut and paste the command descriptions into individual files, with a short header added to each one. The splitting into subdirectories is to support the use of ./man as an element in MANPATH, e.g. for testing. --- man/man1/notmuch-config.1 | 51 +++++++++++++++ man/man1/notmuch-count.1 | 39 +++++++++++ man/man1/notmuch-dump.1 | 57 ++++++++++++++++ man/man1/notmuch-new.1 | 59 +++++++++++++++++ man/man1/notmuch-part.1 | 28 ++++++++ man/man1/notmuch-reply.1 | 60 +++++++++++++++++ man/man1/notmuch-search.1 | 116 +++++++++++++++++++++++++++++++++ man/man1/notmuch-show.1 | 140 ++++++++++++++++++++++++++++++++++++++++ man/man1/notmuch-tag.1 | 26 ++++++++ man/man1/notmuch.1 | 136 ++++++++++++++++++++++++++++++++++++++ man/man5/notmuch-hooks.5 | 40 ++++++++++++ man/man7/notmuch-search-terms.7 | 137 +++++++++++++++++++++++++++++++++++++++ 12 files changed, 889 insertions(+) create mode 100644 man/man1/notmuch-config.1 create mode 100644 man/man1/notmuch-count.1 create mode 100644 man/man1/notmuch-dump.1 create mode 100644 man/man1/notmuch-new.1 create mode 100644 man/man1/notmuch-part.1 create mode 100644 man/man1/notmuch-reply.1 create mode 100644 man/man1/notmuch-search.1 create mode 100644 man/man1/notmuch-show.1 create mode 100644 man/man1/notmuch-tag.1 create mode 100644 man/man1/notmuch.1 create mode 100644 man/man5/notmuch-hooks.5 create mode 100644 man/man7/notmuch-search-terms.7 (limited to 'man') diff --git a/man/man1/notmuch-config.1 b/man/man1/notmuch-config.1 new file mode 100644 index 00000000..20389f7c --- /dev/null +++ b/man/man1/notmuch-config.1 @@ -0,0 +1,51 @@ +.TH NOTMUCH-CONFIG 1 2011-12-04 "Notmuch 0.10.2" +.SH NAME +notmuch-config \- Output a single part of a multipart MIME message. +.SH SYNOPSIS + +.B notmuch config get +.RI "<" section "> . <" item ">" + +.B notmuch config set +.RI "<" section "> . <" item "> [" value "]" + +.SH DESCRIPTION + +The +.B config +command can be used to get or set settings int the notmuch +configuration file. + + +.RS 4 +.TP 4 +.BR "config get "
. + +The value of the specified configuration item is printed to stdout. If +the item has multiple values, each value is separated by a newline +character. + +Available configuration items include at least + + database.path + + user.name + + user.primary_email + + user.other_email + + new.tags +.RE + +.RS 4 +.TP 4 +.BR "config set "
. " [values ...]" + +The specified configuration item is set to the given value. To +specify a multiple-value item, provide each value as a separate +command-line argument. + +If no values are provided, the specified configuration item will be +removed from the configuration file. +.RE diff --git a/man/man1/notmuch-count.1 b/man/man1/notmuch-count.1 new file mode 100644 index 00000000..c0478393 --- /dev/null +++ b/man/man1/notmuch-count.1 @@ -0,0 +1,39 @@ +.TH NOTMUCH-COUNT 1 2011-12-04 "Notmuch 0.10.2" +.SH NAME +notmuch-count \- Count messages matching the given search terms. +.SH SYNOPSIS + +.B notmuch count +.RI [ options "... ] <" search-term ">..." + +.SH DESCRIPTION + +Count messages matching the search terms. + +The number of matching messages (or threads) is output to stdout. + +With no search terms, a count of all messages (or threads) in the database will +be displayed. + +Supported options for +.B count +include +.RS 4 +.TP 4 +.B \-\-output=(messages|threads) + +.RS 4 +.TP 4 +.B messages + +Output the number of matching messages. This is the default. +.RE +.RS 4 +.TP 4 +.B threads + +Output the number of matching threads. +.RE +.RE +.RE +.RE diff --git a/man/man1/notmuch-dump.1 b/man/man1/notmuch-dump.1 new file mode 100644 index 00000000..9dc311f6 --- /dev/null +++ b/man/man1/notmuch-dump.1 @@ -0,0 +1,57 @@ +.TH NOTMUCH-DUMP 1 2011-12-04 "Notmuch 0.10.2" +.SH NAME +notmuch-dump \- Creates a plain-text dump of the tags of each message. + +.SH SYNOPSIS + +.B "notmuch dump" +.RI "[ <" filename "> ] [--]" +.RI "[ <" search-term ">...]" + +.B "notmuch restore" +.RB [ "--accumulate" ] +.RI "[ <" filename "> ]" + +.SH DESCRIPTION + +.TP +.BR dump " []" + +Dump tags for messages matching the given search terms. + +Output is to the given filename, if any, or to stdout. Note that +using the filename argument is deprecated. + +These tags are the only data in the notmuch database that can't be +recreated from the messages themselves. The output of notmuch dump is +therefore the only critical thing to backup (and much more friendly to +incremental backup than the native database files.) + +With no search terms, a dump of all messages in the database will be +generated. A "--" argument instructs notmuch that the +remaining arguments are search terms. + +.TP +.BR restore " [--accumulate] []" + +Restores the tags from the given file (see +.BR "notmuch dump" ")." + +The input is read from the given filename, if any, or from stdin. + +Note: The dump file format is specifically chosen to be +compatible with the format of files produced by sup-dump. +So if you've previously been using sup for mail, then the +.B "notmuch restore" +command provides you a way to import all of your tags (or labels as +sup calls them). + +The --accumulate switch causes the union of the existing and new tags to be +applied, instead of replacing each message's tags as they are read in from the +dump file. +.RE + +See the +.B "SEARCH SYNTAX" +section below for details of the supported syntax for . +.RE diff --git a/man/man1/notmuch-new.1 b/man/man1/notmuch-new.1 new file mode 100644 index 00000000..9c11375e --- /dev/null +++ b/man/man1/notmuch-new.1 @@ -0,0 +1,59 @@ +.TH NOTMUCH-NEW 1 2011-12-04 "Notmuch 0.10.2" +.SH NAME +notmuch-new \- Incorporate new mail into the notmuch database. +.SH SYNOPSIS + +.B notmuch new +.RB "[" --no-hooks "]" + +.SH DESCRIPTION + +Find and import any new messages to the database. + +The +.B new +command scans all sub-directories of the database, performing +full-text indexing on new messages that are found. Each new message +will automatically be tagged with both the +.BR inbox " and " unread +tags. + +You should run +.B "notmuch new" +once after first running +.B "notmuch setup" +to create the initial database. The first run may take a long time if +you have a significant amount of mail (several hundred thousand +messages or more). Subsequently, you should run +.B "notmuch new" +whenever new mail is delivered and you wish to incorporate it into the +database. These subsequent runs will be much quicker than the initial +run. + +Invoking +.B notmuch +with no command argument will run +.B new +if +.B "notmuch setup" +has previously been completed, but +.B "notmuch new" +has not previously been run. + + +The +.B new +command supports hooks. See the +.B "HOOKS" +section below for more details on hooks. + +Supported options for +.B new +include +.RS 4 +.TP 4 +.BR \-\-no\-hooks + +Prevents hooks from being run. +.RE +.RE diff --git a/man/man1/notmuch-part.1 b/man/man1/notmuch-part.1 new file mode 100644 index 00000000..67c4b5ed --- /dev/null +++ b/man/man1/notmuch-part.1 @@ -0,0 +1,28 @@ +.TH NOTMUCH-PART 1 2011-12-04 "Notmuch 0.10.2" +.SH NAME +notmuch-part \- Output a single part of a multipart MIME message. +.SH SYNOPSIS + +.B notmuch part +.BI "\-\-part=" "" +.RI < search-terms > + +.SH DESCRIPTION + +The +.B part +command can used to output a single part of a multipart MIME message. + +A single decoded MIME part, with no encoding or framing, is output to +stdout. The search terms must match only a single message, otherwise +this command will fail. + +The part number should match the part "id" field output by the +"\-\-format=json" option of "notmuch show". If the message specified by +the search terms does not include a part with the specified "id" there +will be no output. + +See the +.B "SEARCH SYNTAX" +section below for details of the supported syntax for . +.RE diff --git a/man/man1/notmuch-reply.1 b/man/man1/notmuch-reply.1 new file mode 100644 index 00000000..eb23925b --- /dev/null +++ b/man/man1/notmuch-reply.1 @@ -0,0 +1,60 @@ +.TH NOTMUCH-REPLY 1 2011-12-04 "Notmuch 0.10.2" +.SH NAME +notmuch-reply \- Constructs a reply template for a set of messages. + +.SH SYNOPSIS + +.B notmuch reply +.RI "[" options "...] <" search-term ">..." + +.SH DESCRIPTION + +Constructs a reply template for a set of messages. + +To make replying to email easier, +.B notmuch reply +takes an existing set of messages and constructs a suitable mail +template. The Reply-to header (if any, otherwise From:) is used for +the To: address. Vales from the To: and Cc: headers are copied, but +not including any of the current user's email addresses (as configured +in primary_mail or other_email in the .notmuch\-config file) in the +recipient list + +It also builds a suitable new subject, including Re: at the front (if +not already present), and adding the message IDs of the messages being +replied to to the References list and setting the In\-Reply\-To: field +correctly. + +Finally, the original contents of the emails are quoted by prefixing +each line with '> ' and included in the body. + +The resulting message template is output to stdout. + +Supported options for +.B reply +include +.RS +.TP 4 +.BR \-\-format= ( default | headers\-only ) +.RS +.TP 4 +.BR default +Includes subject and quoted message body. +.TP +.BR headers\-only +Only produces In\-Reply\-To, References, To, Cc, and Bcc headers. +.RE + +See the +.B "SEARCH SYNTAX" +section below for details of the supported syntax for . + +Note: It is most common to use +.B "notmuch reply" +with a search string matching a single message, (such as +id:), but it can be useful to reply to several messages at +once. For example, when a series of patches are sent in a single +thread, replying to the entire thread allows for the reply to comment +on issue found in multiple patches. +.RE +.RE diff --git a/man/man1/notmuch-search.1 b/man/man1/notmuch-search.1 new file mode 100644 index 00000000..efb63a1c --- /dev/null +++ b/man/man1/notmuch-search.1 @@ -0,0 +1,116 @@ +.TH NOTMUCH-SEARCH 1 2011-12-04 "Notmuch 0.10.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. + +Supported options for +.B search +include +.RS 4 +.TP 4 +.BR \-\-format= ( json | text ) + +Presents the results in either JSON or plain-text (default). +.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) or as a JSON array +(\-\-format=json). +.RE +.RS 4 +.TP 4 +.B 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). +.RE +.RS 4 +.TP 4 +.B files + +Output the filenames of all messages matching the search terms, either +one per line (\-\-format=text) or as a JSON array (\-\-format=json). +.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) or as a JSON array +(\-\-format=json). +.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 +See the +.B "SEARCH SYNTAX" +section below for details of the supported syntax for . +.RE diff --git a/man/man1/notmuch-show.1 b/man/man1/notmuch-show.1 new file mode 100644 index 00000000..701186ee --- /dev/null +++ b/man/man1/notmuch-show.1 @@ -0,0 +1,140 @@ +.TH NOTMUCH-SHOW 1 2011-12-04 "Notmuch 0.10.2" +.SH NAME +notmuch-show \- Show messages matching the given search terms. +.SH SYNOPSIS + +.B notmuch show +.RI "[" options "...] <" search-term ">..." + +.SH DESCRIPTION + +Shows all messages matching the search terms. + +The messages will be grouped and sorted based on the threading (all +replies to a particular message will appear immediately after that +message in date order). The output is not indented by default, but +depth tags are printed so that proper indentation can be performed by +a post-processor (such as the emacs interface to notmuch). + +Supported options for +.B show +include +.RS 4 +.TP 4 +.B \-\-entire\-thread + +By default only those messages that match the search terms will be +displayed. With this option, all messages in the same thread as any +matched message will be displayed. +.RE + +.RS 4 +.TP 4 +.B \-\-format=(text|json|mbox|raw) + +.RS 4 +.TP 4 +.BR text " (default for messages)" + +The default plain-text format has all text-content MIME parts +decoded. Various components in the output, +.RB ( message ", " header ", " body ", " attachment ", and MIME " part ), +will be delimited by easily-parsed markers. Each marker consists of a +Control-L character (ASCII decimal 12), the name of the marker, and +then either an opening or closing brace, ('{' or '}'), to either open +or close the component. For a multipart MIME message, these parts will +be nested. +.RE +.RS 4 +.TP 4 +.B json + +The output is formatted with Javascript Object Notation (JSON). This +format is more robust than the text format for automated +processing. The nested structure of multipart MIME messages is +reflected in nested JSON output. JSON output always includes all +messages in a matching thread; in effect +.B \-\-format=json +implies +.B \-\-entire\-thread + +.RE +.RS 4 +.TP 4 +.B mbox + +All matching messages are output in the traditional, Unix mbox format +with each message being prefixed by a line beginning with "From " and +a blank line separating each message. Lines in the message content +beginning with "From " (preceded by zero or more '>' characters) have +an additional '>' character added. This reversible escaping +is termed "mboxrd" format and described in detail here: + +.nf +.nh +http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/mail-mbox-formats.html +.hy +.fi +. +.RE +.RS 4 +.TP 4 +.BR raw " (default for a single part, see \-\-part)" + +For a message, the original, raw content of the email message is +output. Consumers of this format should expect to implement MIME +decoding and similar functions. + +For a single part (\-\-part) the raw part content is output after +performing any necessary MIME decoding. + +The raw format must only be used with search terms matching single +message. +.RE +.RE + +.RS 4 +.TP 4 +.B \-\-part=N + +Output the single decoded MIME part N of a single message. The search +terms must match only a single message. Message parts are numbered in +a depth-first walk of the message MIME structure, and are identified +in the 'json' or 'text' output formats. +.RE + +.RS 4 +.TP 4 +.B \-\-verify + +Compute and report the validity of any MIME cryptographic signatures +found in the selected content (ie. "multipart/signed" parts). Status +of the signature will be reported (currently only supported with +--format=json), and the multipart/signed part will be replaced by the +signed data. +.RE + +.RS 4 +.TP 4 +.B \-\-decrypt + +Decrypt any MIME encrypted parts found in the selected content +(ie. "multipart/encrypted" parts). Status of the decryption will be +reported (currently only supported with --format=json) and the +multipart/encrypted part will be replaced by the decrypted +content. +.RE + +A common use of +.B notmuch show +is to display a single thread of email messages. For this, use a +search term of "thread:" as can be seen in the first +column of output from the +.B notmuch search +command. + +See the +.B "SEARCH SYNTAX" +section below for details of the supported syntax for . +.RE +.RS 4 diff --git a/man/man1/notmuch-tag.1 b/man/man1/notmuch-tag.1 new file mode 100644 index 00000000..a0082f9b --- /dev/null +++ b/man/man1/notmuch-tag.1 @@ -0,0 +1,26 @@ +.TH NOTMUCH-TAG 1 2011-12-04 "Notmuch 0.10.2" +.SH NAME +notmuch-tag \- Add/remove tags for all messages matching the search terms. + +.SH SYNOPSIS +.B notmuch tag +.RI "+<" tag> "|\-<" tag "> [...] [\-\-] <" search-term ">..." + +.SH DESCRIPTION + +Add/remove tags for all messages matching the search terms. + +Tags prefixed by '+' are added while those prefixed by '\-' are +removed. For each message, tag removal is performed before tag +addition. + +The beginning of is recognized by the first +argument that begins with neither '+' nor '\-'. Support for +an initial search term beginning with '+' or '\-' is provided +by allowing the user to specify a "\-\-" argument to separate +the tags from the search terms. + +See the +.B "SEARCH SYNTAX" +section below for details of the supported syntax for . +.RE diff --git a/man/man1/notmuch.1 b/man/man1/notmuch.1 new file mode 100644 index 00000000..74f892e8 --- /dev/null +++ b/man/man1/notmuch.1 @@ -0,0 +1,136 @@ +.\" notmuch - Not much of an email program, (just index, search and tagging) +.\" +.\" Copyright © 2009 Carl Worth +.\" +.\" Notmuch is free software: you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation, either version 3 of the License, or +.\" (at your option) any later version. +.\" +.\" Notmuch is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program. If not, see http://www.gnu.org/licenses/ . +.\" +.\" Author: Carl Worth +.TH NOTMUCH 1 2011-12-04 "Notmuch 0.10.2" +.SH NAME +notmuch \- thread-based email index, search, and tagging +.SH SYNOPSIS +.B notmuch +.IR command " [" args " ...]" +.SH DESCRIPTION +Notmuch is a command-line based program for indexing, searching, +reading, and tagging large collections of email messages. + +The quickest way to get started with Notmuch is to simply invoke the +.B notmuch +command with no arguments, which will interactively guide you through +the process of indexing your mail. +.SH NOTE +While the command-line program +.B notmuch +provides powerful functionality, it does not provide the most +convenient interface for that functionality. More sophisticated +interfaces are expected to be built on top of either the command-line +interface, or more likely, on top of the notmuch library +interface. See http://notmuchmail.org for more about alternate +interfaces to notmuch. +.SH COMMANDS +The +.BR setup +command is used to configure Notmuch for first use, (or to reconfigure +it later). +.RS 4 +.TP 4 +.B setup + +Interactively sets up notmuch for first use. + +The setup command will prompt for your full name, your primary email +address, any alternate email addresses you use, and the directory +containing your email archives. Your answers will be written to a +configuration file in ${NOTMUCH_CONFIG} (if set) or +${HOME}/.notmuch-config . This configuration file will be created with +descriptive comments, making it easy to edit by hand later to change the +configuration. Or you can run +.B "notmuch setup" +again to change the configuration. + +The mail directory you specify can contain any number of +sub-directories and should primarily contain only files with individual +email messages (eg. maildir or mh archives are perfect). If there are +other, non-email files (such as indexes maintained by other email +programs) then notmuch will do its best to detect those and ignore +them. + +Mail storage that uses mbox format, (where one mbox file contains many +messages), will not work with notmuch. If that's how your mail is +currently stored, it is recommended you first convert it to maildir +format with a utility such as mb2md before running +.B "notmuch setup" . + +Invoking +.B notmuch +with no command argument will run +.B setup +if the setup command has not previously been completed. +.RE + + + +Several of the notmuch commands accept search terms with a common +syntax. See the +.B "SEARCH SYNTAX" +section below for more details on the supported syntax. + +The +.BR search ", " show " and " count +commands are used to query the email database. + + +The +.B reply +command is useful for preparing a template for an email reply. +.RS 4 + +The +.B tag +command is the only command available for manipulating database +contents. + + +The +.BR dump " and " restore +commands can be used to create a textual dump of email tags for backup +purposes, and to restore from that dump. + +The +.B config +command can be used to get or set settings int the notmuch +configuration file. + +.SH ENVIRONMENT +The following environment variables can be used to control the +behavior of notmuch. +.TP +.B NOTMUCH_CONFIG +Specifies the location of the notmuch configuration file. Notmuch will +use ${HOME}/.notmuch\-config if this variable is not set. +.SH SEE ALSO +The emacs-based interface to notmuch (available as +.B notmuch.el +in the Notmuch distribution). + +The notmuch website: +.B http://notmuchmail.org +.SH CONTACT +Feel free to send questions, comments, or kudos to the notmuch mailing +list . Subscription is not required before +posting, but is available from the notmuchmail.org website. + +Real-time interaction with the Notmuch community is available via IRC +(server: irc.freenode.net, channel: #notmuch). diff --git a/man/man5/notmuch-hooks.5 b/man/man5/notmuch-hooks.5 new file mode 100644 index 00000000..8b66425e --- /dev/null +++ b/man/man5/notmuch-hooks.5 @@ -0,0 +1,40 @@ +.TH NOTMUCH-HOOKS 5 2011-12-04 "Notmuch 0.10.2" + +.SH NAME +notmuch-hooks \- hooks for notmuch + +.SH SYNOPSIS + $DATABASEDIR/.notmuch/hooks/* + +.SH DESCRIPTION +Hooks are scripts (or arbitrary executables or symlinks to such) that notmuch +invokes before and after certain actions. These scripts reside in +the .notmuch/hooks directory within the database directory and must have +executable permissions. + +The currently available hooks are described below. +.RS 4 +.TP 4 +.B pre\-new +This hook is invoked by the +.B new +command before scanning or importing new messages into the database. If this +hook exits with a non-zero status, notmuch will abort further processing of the +.B new +command. + +Typically this hook is used for fetching or delivering new mail to be imported +into the database. +.RE +.RS 4 +.TP 4 +.B post\-new +This hook is invoked by the +.B new +command after new messages have been imported into the database and initial tags +have been applied. The hook will not be run if there have been any errors during +the scan or import. + +Typically this hook is used to perform additional query\-based tagging on the +imported messages. +.RE diff --git a/man/man7/notmuch-search-terms.7 b/man/man7/notmuch-search-terms.7 new file mode 100644 index 00000000..ba8b873e --- /dev/null +++ b/man/man7/notmuch-search-terms.7 @@ -0,0 +1,137 @@ +.TH NOTMUCH-SEARCH-TERMS 7 2011-12-04 "Notmuch 0.10.2" + +.SH NAME +notmuch-search-terms \- Syntax for notmuch queries + +.SH SYNOPSIS + +.B notmuch count +.RI [ options... ] +.RI < search-term ">..." + +.B "notmuch dump" +.RI "[ <" filename "> ] [--]" +.RI "[ <" search-term ">...]" + +.B notmuch part +.BI "\-\-part=" "" +.RI < search-term ">..." + +.B notmuch search +.RI [ options "...] <" search-term ">..." + +.B notmuch show +.RI "[" options "...] <" search-term ">..." + +.B notmuch tag +.RI "+<" tag> "|\-<" tag "> [...] [\-\-] <" search-term ">..." + + +.SH DESCRIPTION +Several notmuch commands accept a common syntax for search terms. + +The search terms can consist of free-form text (and quoted phrases) +which will match all messages that contain all of the given +terms/phrases in the body, the subject, or any of the sender or +recipient headers. + +As a special case, a search string consisting of exactly a single +asterisk ("*") will match all messages. + +In addition to free text, the following prefixes can be used to force +terms to match against specific portions of an email, (where + indicate user-supplied values): + + from: + + to: + + subject: + + attachment: + + tag: (or is:) + + id: + + thread: + + folder: + +The +.B from: +prefix is used to match the name or address of the sender of an email +message. + +The +.B to: +prefix is used to match the names or addresses of any recipient of an +email message, (whether To, Cc, or Bcc). + +Any term prefixed with +.B subject: +will match only text from the subject of an email. Searching for a +phrase in the subject is supported by including quotation marks around +the phrase, immediately following +.BR subject: . + +The +.B attachment: +prefix can be used to search for specific filenames (or extensions) of +attachments to email messages. + +For +.BR tag: " and " is: +valid tag values include +.BR inbox " and " unread +by default for new messages added by +.B notmuch new +as well as any other tag values added manually with +.BR "notmuch tag" . + +For +.BR id: , +message ID values are the literal contents of the Message\-ID: header +of email messages, but without the '<', '>' delimiters. + +The +.B thread: +prefix can be used with the thread ID values that are generated +internally by notmuch (and do not appear in email messages). These +thread ID values can be seen in the first column of output from +.B "notmuch search" + +The +.B folder: +prefix can be used to search for email message files that are +contained within particular directories within the mail store. Only +the directory components below the top-level mail database path are +available to be searched. + +In addition to individual terms, multiple terms can be +combined with Boolean operators ( +.BR and ", " or ", " not +, etc.). Each term in the query will be implicitly connected by a +logical AND if no explicit operator is provided, (except that terms +with a common prefix will be implicitly combined with OR until we get +Xapian defect #402 fixed). + +Parentheses can also be used to control the combination of the Boolean +operators, but will have to be protected from interpretation by the +shell, (such as by putting quotation marks around any parenthesized +expression). + +Finally, results can be restricted to only messages within a +particular time range, (based on the Date: header) with a syntax of: + + .. + +Each timestamp is a number representing the number of seconds since +1970\-01\-01 00:00:00 UTC. This is not the most convenient means of +expressing date ranges, but until notmuch is fixed to accept a more +convenient form, one can use the date program to construct +timestamps. For example, with the bash shell the following syntax would +specify a date range to return messages from 2009\-10\-01 until the +current time: + + $(date +%s \-d 2009\-10\-01)..$(date +%s) -- cgit v1.2.3