1 Return-Path: <bremner@pivot.cs.unb.ca>
\r
2 X-Original-To: notmuch@notmuchmail.org
\r
3 Delivered-To: notmuch@notmuchmail.org
\r
4 Received: from localhost (localhost [127.0.0.1])
\r
5 by olra.theworths.org (Postfix) with ESMTP id C71374196F4
\r
6 for <notmuch@notmuchmail.org>; Sun, 13 Jun 2010 08:02:07 -0700 (PDT)
\r
7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
\r
11 X-Spam-Status: No, score=-1.9 tagged_above=-999 required=5
\r
12 tests=[BAYES_00=-1.9] autolearn=ham
\r
13 Received: from olra.theworths.org ([127.0.0.1])
\r
14 by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)
\r
15 with ESMTP id KL9anZhoFnLg for <notmuch@notmuchmail.org>;
\r
16 Sun, 13 Jun 2010 08:01:56 -0700 (PDT)
\r
17 Received: from pivot.cs.unb.ca (pivot.cs.unb.ca [131.202.240.57])
\r
18 by olra.theworths.org (Postfix) with ESMTP id EA2DB431FC1
\r
19 for <notmuch@notmuchmail.org>; Sun, 13 Jun 2010 08:01:55 -0700 (PDT)
\r
21 fctnnbsc30w-142167182069.pppoe-dynamic.high-speed.nb.bellaliant.net
\r
22 ([142.167.182.69] helo=rocinante.cs.unb.ca)
\r
23 by pivot.cs.unb.ca with esmtpsa (TLS1.0:RSA_AES_256_CBC_SHA1:32)
\r
24 (Exim 4.69) (envelope-from <bremner@pivot.cs.unb.ca>)
\r
25 id 1ONoh6-00015s-Ad; Sun, 13 Jun 2010 12:01:53 -0300
\r
26 Received: from bremner by rocinante.cs.unb.ca with local (Exim 4.71)
\r
27 (envelope-from <bremner@rocinante.cs.unb.ca>)
\r
28 id 1ONoh0-0001Mt-MR; Sun, 13 Jun 2010 12:01:46 -0300
\r
29 From: david@tethera.net
\r
30 To: notmuch@notmuchmail.org
\r
31 Subject: [PATCH] notmuch.pod: pod version of documentation, converted by rman,
\r
33 Date: Sun, 13 Jun 2010 12:01:30 -0300
\r
34 Message-Id: <1276441290-5081-1-git-send-email-david@tethera.net>
\r
35 X-Mailer: git-send-email 1.7.1
\r
36 In-Reply-To: <87d3xldbav.fsf@rocinante.cs.unb.ca>
\r
37 References: <87d3xldbav.fsf@rocinante.cs.unb.ca>
\r
38 X-Sender-Verified: bremner@pivot.cs.unb.ca
\r
39 Cc: David Bremner <bremner@unb.ca>
\r
40 X-BeenThere: notmuch@notmuchmail.org
\r
41 X-Mailman-Version: 2.1.13
\r
43 List-Id: "Use and development of the notmuch mail system."
\r
44 <notmuch.notmuchmail.org>
\r
45 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
\r
46 <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
\r
47 List-Archive: <http://notmuchmail.org/pipermail/notmuch>
\r
48 List-Post: <mailto:notmuch@notmuchmail.org>
\r
49 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
\r
50 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
\r
51 <mailto:notmuch-request@notmuchmail.org?subject=subscribe>
\r
52 X-List-Received-Date: Sun, 13 Jun 2010 15:02:07 -0000
\r
54 From: David Bremner <bremner@unb.ca>
\r
56 Some places I deleted a bit of the continuity text introducing a
\r
57 command because I didn't see how to make it work with the slightly
\r
58 more structured layout.
\r
60 I also moved show in front of search, because it explains the output
\r
61 formats. Probably it would make sense to add a separate section
\r
62 explaining common output formats.
\r
65 You can take a look at the HTML output at
\r
67 http://pivot.cs.unb.ca/scratch/notmuch.html
\r
69 We can also generate man pages and inline help from this file. I
\r
70 didn't get that far yet, waiting for more encouraging noises :).
\r
72 notmuch.pod | 361 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
\r
73 1 files changed, 361 insertions(+), 0 deletions(-)
\r
74 create mode 100644 notmuch.pod
\r
76 diff --git a/notmuch.pod b/notmuch.pod
\r
77 new file mode 100644
\r
78 index 0000000..719dead
\r
84 +notmuch - thread-based email index, search, and tagging
\r
90 +=item B<notmuch> I<command> [I<args> ...]
\r
96 +Notmuch is a command-line based program for indexing, searching,
\r
97 +reading, and tagging large collections of email messages. The
\r
98 +quickest way to get started with Notmuch is to simply invoke the
\r
99 +B<notmuch> command with no arguments, which will interactively guide
\r
100 +you through the process of indexing your mail.
\r
102 +=head2 Using notmuch
\r
104 +The B<search> and B<show> commands are used to query the email
\r
105 +database. The B<tag> command is the only command available for
\r
106 +manipulating database contents. Several of the notmuch commands
\r
107 +accept search terms with a common syntax. See the B<SEARCH SYNTAX>
\r
108 +section below for more details on the supported syntax.
\r
112 +While the command-line program B<notmuch> provides powerful
\r
113 +functionality, it does not provide the most convenient interface for
\r
114 +that functionality. More sophisticated interfaces are expected to be
\r
115 +built on top of either the command-line interface, or more likely, on
\r
116 +top of the notmuch library interface. See L<http://notmuchmail.org> for
\r
117 +more about alternate interfaces to notmuch.
\r
123 +Interactively sets up notmuch for first use. The setup command will
\r
124 +prompt for your full name, your primary email address, any alternate
\r
125 +email addresses you use, and the directory containing your email
\r
126 +archives. Your answers will be written to a configuration file in
\r
127 +${NOTMUCH_CONFIG} (if set) or ${HOME}/.notmuch-config . This
\r
128 +configuration file will be created with descriptive comments, making
\r
129 +it easy to edit by hand later to change the configuration. Or you can
\r
130 +run B<notmuch setup> again to change the configuration.
\r
132 +The mail directory you specify can contain any number of
\r
133 +sub-directories and should primarily contain only files with
\r
134 +individual email messages (eg. maildir or mh archives are perfect). If
\r
135 +there are other, non-email files (such as indexes maintained by other
\r
136 +email programs) then notmuch will do its best to detect those and
\r
139 +Mail storage that uses mbox format, (where one mbox file contains many
\r
140 +messages), will not work with notmuch. If that's how your mail is
\r
141 +currently stored, it is recommended you first convert it to maildir
\r
142 +format with a utility such as mb2md before running B<notmuch setup>
\r
144 +Invoking B<notmuch> with no command argument will run B<setup> if the
\r
145 +setup command has not previously been completed.
\r
149 +Find and import any new messages to the database. The B<new> command
\r
150 +scans all sub-directories of the database, performing full-text
\r
151 +indexing on new messages that are found. Each new message will
\r
152 +automatically be tagged with both the B<inbox> and B<unread> tags.
\r
153 +You should run B<notmuch new> once after first running B<notmuch
\r
154 +setup> to create the initial database. The first run may take a long
\r
155 +time if you have a significant amount of mail (several hundred
\r
156 +thousand messages or more). Subsequently, you should run B<notmuch new>
\r
157 +whenever new mail is delivered and you wish to incorporate it
\r
158 +into the database. These subsequent runs will be much quicker than
\r
161 +Invoking B<notmuch> with no command argument will run B<new> if
\r
162 +B<notmuch setup> has previously been completed, but B<notmuch new> has
\r
163 +not previously been run.
\r
165 +=head2 show [options...] <search-term>...
\r
167 +Shows all messages matching the search terms. The messages will be
\r
168 +grouped and sorted based on the threading (all replies to a particular
\r
169 +message will appear immediately after that message in date order). The
\r
170 +output is not indented by default, but depth tags are printed so that
\r
171 +proper indentation can be performed by a post-processor (such as the
\r
172 +emacs interface to notmuch). Supported options for B<show> include
\r
176 +=item B<--entire-thread>
\r
178 +By default only those messages that
\r
179 +match the search terms will be displayed. With this option, all messages
\r
180 +in the same thread as any matched message will be displayed.
\r
182 +=item B<--format=(json|text)>
\r
188 +The default plain-text format has text-content MIME parts decoded.
\r
189 +Various components in the output, (B<message>, B<header>, B<body>,
\r
190 +B<attachment>, and MIME B<part>), will be delimited by easily-parsed
\r
191 +markers. Each marker consists of a Control-L character (ASCII decimal
\r
192 +12), the name of the marker, and then either an opening or closing
\r
193 +brace, ('{' or '}'), to either open or close the component.
\r
197 +Format output as Javascript Object Notation (JSON).
\r
198 +JSON output always includes all messages in a matching thread; in effect
\r
199 +B<--format=json> implies B<--entire-thread>.
\r
205 +A common use of B<notmuch show> is to display a single thread of
\r
206 +email messages. For this, use a search term of "thread:<thread-id>" as
\r
207 +can be seen in the first column of output from the B<notmuch search>
\r
210 +See the B<SEARCH SYNTAX> section below for details of the supported
\r
211 +syntax for <search-terms>.
\r
213 +=head2 search [options...] <search-term>...
\r
215 +Search for messages matching the given search terms, and display as
\r
216 +results the threads containing the matched messages. The output
\r
217 +consists of one line per thread, giving a thread ID, the date of the
\r
218 +newest (or oldest, depending on the sort option) matched message in
\r
219 +the thread, the number of matched messages and total messages in the
\r
220 +thread, the names of all participants in the thread, and the subject
\r
221 +of the newest (or oldest) message. Supported options for B<search>
\r
226 +=item B<--format=>(B<json>|B<text>)
\r
228 +Presents the results in either JSON or plain-text (default).
\r
230 +=item B<--sort=>(B<newest-first>|B<oldest-first>)
\r
232 +This option can be used to present results in either chronological
\r
233 +order (B<oldest-first>) or reverse chronological order
\r
234 +(B<newest-first>). Note: The thread order will be distinct between
\r
235 +these two options (beyond being simply reversed). When sorting by
\r
236 +B<oldest-first> the threads will be sorted by the oldest message in
\r
237 +each thread, but when sorting by B<newest-first> the threads will be
\r
238 +sorted by the newest message in each thread. By default, results will
\r
239 +be displayed in reverse chronological order, (that is, the newest
\r
240 +results will be displayed first).
\r
244 +See the B<SEARCH SYNTAX> section below for details of the supported
\r
245 +syntax for B<search-terms>.
\r
247 +=head2 count <search-term>...
\r
249 +Count messages matching the search terms.
\r
251 +The number of matching messages is output to stdout. With no search
\r
252 +terms, a count of all messages in the database will be displayed.
\r
254 +=head2 reply [options...] <search-term>...
\r
256 +Constructs a reply template for a set of messages. To make replying
\r
257 +to email easier, B<notmuch reply> takes an existing set of messages
\r
258 +and constructs a suitable mail template. The Reply-to header (if any,
\r
259 +otherwise From:) is used for the To: address. Values from the To: and
\r
260 +Cc: headers are copied, but not including any of the current user's
\r
261 +email addresses (as configured in primary_mail or other_email in the
\r
262 +.notmuch-config file) in the recipient list It also builds a suitable
\r
263 +new subject, including Re: at the front (if not already present), and
\r
264 +adding the message IDs of the messages being replied to to the
\r
265 +References list and setting the In-Reply-To: field correctly.
\r
266 +Finally, the original contents of the emails are quoted by prefixing
\r
267 +each line with '> ' and included in the body. The resulting message
\r
268 +template is output to stdout. Supported options for B<reply> include
\r
272 +=item B<--format=>(B<default>|B<headers-only>)
\r
278 +Includes subject and quoted message body.
\r
280 +=item B<headers-only>
\r
282 +Only produces In-Reply-To, References, To, Cc, and Bcc headers.
\r
288 +Note: It is most common to use B<notmuch reply> with a search string
\r
289 +matching a single message, (such as id:<message-id>), but it can be
\r
290 +useful to reply to several messages at once. For example, when a
\r
291 +series of patches are sent in a single thread, replying to the entire
\r
292 +thread allows for the reply to comment on issue found in multiple
\r
295 +=head2 tag +<tag>|-<tag> [...] [--] <search-term>...
\r
297 +Add/remove tags for all messages matching the search terms. Tags
\r
298 +prefixed by '+' are added while those prefixed by '-' are removed. For
\r
299 +each message, tag removal is performed before tag addition. The
\r
300 +beginning of I<search-terms> is recognized by the first argument that
\r
301 +begins with neither '+' nor '-'. Support for an initial search term
\r
302 +beginning with '+' or '-' is provided by allowing the user to specify
\r
303 +a "--" argument to separate the tags from the search terms. See the
\r
304 +B<SEARCH SYNTAX> section below for details of the supported syntax for
\r
305 +I<search-terms>. The B<dump> and B<restore> commands can be used to
\r
306 +create a textual dump of email tags for backup purposes, and to
\r
307 +restore from that dump
\r
309 +=head2 dump [<filename>]
\r
311 +Creates a plain-text dump of the tags of each message. The output is
\r
312 +to the given filename, if any, or to stdout. These tags are the only
\r
313 +data in the notmuch database that can't be recreated from the messages
\r
314 +themselves. The output of notmuch dump is therefore the only critical
\r
315 +thing to backup (and much more friendly to incremental backup than the
\r
316 +native database files.)
\r
318 +=head2 restore <filename>
\r
320 +Restores the tags from the given file (see B<notmuch dump>. Note: The
\r
321 +dump file format is specifically chosen to be compatible with the
\r
322 +format of files produced by sup-dump. So if you've previously been
\r
323 +using sup for mail, then the B<notmuch restore> command provides you a
\r
324 +way to import all of your tags (or labels as sup calls them).
\r
326 +=head2 part --part=<part-number> <search-term>...
\r
329 +Output a single MIME part of a message. A single decoded MIME part,
\r
330 +with no encoding or framing, is output to stdout. The search terms
\r
331 +must match only a single message, otherwise this command will fail.
\r
332 +The part number should match the part "id" field output by the
\r
333 +"--format=json" option of "notmuch show". If the message specified by
\r
334 +the search terms does not include a part with the specified "id" there
\r
335 +will be no output. See the B<SEARCH SYNTAX> section below for details
\r
336 +of the supported syntax for <search-terms>.
\r
338 +=head1 Search Syntax
\r
340 +Several notmuch commands accept a common syntax
\r
342 +The search terms can consist of free-form text (and quoted
\r
343 +phrases) which will match all messages that contain all of the given terms/phrases
\r
344 +in the body, the subject, or any of the sender or recipient headers.
\r
346 +a special case, a search string consisting of exactly a single asterisk
\r
347 +("*") will match all messages.
\r
348 + In addition to free text, the following
\r
349 +prefixes can be used to force terms to match against specific portions
\r
350 +of an email, (where <brackets> indicate user-supplied values):
\r
353 + from:<name-or-address>
\r
354 + to:<name-or-address>
\r
355 + subject:<word-or-quoted-phrase>
\r
356 + attachment:<word>
\r
357 + tag:<tag> (or is:<tag>)
\r
359 + thread:<thread-id>
\r
362 +The B<from:> prefix is used to match the name or address of the sender
\r
363 +of an email message. The B<to:> prefix is used to match the names or
\r
364 +addresses of any recipient of an email message, (whether To, Cc, or
\r
365 +Bcc). Any term prefixed with B<subject:> will match only text from
\r
366 +the subject of an email.
\r
368 +Searching for a phrase in the subject is supported by including quotation
\r
369 +marks around the phrase, immediately following B<subject:>.
\r
371 +The B<attachment:>
\r
372 +prefix can be used to search for specific filenames (or extensions) of
\r
373 +attachments to email messages.
\r
374 + For B<tag:> and B<is:> valid tag values include
\r
375 +B<inbox> and B<unread> by default for new messages added by B<notmuch new> as well
\r
376 +as any other tag values added manually with B<notmuch tag>.
\r
377 +For B<id:>, message
\r
378 +ID values are the literal contents of the Message-ID: header of email messages,
\r
379 +but without the '<', '>' delimiters.
\r
381 +The B<thread:> prefix can be used with the
\r
382 +thread ID values that are generated internally by notmuch (and do not appear
\r
383 +in email messages). These thread ID values can be seen in the first column
\r
384 +of output from B<notmuch search>
\r
386 +In addition to individual terms, multiple
\r
387 +terms can be combined with Boolean operators ( B<and>, B<or>, B<not> , etc.). Each
\r
388 +term in the query will be implicitly connected by a logical AND if no explicit
\r
389 +operator is provided, (except that terms with a common prefix will be implicitly
\r
390 +combined with OR until we get Xapian defect #402 fixed).
\r
392 +also be used to control the combination of the Boolean operators, but will
\r
393 +have to be protected from interpretation by the shell, (such as by putting
\r
394 +quotation marks around any parenthesized expression).
\r
397 +can be restricted to only messages within a particular time range, (based
\r
398 +on the Date: header) with a syntax of:
\r
400 + <initial-timestamp>..<final-timestamp>
\r
402 +Each timestamp is a number representing the number of seconds since
\r
403 +1970-01-01 00:00:00 UTC. This is not the most convenient means of
\r
404 +expressing date ranges, but until notmuch is fixed to accept a more
\r
405 +convenient form, one can use the date program to construct
\r
406 +timestamps. For example, with the bash shell the folowing syntax would
\r
407 +specify a date range to return messages from 2009-10-01 until the
\r
411 + $(date +%s -d 2009-10-01)..$(date +%s)
\r
413 +=head1 Environment
\r
415 +The following environment variables can be used to control
\r
416 +the behavior of notmuch.
\r
420 +=item B<NOTMUCH_CONFIG>
\r
422 +Specifies the location of the notmuch
\r
423 +configuration file. Notmuch will use ${HOME}/.notmuch-config if this variable
\r
430 +The emacs-based interface to notmuch (available
\r
431 +as B<notmuch.el> in the Notmuch distribution).
\r
433 +The notmuch website: L<http://notmuchmail.org>
\r
437 +Feel free to send questions, comments, or kudos to the notmuch mailing
\r
438 +list <notmuch@notmuchmail.org> . Subscription is not required before
\r
439 +posting, but is available from the notmuchmail.org website.
\r
441 +Real-time interaction with the Notmuch community is available via IRC
\r
442 +(server: irc.freenode.net, channel: #notmuch).
\r
443 \ No newline at end of file
\r
projects / notmuch-archives.git / blob