From: David Bremner <brem...@unb.ca> Some places I deleted a bit of the continuity text introducing a command because I didn't see how to make it work with the slightly more structured layout.
I also moved show in front of search, because it explains the output formats. Probably it would make sense to add a separate section explaining common output formats. --- You can take a look at the HTML output at http://pivot.cs.unb.ca/scratch/notmuch.html We can also generate man pages and inline help from this file. I didn't get that far yet, waiting for more encouraging noises :). notmuch.pod | 361 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 361 insertions(+), 0 deletions(-) create mode 100644 notmuch.pod diff --git a/notmuch.pod b/notmuch.pod new file mode 100644 index 0000000..719dead --- /dev/null +++ b/notmuch.pod @@ -0,0 +1,361 @@ +=head1 Name + +notmuch - thread-based email index, search, and tagging + +=head1 Synopsis + +=over + +=item B<notmuch> I<command> [I<args> ...] + +=back + +=head1 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. + +=head2 Using notmuch + +The B<search> and B<show> commands are used to query the email +database. The B<tag> command is the only command available for +manipulating database contents. 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. + +=head2 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 L<http://notmuchmail.org> for +more about alternate interfaces to notmuch. + +=head1 Commands + +=head2 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. + +=head2 new + +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 B<inbox> and B<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. + +=head2 show [options...] <search-term>... + +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 + +=over + +=item 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. + +=item B<--format=(json|text)> + +=over + +=item B<text> + +The default plain-text format has text-content MIME parts decoded. +Various components in the output, (B<message>, B<header>, B<body>, +B<attachment>, and MIME B<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. + +=item B<json> + +Format output as Javascript Object Notation (JSON). +JSON output always includes all messages in a matching thread; in effect +B<--format=json> implies B<--entire-thread>. + +=back + +=back + +A common use of B<notmuch show> is to display a single thread of +email messages. For this, use a search term of "thread:<thread-id>" 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 <search-terms>. + +=head2 search [options...] <search-term>... + +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 + +=over + +=item B<--format=>(B<json>|B<text>) + +Presents the results in either JSON or plain-text (default). + +=item B<--sort=>(B<newest-first>|B<oldest-first>) + +This option can be used to present results in either chronological +order (B<oldest-first>) or reverse chronological order +(B<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). + +=back + +See the B<SEARCH SYNTAX> section below for details of the supported +syntax for B<search-terms>. + +=head2 count <search-term>... + +Count messages matching the search terms. + +The number of matching messages is output to stdout. With no search +terms, a count of all messages in the database will be displayed. + +=head2 reply [options...] <search-term>... + +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. Values 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 + +=over + +=item B<--format=>(B<default>|B<headers-only>) + +=over + +=item B<default> + +Includes subject and quoted message body. + +=item B<headers-only> + +Only produces In-Reply-To, References, To, Cc, and Bcc headers. + +=back + +=back + +Note: It is most common to use B<notmuch reply> with a search string +matching a single message, (such as id:<message-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. + +=head2 tag +<tag>|-<tag> [...] [--] <search-term>... + +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 I<search-terms> 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 +I<search-terms>. The B<dump> and B<restore> commands can be used to +create a textual dump of email tags for backup purposes, and to +restore from that dump + +=head2 dump [<filename>] + +Creates a plain-text dump of the tags of each message. The output is +to the given filename, if any, or to stdout. 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.) + +=head2 restore <filename> + +Restores the tags from the given file (see B<notmuch dump>. 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). + +=head2 part --part=<part-number> <search-term>... + + +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 <search-terms>. + +=head1 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 <brackets> indicate user-supplied values): + + + from:<name-or-address> + to:<name-or-address> + subject:<word-or-quoted-phrase> + attachment:<word> + tag:<tag> (or is:<tag>) + id:<message-id> + thread:<thread-id> + + +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 B<subject:>. + +The B<attachment:> +prefix can be used to search for specific filenames (or extensions) of +attachments to email messages. + For B<tag:> and B<is:> valid tag values include +B<inbox> and B<unread> by default for new messages added by B<notmuch new> as well +as any other tag values added manually with B<notmuch tag>. +For B<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> + +In addition to individual terms, multiple +terms can be combined with Boolean operators ( B<and>, B<or>, B<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: + + <initial-timestamp>..<final-timestamp> + +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 folowing 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) + +=head1 Environment + +The following environment variables can be used to control +the behavior of notmuch. + +=over + +=item B<NOTMUCH_CONFIG> + +Specifies the location of the notmuch +configuration file. Notmuch will use ${HOME}/.notmuch-config if this variable +is not set. + +=back + +=head1 See Also + +The emacs-based interface to notmuch (available +as B<notmuch.el> in the Notmuch distribution). + +The notmuch website: L<http://notmuchmail.org> + +=head1 Contact + +Feel free to send questions, comments, or kudos to the notmuch mailing +list <notmuch at notmuchmail.org> . 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). \ No newline at end of file -- 1.7.1