=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.

=head1 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.

=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.

Note:
B<notmuch new> runs (other than the first run) will skip any read-only directories,
so you can use that to mark directories that will not receive any new mail
(and make B<notmuch new> even faster). 
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. 
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 B<search> and B<show> commands are
used to query the email database. 

=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<--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 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. 

=back

The  output
format  is plain-text,  with all  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. 

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>. 
The B<reply> command is useful for preparing a template for
an email reply. 

=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.
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 

=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. 
See the B<SEARCH SYNTAX> section below for details
of the supported syntax for <search-terms>. 

=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).


=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. 

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): 

=over

=begin text

 	from:<name-or-address> 
 	to:<name-or-address> 
 	subject:<word-or-quoted-phrase> 
 	attachment:<word> 
 	tag:<tag> 
 	id:<message-id> 
 	thread:<thread-id> 

=end text

=back

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:>, 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: 

=over

<initial-timestamp>..<final-timestamp> 

=back

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:

=over 

text $(date +%s -d 2009-10-01)..$(date +%s) 

=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@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).