From: David Bremner Date: Mon, 19 Dec 2011 02:38:24 +0000 (-0400) Subject: initial splitting of notmuch.1 X-Git-Tag: debian/0.12_rc1-1~252 X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=c48797b498ba8dc46fb323a8a7f2cde4d41d3123;p=notmuch.git 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. --- 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) diff --git a/notmuch.1 b/notmuch.1 deleted file mode 100644 index 3dbd67e1..00000000 --- a/notmuch.1 +++ /dev/null @@ -1,776 +0,0 @@ -.\" 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 - -The -.B new -command is used to incorporate new mail into the notmuch database. -.RS 4 -.TP 4 -.BR new " [options...]" - -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 - -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. -.RS 4 -.TP 4 -.BR search " [options...] ..." - -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 -.TP -.BR show " [options...] ..." - -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 -.TP 4 -.BR count " [options...] ..." - -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 - -The -.B reply -command is useful for preparing a template for an email reply. -.RS 4 -.TP 4 -.BR reply " [options...] ..." - -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 - -The -.B tag -command is the only command available for manipulating database -contents. - -.RS 4 -.TP 4 -.BR tag " +|\- [...] [\-\-] ..." - -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 - -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. - -.RS 4 -.TP 4 -.BR dump " [] [--] []" - -Creates a plain-text dump of the tags of each message. - -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. - -See the -.B "SEARCH SYNTAX" -section below for details of the supported syntax for . -.RE - -.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 - -The -.B part -command can used to output a single part of a multipart MIME message. - -.RS 4 -.TP 4 -.BR part " \-\-part= ..." - -Output a single MIME part of a 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 - -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 - -.SH SEARCH SYNTAX -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) -.SH HOOKS -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 -.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).