.\" along with this program. If not, see http://www.gnu.org/licenses/ .
.\"
.\" Author: Carl Worth <cworth@cworth.org>
-.TH NOTMUCH 1 2009-10-31 "Notmuch 0.1"
+.TH NOTMUCH 1 2012-01-13 "Notmuch 0.11"
.SH NAME
notmuch \- thread-based email index, search, and tagging
.SH SYNOPSIS
command is used to incorporate new mail into the notmuch database.
.RS 4
.TP 4
-.B new
+.BR new " [options...]"
Find and import any new messages to the database.
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
.B newest\-first
the threads will be sorted by the newest message in each thread.
-.RE
-.RS 4
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 <search-terms>.
.RE
.RS 4
.TP 4
-.BR count " <search-term>..."
+.BR count " [options...] <search-term>..."
Count messages matching the search terms.
-The number of matching messages is output to stdout.
+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
-With no search terms, a count of all messages in the database will be
-displayed.
+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
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.