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 pages|manpages]]. Please refer to them for
  12 details.
  13
  14 ## Prerequisites
  15
  16 In order to use Notmuch, you will need to have your email messages stored in
  17 your local filesystem, one message per file. For example,
  18 [Maildir](http://cr.yp.to/proto/maildir.html), Maildir++, and MH formats work
  19 like this, while [mbox](https://en.wikipedia.org/wiki/Mbox) does not. Storing
  20 the messages one message per file is the only hard dependency for trying out
  21 Notmuch.
  22
  23 We will get back to delivering messages later, for now we'll just assume you
  24 already have messages in this format.
  25
  26 ## Installation
  27
  28 On Linux, the easiest way to install Notmuch is through your distribution's
  29 package repository. If you're installing Notmuch from a [git
  30 checkout](http://git.notmuchmail.org/git/notmuch) or a [source
  31 release](http://notmuchmail.org/releases/), please refer to the
  32 [INSTALL](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/INSTALL) document.
  33
  34 ## Configuration
  35
  36 To configure Notmuch, just run
  37
  38         notmuch
  39
  40 This will interactively guide you through the setup process, and save the
  41 configuration to `$HOME/.notmuch-config`. If you'd like to change the
  42 configuration in the future, you can either edit that file directly, or run
  43 `notmuch setup`.
  44
  45 This step only modifies the configuration file.
  46
  47 ## Initial Indexing
  48
  49 Notmuch needs a search database to operate. The next step is to run
  50
  51         notmuch new
  52
  53 to index all your messages in the search database. The database will be stored
  54 in `.notmuch` directory under your mail store. The database is not a replacement
  55 or storage for your messages; it's just an index to find the right message
  56 files.
  57
  58 Notmuch does not modify or delete your mails. This is one of the main design
  59 principles of Notmuch. (The only exception is renaming files upon tagging
  60 according to the Maildir specification if the `maildir.synchronize_flags`
  61 configuration option is set.) It should be safe to try Notmuch.
  62
  63 Depending on the amount of mail you have the initial indexing process can take a
  64 long time, so expect that. Also, the resulting database will require roughly the
  65 same amount of storage space as your current collection of email.
  66
  67 After this step, you can try out the [[Notmuch command-line
  68 interface|manpages]], or [[Notmuch Emacs interface|notmuch-emacs]].
  69
  70 ## Converting Existing mbox to Maildir
  71
  72 ## Delivering New Messages
  73
  74 Notmuch itself does not receive messages. There is no IMAP or POP support. You
  75 will need to set up other tools, such as fetchmail, offlineimap, or mbsync, to
  76 receive the messages.
  77
  78 There is two ways to deliver and index the messages:
  79
  80 * Use an external tool (such as offlineimap or mbsync) to deliver the messages
  81   to your mail store, and call `notmuch new` to discover and index the newly
  82   delivered messages (and any other changes in the mail store).
  83
  84 * Use an external tool (such as fetchmail) receive the messages, and configure
  85   the tool to use `notmuch insert` to deliver the messages to your mail store
  86   and index them.
  87
  88 ## Automation Via Hooks
  89
  90 ## Backing up and Restoring the Database
  91
  92 ## Removing Notmuch
  93
  94 Did not like it after all? All you need to do is remove the database and the
  95 configuration file. The database is stored in the `.notmuch` directory under
  96 your mail store. And your mail store is at `notmuch config get database.path`.
  97
  98 Note that the database is where the tags are stored. Everything else can be
  99 regenerated by indexing again, but the tags will be lost when the database is
 100 removed. Use the `notmuch dump` command to create a backup of the tags.