git.cworth.org Git - notmuch-wiki/blob - getting-started.mdwn

   1 [[!img notmuch-logo.png alt="Notmuch logo" class="left"]]
   2 # Getting Started with Notmuch
   3
   4 *This is a work in progress.*
   5
   6 [[!toc levels=2]]
   7
   8 This is your friendly guide and tutorial to getting started with Notmuch. It
   9 will help you through the first steps of setting up Notmuch.
  10
  11 All Notmuch commands have [manual
  12 pages](https://notmuchmail.org/doc/latest/). Please refer to them for
  13 details.
  14
  15 ## Prerequisites
  16
  17 In order to use Notmuch, you will need to have your email messages stored in
  18 your local filesystem, one message per file. For example,
  19 [Maildir](http://cr.yp.to/proto/maildir.html), Maildir++, and MH formats work
  20 like this, while [mbox](https://en.wikipedia.org/wiki/Mbox) does not. Storing
  21 the messages one message per file is the only hard dependency for trying out
  22 Notmuch.
  23
  24 We will get back to delivering messages later, for now we'll just assume you
  25 already have messages in this format.
  26
  27 ## Installation
  28
  29 On Linux, the easiest way to install Notmuch is through your distribution's
  30 package repository. If you're installing Notmuch from a [git
  31 checkout](https://git.notmuchmail.org/git/notmuch) or a [source
  32 release](https://notmuchmail.org/releases/), please refer to the
  33 [INSTALL](https://git.notmuchmail.org/git/notmuch/blob/HEAD:/INSTALL) document.
  34
  35 ## Configuration
  36
  37 To configure Notmuch, just run
  38
  39         notmuch
  40
  41 This will interactively guide you through the setup process, and save the
  42 configuration to `$HOME/.notmuch-config`. If you'd like to change the
  43 configuration in the future, you can either edit that file directly, or run
  44 `notmuch setup`.
  45
  46 This step only modifies the configuration file.
  47
  48 ## Initial Indexing
  49
  50 Notmuch needs a search database to operate. The next step is to run
  51
  52         notmuch new
  53
  54 to index all your messages in the search database. The database will be stored
  55 in `.notmuch` directory under your mail store. The database is not a replacement
  56 or storage for your messages; it's just an index to find the right message
  57 files.
  58
  59 Notmuch does not modify or delete your mails. This is one of the main design
  60 principles of Notmuch. (The only exception is renaming files upon tagging
  61 according to the Maildir specification if the `maildir.synchronize_flags`
  62 configuration option is set.) It should be safe to try Notmuch.
  63
  64 Depending on the amount of mail you have the initial indexing process can take a
  65 long time, so expect that. Also, the resulting database will require roughly the
  66 same amount of storage space as your current collection of email.
  67
  68 After this step, you can try out the [Notmuch command line
  69 interface](https://notmuchmail.org/doc/latest/man1/notmuch.html), or
  70 [[Notmuch Emacs interface|notmuch-emacs]].
  71
  72 ## Converting Existing mbox to Maildir
  73
  74 The [`mb2md`](http://batleth.sapienti-sat.org/projects/mb2md/) tool can be used
  75 to convert existing mbox files to Maildir.
  76
  77 Beware that the source and destination directory options to `mb2md` are relative
  78 to the user's home directory, not relative to the current working directory.
  79
  80 ## Delivering New Messages
  81
  82 Notmuch itself does not receive messages. There is no IMAP or POP support. You
  83 will need to set up other tools, such as fetchmail, offlineimap, or mbsync, to
  84 receive the messages.
  85
  86 There are two ways to deliver and index messages:
  87
  88 * Use an external tool (such as offlineimap or mbsync) to deliver the messages
  89   to your mail store, and run `notmuch new` to discover and index the newly
  90   delivered messages (and any other changes in the mail store).
  91
  92 * Use an external tool (such as fetchmail) receive the messages, and configure
  93   the tool to use `notmuch insert` as a Mail Delivery Agent to deliver the
  94   messages to your mail store and index them.
  95
  96 ## Automation Via Hooks
  97
  98 Notmuch supports running [user defined
  99 hooks](https://notmuchmail.org/doc/latest/man5/notmuch-hooks.html)
 100 before or after certain commands. Hooks can be arbitrary executable
 101 programs or scripts. For example, if you always run your mail delivery
 102 tool first and `notmuch new` after that, you can run the tool from
 103 Notmuch `pre-new` hook, and simply run `notmuch new` to do both. If
 104 you always do some tagging after indexing of new messages, you may
 105 want to set up a `post-new` or `post-insert` hook to do that
 106 automatically.
 107
 108 ## Backing Up and Restoring the Database
 109
 110 The Notmuch database contains a search index of your messages, along with all
 111 the tags you've added to your messages. The search index can be regenerated by
 112 indexing the messages again, but the tags will be lost if the database is
 113 lost. (If you have `maildir.synchronize_flags` configuration option enabled,
 114 also some of the tags can be regenerated from maildir flags.)
 115
 116 To create a plain-text dump of the tags, run
 117
 118         notmuch dump --output=dump.txt
 119
 120 To restore the tags from the dump, run
 121
 122         notmuch restore --input=dump.txt
 123
 124 ## Removing Notmuch
 125
 126 Did not like it after all? All you need to do is remove the database and the
 127 configuration file. The database is stored in the `.notmuch` directory under
 128 your mail store. And your mail store is at `notmuch config get database.path`.
 129
 130 You may want to use the `notmuch dump` command to create a backup of any tags
 131 you've added before removing the database.