mirror of
https://git.notmuchmail.org/git/notmuch
synced 2025-01-03 15:21:41 +01:00
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.
This commit is contained in:
David Bremner
parent
347f39d73e
commit
c48797b498
13 changed files with 889 additions and 776 deletions
51
man/man1/notmuch-config.1
Normal file
51
man/man1/notmuch-config.1
Normal file
|
|
@ -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 " <section> . <item>
|
||||
|
||||
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 " <section> . "<item> [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
|
||||
39
man/man1/notmuch-count.1
Normal file
39
man/man1/notmuch-count.1
Normal file
|
|
@ -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
|
||||
57
man/man1/notmuch-dump.1
Normal file
57
man/man1/notmuch-dump.1
Normal file
|
|
@ -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 " [<filename>]"
|
||||
|
||||
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] [<filename>]"
|
||||
|
||||
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 <search-terms>.
|
||||
.RE
|
||||
59
man/man1/notmuch-new.1
Normal file
59
man/man1/notmuch-new.1
Normal file
|
|
@ -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
|
||||
28
man/man1/notmuch-part.1
Normal file
28
man/man1/notmuch-part.1
Normal file
|
|
@ -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=" "<part-number>"
|
||||
.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 <search-terms>.
|
||||
.RE
|
||||
60
man/man1/notmuch-reply.1
Normal file
60
man/man1/notmuch-reply.1
Normal file
|
|
@ -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 <search-terms>.
|
||||
|
||||
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.
|
||||
.RE
|
||||
.RE
|
||||
116
man/man1/notmuch-search.1
Normal file
116
man/man1/notmuch-search.1
Normal file
|
|
@ -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 <search-terms>.
|
||||
.RE
|
||||
140
man/man1/notmuch-show.1
Normal file
140
man/man1/notmuch-show.1
Normal file
|
|
@ -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:<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>.
|
||||
.RE
|
||||
.RS 4
|
||||
26
man/man1/notmuch-tag.1
Normal file
26
man/man1/notmuch-tag.1
Normal file
|
|
@ -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 <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 <search-terms>.
|
||||
.RE
|
||||
136
man/man1/notmuch.1
Normal file
136
man/man1/notmuch.1
Normal file
|
|
@ -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 <cworth@cworth.org>
|
||||
.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 <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).
|
||||
40
man/man5/notmuch-hooks.5
Normal file
40
man/man5/notmuch-hooks.5
Normal file
|
|
@ -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
|
||||
137
man/man7/notmuch-search-terms.7
Normal file
137
man/man7/notmuch-search-terms.7
Normal file
|
|
@ -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=" "<part-number>"
|
||||
.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
|
||||
<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>
|
||||
|
||||
folder:<directory-path>
|
||||
|
||||
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:
|
||||
|
||||
<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 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)
|
||||
776
notmuch.1
776
notmuch.1
|
|
@ -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 <cworth@cworth.org>
|
||||
.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-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
|
||||
.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 <search-terms>.
|
||||
.RE
|
||||
.TP
|
||||
.BR 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
|
||||
.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:<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>.
|
||||
.RE
|
||||
.RS 4
|
||||
.TP 4
|
||||
.BR count " [options...] <search-term>..."
|
||||
|
||||
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...] <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
|
||||
.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 <search-terms>.
|
||||
|
||||
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.
|
||||
.RE
|
||||
.RE
|
||||
|
||||
The
|
||||
.B tag
|
||||
command is the only command available for manipulating database
|
||||
contents.
|
||||
|
||||
.RS 4
|
||||
.TP 4
|
||||
.BR 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 <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 <search-terms>.
|
||||
.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 " [<filename>] [--] [<search-terms>]"
|
||||
|
||||
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 <search-terms>.
|
||||
.RE
|
||||
|
||||
.TP
|
||||
.BR restore " [--accumulate] [<filename>]"
|
||||
|
||||
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=<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>.
|
||||
.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 " <section> . <item>
|
||||
|
||||
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 " <section> . "<item> [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
|
||||
<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>
|
||||
|
||||
folder:<directory-path>
|
||||
|
||||
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:
|
||||
|
||||
<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 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 <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).
|
||||
Loading…
Reference in a new issue