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