1NOTMUCH(1) General Commands Manual NOTMUCH(1)
2
6 notmuch - thread-based email index, search, and tagging
7
9 notmuch command [args ...]
10
12 Notmuch is a command-line based program for indexing, searching, read‐
13 ing, and tagging large collections of email messages.
14 The quickest way to get started with Notmuch is to simply invoke the
16 notmuch command with no arguments, which will interactively guide you
17 through the process of indexing your mail.
18
20 While the command-line program notmuch provides powerful functionality,
21 it does not provide the most convenient interface for that functional‐
22 ity. More sophisticated interfaces are expected to be built on top of
23 either the command-line interface, or more likely, on top of the not‐
24 much library interface. See http://notmuchmail.org for more about
25 alternate interfaces to notmuch.
26
28 The setup command is used to configure Notmuch for first use, (or to
29 reconfigure it later).
30 setup
32 Interactively sets up notmuch for first use.
34 The setup command will prompt for your full name, your primary
36 email address, any alternate email addresses you use, and the
37 directory containing your email archives. Your answers will be
38 written to a configuration file in ${NOTMUCH_CONFIG} (if set)
39 or ${HOME}/.notmuch-config . This configuration file will be
40 created with descriptive comments, making it easy to edit by
41 hand later to change the configuration. Or you can run notmuch
42 setup again to change the configuration.
43 The mail directory you specify can contain any number of sub-
45 directories and should primarily contain only files with indi‐
46 vidual email messages (eg. maildir or mh archives are perfect).
47 If there are other, non-email files (such as indexes maintained
48 by other email programs) then notmuch will do its best to
49 detect those and ignore them.
50 Mail storage that uses mbox format, (where one mbox file con‐
52 tains many messages), will not work with notmuch. If that's how
53 your mail is currently stored, it is recommended you first con‐
54 vert it to maildir format with a utility such as mb2md before
55 running notmuch setup .
56 Invoking notmuch with no command argument will run setup if the
58 setup command has not previously been completed.
59 The new command is used to incorporate new mail into the notmuch data‐
61 base.
62 new
64 Find and import any new messages to the database.
66 The new command scans all sub-directories of the database, per‐
68 forming full-text indexing on new messages that are found. Each
69 new message will automatically be tagged with both the inbox
70 and unread tags.
71 You should run notmuch new once after first running notmuch
73 setup to create the initial database. The first run may take a
74 long time if you have a significant amount of mail (several
75 hundred thousand messages or more). Subsequently, you should
76 run notmuch new whenever new mail is delivered and you wish to
77 incorporate it into the database. These subsequent runs will be
78 much quicker than the initial run.
79 Invoking notmuch with no command argument will run new if not‐
81 much setup has previously been completed, but notmuch new has
82 not previously been run.
83 Several of the notmuch commands accept search terms with a common syn‐
85 tax. See the SEARCH SYNTAX section below for more details on the sup‐
86 ported syntax.
87 The search, show and count commands are used to query the email data‐
89 base.
90 search [options...] <search-term>...
92 Search for messages matching the given search terms, and dis‐
94 play as results the threads containing the matched messages.
95 The output consists of one line per thread, giving a thread ID,
97 the date of the newest (or oldest, depending on the sort
98 option) matched message in the thread, the number of matched
99 messages and total messages in the thread, the names of all
100 participants in the thread, and the subject of the newest (or
101 oldest) message.
102 Supported options for search include
104 --format=(json|text)
106 Presents the results in either JSON or plain-text
108 (default).
109 --output=(summary|threads|messages|files|tags)
112 summary
115 Output a summary of each thread with any message match‐
117 ing the search terms. The summary includes the thread
118 ID, date, the number of messages in the thread (both
119 the number matched and the total number), the authors
120 of the thread and the subject.
121 threads
123 Output the thread IDs of all threads with any message
125 matching the search terms, either one per line (--for‐
126 mat=text) or as a JSON array (--format=json).
127 messages
129 Output the message IDs of all messages matching the
131 search terms, either one per line (--format=text) or as
132 a JSON array (--format=json).
133 files
135 Output the filenames of all messages matching the
137 search terms, either one per line (--format=text) or as
138 a JSON array (--format=json).
139 tags
141 Output all tags that appear on any message matching the
143 search terms, either one per line (--format=text) or as
144 a JSON array (--format=json).
145 --sort=(newest-first|oldest-first)
148 This option can be used to present results in either
150 chronological order (oldest-first) or reverse chronological
151 order (newest-first).
152 Note: The thread order will be distinct between these two
154 options (beyond being simply reversed). When sorting by
155 oldest-first the threads will be sorted by the oldest mes‐
156 sage in each thread, but when sorting by newest-first the
157 threads will be sorted by the newest message in each
158 thread.
159 By default, results will be displayed in reverse chronological
161 order, (that is, the newest results will be displayed first).
162 See the SEARCH SYNTAX section below for details of the sup‐
164 ported syntax for <search-terms>.
165 show [options...] <search-term>...
167 Shows all messages matching the search terms.
169 The messages will be grouped and sorted based on the threading
171 (all replies to a particular message will appear immediately
172 after that message in date order). The output is not indented
173 by default, but depth tags are printed so that proper indenta‐
174 tion can be performed by a post-processor (such as the emacs
175 interface to notmuch).
176 Supported options for show include
178 --entire-thread
180 By default only those messages that match the search terms
182 will be displayed. With this option, all messages in the
183 same thread as any matched message will be displayed.
184 --format=(text|json|mbox|raw)
187 text
190 The default plain-text format has all text-content MIME
192 parts decoded. Various components in the output, (mes‐
193 sage, header, body, attachment, and MIME part), will be
194 delimited by easily-parsed markers. Each marker con‐
195 sists of a Control-L character (ASCII decimal 12), the
196 name of the marker, and then either an opening or clos‐
197 ing brace, ('{' or '}'), to either open or close the
198 component.
199 json
201 The output is formatted with Javascript Object Notation
203 (JSON). This format is more robust than the text format
204 for automated processing. JSON output always includes
205 all messages in a matching thread; in effect --for‐
206 mat=json implies --entire-thread
207 mbox
210 All matching messages are output in the traditional,
212 Unix mbox format with each message being prefixed by a
213 line beginning with "From " and a blank line separating
214 each message. Lines in the message content beginning
215 with "From " (preceded by zero or more '>' characters)
216 have an additional '>' character added. This reversible
217 escaping is termed "mboxrd" format and described in
218 detail here: http://homepage.ntl‐
219 world.com/jonathan.deboynepollard/FGA/mail-mbox-for‐
220 mats.html
221 raw
223 The original, raw content of the email message is dis‐
225 played. Consumers of this format should expect to
226 implement MIME decoding and similar functions. This
227 format must only be used with search terms matching a
228 single message.
229 A common use of notmuch show is to display a single thread of
231 email messages. For this, use a search term of "thread:<thread-
232 id>" as can be seen in the first column of output from the not‐
233 much search command.
234 See the SEARCH SYNTAX section below for details of the sup‐
236 ported syntax for <search-terms>.
237 count <search-term>...
239 Count messages matching the search terms.
241 The number of matching messages is output to stdout.
243 With no search terms, a count of all messages in the database
245 will be displayed.
246 The reply command is useful for preparing a template for an email
248 reply.
249 reply [options...] <search-term>...
251 Constructs a reply template for a set of messages.
253 To make replying to email easier, notmuch reply takes an exist‐
255 ing set of messages and constructs a suitable mail template.
256 The Reply-to header (if any, otherwise From:) is used for the
257 To: address. Vales from the To: and Cc: headers are copied, but
258 not including any of the current user's email addresses (as
259 configured in primary_mail or other_email in the .notmuch-con‐
260 fig file) in the recipient list
261 It also builds a suitable new subject, including Re: at the
263 front (if not already present), and adding the message IDs of
264 the messages being replied to to the References list and set‐
265 ting the In-Reply-To: field correctly.
266 Finally, the original contents of the emails are quoted by pre‐
268 fixing each line with '> ' and included in the body.
269 The resulting message template is output to stdout.
271 Supported options for reply include
273 --format=(default|headers-only)
275 default
277 Includes subject and quoted message body.
278 headers-only
280 Only produces In-Reply-To, References, To, Cc, and Bcc
281 headers.
282 See the SEARCH SYNTAX section below for details of the sup‐
284 ported syntax for <search-terms>.
285 Note: It is most common to use notmuch reply with a search
287 string matching a single message, (such as id:<message-id>),
288 but it can be useful to reply to several messages at once. For
289 example, when a series of patches are sent in a single thread,
290 replying to the entire thread allows for the reply to comment
291 on issue found in multiple patches.
292 The tag command is the only command available for manipulating database
294 contents.
295 tag +<tag>|-<tag> [...] [--] <search-term>...
298 Add/remove tags for all messages matching the search terms.
300 Tags prefixed by '+' are added while those prefixed by '-' are
302 removed. For each message, tag removal is performed before tag
303 addition.
304 The beginning of <search-terms> is recognized by the first
306 argument that begins with neither '+' nor '-'. Support for an
307 initial search term beginning with '+' or '-' is provided by
308 allowing the user to specify a "--" argument to separate the
309 tags from the search terms.
310 See the SEARCH SYNTAX section below for details of the sup‐
312 ported syntax for <search-terms>.
313 The dump and restore commands can be used to create a textual dump of
315 email tags for backup purposes, and to restore from that dump
316 dump [<filename>]
319 Creates a plain-text dump of the tags of each message.
321 The output is to the given filename, if any, or to stdout.
323 These tags are the only data in the notmuch database that can't
325 be recreated from the messages themselves. The output of not‐
326 much dump is therefore the only critical thing to backup (and
327 much more friendly to incremental backup than the native data‐
328 base files.)
329 restore <filename>
331 Restores the tags from the given file (see notmuch dump.
333 Note: The dump file format is specifically chosen to be compat‐
335 ible with the format of files produced by sup-dump. So if
336 you've previously been using sup for mail, then the notmuch
337 restore command provides you a way to import all of your tags
338 (or labels as sup calls them).
339 The part command can used to output a single part of a multi-part MIME
341 message.
342 part --part=<part-number> <search-term>...
345 Output a single MIME part of a message.
347 A single decoded MIME part, with no encoding or framing, is
349 output to stdout. The search terms must match only a single
350 message, otherwise this command will fail.
351 The part number should match the part "id" field output by the
353 "--format=json" option of "notmuch show". If the message speci‐
354 fied by the search terms does not include a part with the spec‐
355 ified "id" there will be no output.
356 See the SEARCH SYNTAX section below for details of the sup‐
358 ported syntax for <search-terms>.
359 The config command can be used to get or set settings int the notmuch
361 configuration file.
362 config get <section>.<item>
365 The value of the specified configuration item is printed to
367 stdout. If the item has multiple values, each value is sepa‐
368 rated by a newline character.
369 Available configuration items include at least
371 database.path
373 user.name
375 user.primary_email
377 user.other_email
379 new.tags
381 config set <section>.<item> [values ...]
384 The specified configuration item is set to the given value. To
386 specify a multiple-value item, provide each value as a separate
387 command-line argument.
388 If no values are provided, the specified configuration item
390 will be removed from the configuration file.
391
394 Several notmuch commands accept a common syntax for search terms.
395 The search terms can consist of free-form text (and quoted phrases)
397 which will match all messages that contain all of the given
398 terms/phrases in the body, the subject, or any of the sender or recipi‐
399 ent headers.
400 As a special case, a search string consisting of exactly a single
402 asterisk ("*") will match all messages.
403 In addition to free text, the following prefixes can be used to force
405 terms to match against specific portions of an email, (where <brackets>
406 indicate user-supplied values):
407 from:<name-or-address>
409 to:<name-or-address>
411 subject:<word-or-quoted-phrase>
413 attachment:<word>
415 tag:<tag> (or is:<tag>)
417 id:<message-id>
419 thread:<thread-id>
421 The from: prefix is used to match the name or address of the sender of
423 an email message.
424 The to: prefix is used to match the names or addresses of any recipient
426 of an email message, (whether To, Cc, or Bcc).
427 Any term prefixed with subject: will match only text from the subject
429 of an email. Searching for a phrase in the subject is supported by
430 including quotation marks around the phrase, immediately following sub‐
431 ject:.
432 The attachment: prefix can be used to search for specific filenames (or
434 extensions) of attachments to email messages.
435 For tag: and is: valid tag values include inbox and unread by default
437 for new messages added by notmuch new as well as any other tag values
438 added manually with notmuch tag.
439 For id:, message ID values are the literal contents of the Message-ID:
441 header of email messages, but without the '<', '>' delimiters.
442 The thread: prefix can be used with the thread ID values that are gen‐
444 erated internally by notmuch (and do not appear in email messages).
445 These thread ID values can be seen in the first column of output from
446 notmuch search
447 In addition to individual terms, multiple terms can be combined with
449 Boolean operators ( and, or, not , etc.). Each term in the query will
450 be implicitly connected by a logical AND if no explicit operator is
451 provided, (except that terms with a common prefix will be implicitly
452 combined with OR until we get Xapian defect #402 fixed).
453 Parentheses can also be used to control the combination of the Boolean
455 operators, but will have to be protected from interpretation by the
456 shell, (such as by putting quotation marks around any parenthesized
457 expression).
458 Finally, results can be restricted to only messages within a particular
460 time range, (based on the Date: header) with a syntax of:
461 <intial-timestamp>..<final-timestamp>
463 Each timestamp is a number representing the number of seconds since
465 1970-01-01 00:00:00 UTC. This is not the most convenient means of
466 expressing date ranges, but until notmuch is fixed to accept a more
467 convenient form, one can use the date program to construct timestamps.
468 For example, with the bash shell the folowing syntax would specify a
469 date range to return messages from 2009-10-01 until the current time:
470 $(date +%s -d 2009-10-01)..$(date +%s)
472
474 The following environment variables can be used to control the behavior
475 of notmuch.
476 NOTMUCH_CONFIG
478 Specifies the location of the notmuch configuration file. Not‐
479 much will use ${HOME}/.notmuch-config if this variable is not
480 set.
481
483 The emacs-based interface to notmuch (available as notmuch.el in the
484 Notmuch distribution).
485 The notmuch website: http://notmuchmail.org
487
489 Feel free to send questions, comments, or kudos to the notmuch mailing
490 list <notmuch@notmuchmail.org> . Subscription is not required before
491 posting, but is available from the notmuchmail.org website.
492 Real-time interaction with the Notmuch community is available via IRC
494 (server: irc.freenode.net, channel: #notmuch).
495Notmuch 0.1 2009-10-31 NOTMUCH(1)