Add a simple manual page for notmuch.
authorCarl Worth <>
Mon, 2 Nov 2009 14:13:16 +0000 (06:13 -0800)
committerCarl Worth <>
Mon, 2 Nov 2009 15:18:31 +0000 (07:18 -0800)
By pulling content out of notmuch help, and also the messages
printed by "notmuch setup".

notmuch.1 [new file with mode: 0644]

index ad5e336b8934ebd394de87d82c3339e2a7183f3d..584bec601deba197cb7c895ea77002c7d27b3274 100644 (file)
@@ -1,3 +1,5 @@
index 26ab8da8e748b32beb143e4f92d7ab02707a5eb2..fee4ffffc0ee6a579290832a24e168b91fa81fd7 100644 (file)
--- a/Makefile
+++ b/Makefile
@@ -41,8 +41,12 @@ Makefile.dep: *.c *.cc
 -include Makefile.dep
+       gzip --stdout notmuch.1 > notmuch.1.gz
+install: notmuch.1.gz
        install -C -D notmuch $(DESTDIR)/usr/bin/notmuch
+       install -C -D notmuch.1.gz $(DESTDIR)/usr/share/man/man1
        install -C -D notmuch-completion.bash $(DESTDIR)/etc/bash_completion.d/notmuch
diff --git a/TODO b/TODO
index 462dfa25a290d0bda4bc9379032511fb66956b2d..49485d197dbce06215596b6eae432438e4037d8a 100644 (file)
--- a/TODO
+++ b/TODO
@@ -1,5 +1,3 @@
-Write a notmuch man page.
 Compile and install a libnotmuch library.
 Make "notmuch setup" not index all messages, but only what it can do
diff --git a/notmuch.1 b/notmuch.1
new file mode 100644 (file)
index 0000000..08bcf14
--- /dev/null
+++ b/notmuch.1
@@ -0,0 +1,239 @@
+.\" 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
+.\" 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 .
+.\" Author: Carl Worth <>
+.TH NOTMUCH 1 2009-10-31 "Notmuch 0.1"
+notmuch \- thread-based email index, search, and tagging
+.B notmuch
+.IR command " [" args " ...]"
+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.
+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 for more about alternate
+interfaces to notmuch.
+All commands need to know where your mail (and the notmuch database)
+are stored. This is ${HOME}/mail by default. An alternate location can
+be specified with the
+environment variable.
+.BR setup " and " new
+commands are used to add new mail messages to the notmuch database.
+.RS 4
+.TP 4
+.B setup
+Interactively sets up notmuch for first use.
+The setup command will prompt for the directory containing your email
+archives, and will then proceed to build a database that indexes the
+mail to allow for fast search of the archive.
+This directory can contain any number of sub-directories and should
+primarily contain only files with indvidual 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
+.BR "notmuch setup" .
+.B notmuch
+with no command argument will run
+.B setup
+if the setup command has not previously been completed.
+.B new
+Find and import any new messages to the database.
+.B new
+command scans all sub-directories of the database, adding new messages
+that are found. Each new message will automatically be tagged with
+both the
+.BR inbox and unread
+.B notmuch new
+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
+.BR search " and "show
+commands are used to query the email database.
+.RS 4
+.TP 4
+.BR search " <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 oldest matched message in the thread, and the subject from
+that message.
+Currently, the supported search terms are as follows, (where
+<brackets> indicate user-supplied values):
+       tag:<tag>
+       id:<message-id>
+       thread:<thread-id>
+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" .
+Message ID values are the literal contents of the Message-ID: header
+of email messages, but without the '<', '>' delimiters.
+Thread ID values are generated internally by notmuch but can be seen
+in the first column of output from
+.B notmuch search
+for example.
+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
+.BR show " <thread-ID>"
+Show the thread with the given thread ID.
+Displays each message in the thread on stdout.
+Thread ID values are given as the first column in the output of the
+"notmuch search" command. These are the random-looking strings of 32
+.B tag
+command is the only command available for manipulating database
+.RS 4
+.TP 4
+.BR tag " +<tag>|-<tag> [...] [--] <search-term>..."
+Add/remove tags for all messages matching the search terms.
+The search terms are handled exactly as in
+.B "notmuch search"
+so one can use that command first to see what will be modified.
+Tags prefixed by '+' are added while those prefixed by '-' are
+removed. For each message, tag removal is before tag addition.
+The beginning of <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.
+Caution: If you run
+.B "notmuch new"
+between reading a thread with
+.B "notmuch show"
+and removing the "inbox" tag for that thread with
+.B "notmuch tag"
+then you create the possibility of moving some messages from that
+thread out of your inbox without ever reading them. The easiest way to
+avoid this problem is to not run
+.B "notmuch new"
+between reading mail and removing tags.
+.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 " [<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.)
+.BR restore " <filename>"
+Restores the tags from the given file (see
+.BR "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).
+Set to the directory which contains the user's mail to be indexed and
+searched by notmuch. Notmuch will create a directory named
+.B .notmuch
+at the toplevel of this directory where it will store its database.
+The emacs-based interface to notmuch (available as
+.B notmuch.el
+in the Notmuch distribution).
+The notmuch website:
index fe4efa5991b8c3d4a009c7f71f9a942c3f4cbfbe..4158cc5f098bf13429168a389393beb1c42614dd 100644 (file)
--- a/notmuch.c
+++ b/notmuch.c
@@ -1305,7 +1305,7 @@ command_t commands[] = {
       "\t\t\"inbox\" and \"unread\".\n"
       "\t\tNote: \"notmuch new\" will skip any read-only directories,\n"
-      "\t\tso you can use that to mark tdirectories that will not\n"
+      "\t\tso you can use that to mark directories that will not\n"
       "\t\treceive any new mail (and make \"notmuch new\" faster)." },
     { "search", search_command,
       "<search-term> [...]\n\n"