1 Return-Path: <bremner@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 D225140D14B
\r
6 for <notmuch@notmuchmail.org>; Wed, 3 Nov 2010 10:19:53 -0700 (PDT)
\r
7 X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
\r
11 X-Spam-Status: No, score=-2.6 tagged_above=-999 required=5
\r
12 tests=[BAYES_00=-1.9, RCVD_IN_DNSWL_LOW=-0.7] 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 p2vKz8lAT1Hs for <notmuch@notmuchmail.org>;
\r
16 Wed, 3 Nov 2010 10:19:41 -0700 (PDT)
\r
17 Received: from tempo.its.unb.ca (tempo.its.unb.ca [131.202.1.21])
\r
18 (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits))
\r
19 (No client certificate requested)
\r
20 by olra.theworths.org (Postfix) with ESMTPS id 52DF74196F2
\r
21 for <notmuch@notmuchmail.org>; Wed, 3 Nov 2010 10:19:35 -0700 (PDT)
\r
22 Received: from rocinante.cs.unb.ca
\r
23 (fctnnbsc30w-142167176217.pppoe-dynamic.High-Speed.nb.bellaliant.net
\r
24 [142.167.176.217]) (authenticated bits=0)
\r
25 by tempo.its.unb.ca (8.13.8/8.13.8) with ESMTP id oA3HJYns014327
\r
26 (version=TLSv1/SSLv3 cipher=AES256-SHA bits=256 verify=NO);
\r
27 Wed, 3 Nov 2010 14:19:34 -0300
\r
28 Received: from bremner by rocinante.cs.unb.ca with local (Exim 4.72)
\r
29 (envelope-from <bremner@unb.ca>)
\r
30 id 1PDgzm-0001Ox-3o; Wed, 03 Nov 2010 14:19:34 -0300
\r
31 From: david@tethera.net
\r
32 To: notmuch@notmuchmail.org
\r
33 Subject: [PATCH 1/4] notmuch.pod: pod version of documentation,
\r
34 converted by rman, massaged by hand.
\r
35 Date: Wed, 3 Nov 2010 14:18:53 -0300
\r
36 Message-Id: <1288804736-5173-2-git-send-email-david@tethera.net>
\r
37 X-Mailer: git-send-email 1.7.1
\r
38 In-Reply-To: <874oc4r4bu.fsf@yoom.home.cworth.org>
\r
39 References: <874oc4r4bu.fsf@yoom.home.cworth.org>
\r
40 Cc: David Bremner <bremner@unb.ca>
\r
41 X-BeenThere: notmuch@notmuchmail.org
\r
42 X-Mailman-Version: 2.1.13
\r
44 List-Id: "Use and development of the notmuch mail system."
\r
45 <notmuch.notmuchmail.org>
\r
46 List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
\r
47 <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
\r
48 List-Archive: <http://notmuchmail.org/pipermail/notmuch>
\r
49 List-Post: <mailto:notmuch@notmuchmail.org>
\r
50 List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
\r
51 List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
\r
52 <mailto:notmuch-request@notmuchmail.org?subject=subscribe>
\r
53 X-List-Received-Date: Wed, 03 Nov 2010 17:19:54 -0000
\r
55 From: David Bremner <bremner@unb.ca>
\r
57 Some places I deleted a bit of the continuity text introducing a
\r
58 command because I didn't see how to make it work with the slightly
\r
59 more structured layout.
\r
61 I also moved show in front of search, because it explains the output
\r
62 formats. Probably it would make sense to add a separate section
\r
63 explaining common output formats.
\r
65 The =for help lines are ignored for the man page, but used to generate
\r
68 I also added dummy sections for currently undocumented commands; or
\r
69 more precisely, commands that were not documented that last time I
\r
70 refreshed notmuch.pod.
\r
72 notmuch.pod | 409 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
\r
73 1 files changed, 409 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..f4127e0
\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 +=for help args NULL
\r
125 +=for help desc Interactively sets up notmuch for first use.
\r
127 +The setup command will prompt for your full name, your primary email
\r
128 +address, any alternate email addresses you use, and the directory
\r
129 +containing your email archives. Your answers will be written to a
\r
130 +configuration file in ${NOTMUCH_CONFIG} (if set) or
\r
131 +${HOME}/.notmuch-config . This configuration file will be created with
\r
132 +descriptive comments, making it easy to edit by hand later to change
\r
133 +the configuration. Or you can run B<notmuch setup> again to change the
\r
136 +The mail directory you specify can contain any number of
\r
137 +sub-directories and should primarily contain only files with
\r
138 +individual email messages (eg. maildir or mh archives are perfect). If
\r
139 +there are other, non-email files (such as indexes maintained by other
\r
140 +email programs) then notmuch will do its best to detect those and
\r
143 +Mail storage that uses mbox format, (where one mbox file contains many
\r
144 +messages), will not work with notmuch. If that's how your mail is
\r
145 +currently stored, it is recommended you first convert it to maildir
\r
146 +format with a utility such as mb2md before running B<notmuch setup>
\r
148 +Invoking B<notmuch> with no command argument will run B<setup> if the
\r
149 +setup command has not previously been completed.
\r
153 +=for help args NULL
\r
155 +=for help desc Find and import any new messages to the database.
\r
157 +The B<new> command scans all sub-directories of the database,
\r
158 +performing full-text indexing on new messages that are found. Each new
\r
159 +message will automatically be tagged with both the B<inbox> and
\r
160 +B<unread> tags. You should run B<notmuch new> once after first
\r
161 +running B<notmuch setup> to create the initial database. The first run
\r
162 +may take a long time if you have a significant amount of mail (several
\r
163 +hundred thousand messages or more). Subsequently, you should run
\r
164 +B<notmuch new> whenever new mail is delivered and you wish to
\r
165 +incorporate it into the database. These subsequent runs will be much
\r
166 +quicker than the initial run.
\r
168 +Invoking B<notmuch> with no command argument will run B<new> if
\r
169 +B<notmuch setup> has previously been completed, but B<notmuch new> has
\r
170 +not previously been run.
\r
172 +=head2 show [options...] <search-term>...
\r
174 +=for help args [options...] <search-term>...
\r
175 +=for help desc Shows all messages matching the search terms.
\r
177 +The messages will be grouped and sorted based on the threading (all
\r
178 +replies to a particular message will appear immediately after that
\r
179 +message in date order). The output is not indented by default, but
\r
180 +depth tags are printed so that proper indentation can be performed by
\r
181 +a post-processor (such as the emacs interface to notmuch). Supported
\r
182 +options for B<show> include
\r
186 +=item B<--entire-thread>
\r
188 +By default only those messages that
\r
189 +match the search terms will be displayed. With this option, all messages
\r
190 +in the same thread as any matched message will be displayed.
\r
192 +=item B<--format=(json|text)>
\r
198 +The default plain-text format has text-content MIME parts decoded.
\r
199 +Various components in the output, (B<message>, B<header>, B<body>,
\r
200 +B<attachment>, and MIME B<part>), will be delimited by easily-parsed
\r
201 +markers. Each marker consists of a Control-L character (ASCII decimal
\r
202 +12), the name of the marker, and then either an opening or closing
\r
203 +brace, ('{' or '}'), to either open or close the component.
\r
207 +Format output as Javascript Object Notation (JSON).
\r
208 +JSON output always includes all messages in a matching thread; in effect
\r
209 +B<--format=json> implies B<--entire-thread>.
\r
215 +A common use of B<notmuch show> is to display a single thread of
\r
216 +email messages. For this, use a search term of "thread:<thread-id>" as
\r
217 +can be seen in the first column of output from the B<notmuch search>
\r
220 +See the B<SEARCH SYNTAX> section below for details of the supported
\r
221 +syntax for <search-terms>.
\r
223 +=head2 search [options...] <search-term>...
\r
225 +=for help args [options...] <search-term>...
\r
226 +=for help desc Search threads containing messages matching the given search terms.
\r
228 +The output consists of one line per thread, giving a thread ID, the
\r
229 +date of the newest (or oldest, depending on the sort option) matched
\r
230 +message in the thread, the number of matched messages and total
\r
231 +messages in the thread, the names of all participants in the thread,
\r
232 +and the subject of the newest (or oldest) message. Supported options
\r
233 +for B<search> include
\r
237 +=item B<--format=>(B<json>|B<text>)
\r
239 +Presents the results in either JSON or plain-text (default).
\r
241 +=item B<--sort=>(B<newest-first>|B<oldest-first>)
\r
243 +This option can be used to present results in either chronological
\r
244 +order (B<oldest-first>) or reverse chronological order
\r
245 +(B<newest-first>). Note: The thread order will be distinct between
\r
246 +these two options (beyond being simply reversed). When sorting by
\r
247 +B<oldest-first> the threads will be sorted by the oldest message in
\r
248 +each thread, but when sorting by B<newest-first> the threads will be
\r
249 +sorted by the newest message in each thread. By default, results will
\r
250 +be displayed in reverse chronological order, (that is, the newest
\r
251 +results will be displayed first).
\r
255 +See the B<SEARCH SYNTAX> section below for details of the supported
\r
256 +syntax for B<search-terms>.
\r
258 +=head2 count <search-term>...
\r
260 +=for help args <search-term>...
\r
262 +=for help desc Count messages matching the search terms.
\r
264 +The number of matching messages is output to stdout. With no search
\r
265 +terms, a count of all messages in the database will be displayed.
\r
267 +=head2 reply [options...] <search-term>...
\r
269 +=for help args [options...] <search-term>...
\r
270 +=for help desc Construct a reply template for a set of messages.
\r
272 +To make replying to email easier, B<notmuch reply> takes an existing
\r
273 +set of messages and constructs a suitable mail template. The Reply-to
\r
274 +header (if any, otherwise From:) is used for the To: address. Values
\r
275 +from the To: and Cc: headers are copied, but not including any of the
\r
276 +current user's email addresses (as configured in primary_mail or
\r
277 +other_email in the .notmuch-config file) in the recipient list It also
\r
278 +builds a suitable new subject, including Re: at the front (if not
\r
279 +already present), and adding the message IDs of the messages being
\r
280 +replied to to the References list and setting the In-Reply-To: field
\r
281 +correctly. Finally, the original contents of the emails are quoted by
\r
282 +prefixing each line with '> ' and included in the body. The resulting
\r
283 +message template is output to stdout. Supported options for B<reply>
\r
288 +=item B<--format=>(B<default>|B<headers-only>)
\r
294 +Includes subject and quoted message body.
\r
296 +=item B<headers-only>
\r
298 +Only produces In-Reply-To, References, To, Cc, and Bcc headers.
\r
304 +Note: It is most common to use B<notmuch reply> with a search string
\r
305 +matching a single message, (such as id:<message-id>), but it can be
\r
306 +useful to reply to several messages at once. For example, when a
\r
307 +series of patches are sent in a single thread, replying to the entire
\r
308 +thread allows for the reply to comment on issue found in multiple
\r
311 +=head2 tag +<tag>|-<tag> [...] [--] <search-term>...
\r
313 +=for help args +<tag>|-<tag> [...] [--] <search-term>...
\r
315 +=for help desc Add/remove tags for all messages matching the search terms.
\r
317 +Tags prefixed by '+' are added while those prefixed by '-' are
\r
318 +removed. For each message, tag removal is performed before tag
\r
319 +addition. The beginning of I<search-terms> is recognized by the first
\r
320 +argument that begins with neither '+' nor '-'. Support for an initial
\r
321 +search term beginning with '+' or '-' is provided by allowing the user
\r
322 +to specify a "--" argument to separate the tags from the search terms.
\r
323 +See the B<SEARCH SYNTAX> section below for details of the supported
\r
324 +syntax for I<search-terms>. The B<dump> and B<restore> commands can
\r
325 +be used to create a textual dump of email tags for backup purposes,
\r
326 +and to restore from that dump
\r
328 +=head2 dump [<filename>]
\r
330 +=for help args [<filename>]
\r
331 +=for help desc Create a plain-text dump of the tags of each message.
\r
333 +The output is to the given filename, if any, or to stdout. These tags
\r
334 +are the only data in the notmuch database that can't be recreated from
\r
335 +the messages themselves. The output of notmuch dump is therefore the
\r
336 +only critical thing to backup (and much more friendly to incremental
\r
337 +backup than the native database files.)
\r
339 +=head2 restore <filename>
\r
341 +=for help args [<filename>]
\r
342 +=for help desc Restore the tags from the given file (see <notmuch dump>).
\r
344 +Note: The dump file format is specifically chosen to be compatible
\r
345 +with the format of files produced by sup-dump. So if you've previously
\r
346 +been using sup for mail, then the B<notmuch restore> command provides
\r
347 +you a way to import all of your tags (or labels as sup calls them).
\r
349 +=head2 part --part=<part-number> <search-term>...
\r
351 +=for help args --part=<part-number> <search-term>...
\r
352 +=for help desc Output a single MIME part of a message.
\r
354 +A single decoded MIME part, with no encoding or framing, is output to
\r
355 +stdout. The search terms must match only a single message, otherwise
\r
356 +this command will fail. The part number should match the part "id"
\r
357 +field output by the "--format=json" option of "notmuch show". If the
\r
358 +message specified by the search terms does not include a part with the
\r
359 +specified "id" there will be no output. See the B<SEARCH SYNTAX>
\r
360 +section below for details of the supported syntax for <search-terms>.
\r
362 +=head2 search-tags
\r
364 +=for help args dummy args
\r
365 +=for help desc dummy description
\r
371 +=for help args dummy args
\r
372 +=for help desc dummy description
\r
378 +=for help args dummy args
\r
379 +=for help desc dummy description
\r
384 +=head1 Search Syntax
\r
386 +=for help name search_syntax
\r
388 +Several notmuch commands accept a common syntax
\r
390 +The search terms can consist of free-form text (and quoted
\r
391 +phrases) which will match all messages that contain all of the given terms/phrases
\r
392 +in the body, the subject, or any of the sender or recipient headers.
\r
394 +a special case, a search string consisting of exactly a single asterisk
\r
395 +("*") will match all messages.
\r
396 + In addition to free text, the following
\r
397 +prefixes can be used to force terms to match against specific portions
\r
398 +of an email, (where <brackets> indicate user-supplied values):
\r
401 + from:<name-or-address>
\r
402 + to:<name-or-address>
\r
403 + subject:<word-or-quoted-phrase>
\r
404 + attachment:<word>
\r
405 + tag:<tag> (or is:<tag>)
\r
407 + thread:<thread-id>
\r
410 +The B<from:> prefix is used to match the name or address of the sender
\r
411 +of an email message. The B<to:> prefix is used to match the names or
\r
412 +addresses of any recipient of an email message, (whether To, Cc, or
\r
413 +Bcc). Any term prefixed with B<subject:> will match only text from
\r
414 +the subject of an email.
\r
416 +Searching for a phrase in the subject is supported by including quotation
\r
417 +marks around the phrase, immediately following B<subject:>.
\r
419 +The B<attachment:>
\r
420 +prefix can be used to search for specific filenames (or extensions) of
\r
421 +attachments to email messages.
\r
422 + For B<tag:> and B<is:> valid tag values include
\r
423 +B<inbox> and B<unread> by default for new messages added by B<notmuch new> as well
\r
424 +as any other tag values added manually with B<notmuch tag>.
\r
425 +For B<id:>, message
\r
426 +ID values are the literal contents of the Message-ID: header of email messages,
\r
427 +but without the '<', '>' delimiters.
\r
429 +The B<thread:> prefix can be used with the
\r
430 +thread ID values that are generated internally by notmuch (and do not appear
\r
431 +in email messages). These thread ID values can be seen in the first column
\r
432 +of output from B<notmuch search>
\r
434 +In addition to individual terms, multiple
\r
435 +terms can be combined with Boolean operators ( B<and>, B<or>, B<not> , etc.). Each
\r
436 +term in the query will be implicitly connected by a logical AND if no explicit
\r
437 +operator is provided, (except that terms with a common prefix will be implicitly
\r
438 +combined with OR until we get Xapian defect #402 fixed).
\r
440 +also be used to control the combination of the Boolean operators, but will
\r
441 +have to be protected from interpretation by the shell, (such as by putting
\r
442 +quotation marks around any parenthesized expression).
\r
445 +can be restricted to only messages within a particular time range, (based
\r
446 +on the Date: header) with a syntax of:
\r
448 + <initial-timestamp>..<final-timestamp>
\r
450 +Each timestamp is a number representing the number of seconds since
\r
451 +1970-01-01 00:00:00 UTC. This is not the most convenient means of
\r
452 +expressing date ranges, but until notmuch is fixed to accept a more
\r
453 +convenient form, one can use the date program to construct
\r
454 +timestamps. For example, with the bash shell the folowing syntax would
\r
455 +specify a date range to return messages from 2009-10-01 until the
\r
459 + $(date +%s -d 2009-10-01)..$(date +%s)
\r
461 +=head1 Environment
\r
463 +The following environment variables can be used to control
\r
464 +the behavior of notmuch.
\r
468 +=item B<NOTMUCH_CONFIG>
\r
470 +Specifies the location of the notmuch
\r
471 +configuration file. Notmuch will use ${HOME}/.notmuch-config if this variable
\r
478 +The emacs-based interface to notmuch (available
\r
479 +as B<notmuch.el> in the Notmuch distribution).
\r
481 +The notmuch website: L<http://notmuchmail.org>
\r
485 +Feel free to send questions, comments, or kudos to the notmuch mailing
\r
486 +list <notmuch@notmuchmail.org> . Subscription is not required before
\r
487 +posting, but is available from the notmuchmail.org website.
\r
489 +Real-time interaction with the Notmuch community is available via IRC
\r
490 +(server: irc.freenode.net, channel: #notmuch).
\r
491 \ No newline at end of file
\r
projects / notmuch-archives.git / blob