Update MacPorts link

[notmuch-wiki] / getting-started.mdwn

diff --git a/getting-started.mdwn b/getting-started.mdwn
index 4bcc4ce9b6fca7d2299a6f8cf2a5d56ad056fe20..7cc7c31f4181225b67a4fb5598a08a07f3856828 100644 (file)
--- a/getting-started.mdwn
+++ b/getting-started.mdwn
@@ -8,6 +8,9 @@
 This is your friendly guide and tutorial to getting started with Notmuch. It
 will help you through the first steps of setting up Notmuch.
 
 This is your friendly guide and tutorial to getting started with Notmuch. It
 will help you through the first steps of setting up Notmuch.
 

+All Notmuch commands have [[manual pages|manpages]]. Please refer to them for
+details.
+

 ## Prerequisites
 
 In order to use Notmuch, you will need to have your email messages stored in
 ## Prerequisites
 
 In order to use Notmuch, you will need to have your email messages stored in


@@ -24,15 +27,15 @@ already have messages in this format.
 
 On Linux, the easiest way to install Notmuch is through your distribution's
 package repository. If you're installing Notmuch from a [git
 
 On Linux, the easiest way to install Notmuch is through your distribution's
 package repository. If you're installing Notmuch from a [git

-checkout](http://git.notmuchmail.org/git/notmuch) or a [source
-release](http://notmuchmail.org/releases/), please refer to the
-[INSTALL](http://git.notmuchmail.org/git/notmuch/blob/HEAD:/INSTALL) document.
+checkout](https://git.notmuchmail.org/git/notmuch) or a [source
+release](https://notmuchmail.org/releases/), please refer to the
+[INSTALL](https://git.notmuchmail.org/git/notmuch/blob/HEAD:/INSTALL) document.

 
 ## Configuration
 
 To configure Notmuch, just run
 
 
 ## Configuration
 
 To configure Notmuch, just run
 

-       notmuch
+        notmuch

 
 This will interactively guide you through the setup process, and save the
 configuration to `$HOME/.notmuch-config`. If you'd like to change the
 
 This will interactively guide you through the setup process, and save the
 configuration to `$HOME/.notmuch-config`. If you'd like to change the


@@ -45,7 +48,7 @@ This step only modifies the configuration file.
 
 Notmuch needs a search database to operate. The next step is to run
 
 
 Notmuch needs a search database to operate. The next step is to run
 

-       notmuch new
+        notmuch new

 
 to index all your messages in the search database. The database will be stored
 in `.notmuch` directory under your mail store. The database is not a replacement
 
 to index all your messages in the search database. The database will be stored
 in `.notmuch` directory under your mail store. The database is not a replacement


@@ -66,10 +69,59 @@ interface|manpages]], or [[Notmuch Emacs interface|notmuch-emacs]].
 
 ## Converting Existing mbox to Maildir
 
 
 ## Converting Existing mbox to Maildir
 

+The [`mb2md`](http://batleth.sapienti-sat.org/projects/mb2md/) tool can be used
+to convert existing mbox files to Maildir.
+
+Beware that the source and destination directory options to `mb2md` are relative
+to the user's home directory, not relative to the current working directory.
+

 ## Delivering New Messages
 
 ## Delivering New Messages
 

+Notmuch itself does not receive messages. There is no IMAP or POP support. You
+will need to set up other tools, such as fetchmail, offlineimap, or mbsync, to
+receive the messages.
+
+There are two ways to deliver and index messages:
+
+* Use an external tool (such as offlineimap or mbsync) to deliver the messages
+  to your mail store, and run `notmuch new` to discover and index the newly
+  delivered messages (and any other changes in the mail store).
+
+* Use an external tool (such as fetchmail) receive the messages, and configure
+  the tool to use `notmuch insert` as a Mail Delivery Agent to deliver the
+  messages to your mail store and index them.
+

 ## Automation Via Hooks
 
 ## Automation Via Hooks
 

-## Backing up and Restoring the Database
+Notmuch supports running [[user defined hooks|manpages/notmuch-hooks-5]] before
+or after certain commands. Hooks can be arbitrary executable programs or
+scripts. For example, if you always run your mail delivery tool first and
+`notmuch new` after that, you can run the tool from Notmuch `pre-new` hook, and
+simply run `notmuch new` to do both. If you always do some tagging after
+indexing of new messages, you may want to set up a `post-new` or `post-insert`
+hook to do that automatically.
+
+## Backing Up and Restoring the Database
+
+The Notmuch database contains a search index of your messages, along with all
+the tags you've added to your messages. The search index can be regenerated by
+indexing the messages again, but the tags will be lost if the database is
+lost. (If you have `maildir.synchronize_flags` configuration option enabled,
+also some of the tags can be regenerated from maildir flags.)
+
+To create a plain-text dump of the tags, run
+
+        notmuch dump --output=dump.txt
+
+To restore the tags from the dump, run
+
+        notmuch restore --input=dump.txt

 
 ## Removing Notmuch
 
 ## Removing Notmuch

+
+Did not like it after all? All you need to do is remove the database and the
+configuration file. The database is stored in the `.notmuch` directory under
+your mail store. And your mail store is at `notmuch config get database.path`.
+
+You may want to use the `notmuch dump` command to create a backup of any tags
+you've added before removing the database.