add page on message exclusion and deletion

and link from front page.

diff --git a/excluding.mdwn b/excluding.mdwn
new file mode 100644 (file)
index 0000000..9d8a5dd
--- /dev/null
+++ b/excluding.mdwn
@@ -0,0 +1,77 @@
+# Message exclusion and deletion
+
+An important principle of notmuch is that it does not modify your mail
+(with the one exception of
+[[maildir flag syncing|howto/#sync_maildir_flags]]).  A question that
+frequently comes up, though, is how users can delete messages.  While
+notmuch does not support, nor ever will, the deleting of messages,
+notmuch has a couple of nice features that allow users to handle
+excluding unwanted messages in a sensible way.
+
+## <span id="exclude>**message exclusion**</span>
+
+Notmuch has the ability to exclude message with certain tags from
+search results.  A common usage is to exclude "deleted" or "spam"
+messages so that they don't clutter your search results.  To enable
+excludes, use the config utility:
+
+       $ notmuch config set search.exclude_tags deleted spam
+
+This will cause messages with the "deleted" or "spam" tags to be
+excluded from search results.
+
+It is still possible to find messages with excluded tags, though, by
+manually including the excluded tag in your search:
+
+       $ notmuch search from:foo and tag:spam
+
+This will find messages from "foo" with the tag "spam", even though
+"spam" is an excluded tag.
+
+## <span id="files">**message files**</span>
+
+Notmuch makes it very easy to access the underlying mail files
+associated with specific search terms using the "file" output format
+of notmuch search.  To find all message files associated with the tag
+"foo" rung:
+
+       $ notmuch search --output=files tag:foo
+
+This will output the paths to all message files with "tag:foo", one
+per line.
+
+This is useful in a number of different ways.  For instance, it could
+be used to train a spam filter:
+
+       $ notmuch search --output=files tag:spam | sa-learn -f -
+
+It can also be used to purge mail files from disk:
+
+       $ notmuch search --output=files tag:deleted | xargs -l rm
+
+Make sure you run "notmuch new" after the last command so the database
+becomes aware that the files have been removed and can remove the
+corresponding entries from the index.
+
+## <span id="recipe>**putting it all together**</span>
+
+So if you want to add message deletion to your work flow, here's a
+procedure:
+
+* Add exclusion for messages with the "deleted" tag:
+
+       $ notmuch config set search.exclude_tags deleted
+
+* Add a key binding to your favorite ui to add a "deleted" tag to
+  messages that you want to delete.  In [[emacs|emacstips]] that might
+  be:
+
+       (define-key notmuch-show-mode-map "d"
+         (lambda ()
+               (interactive)
+               (notmuch-show-tag "+deleted")))
+
+* And, finally, if you _really_ want the messages purged from disk,
+  you can delete them manually with:
+
+       $ notmuch search --output=files tag:deleted | xargs -l rm

diff --git a/index.mdwn b/index.mdwn
index 8260c3b98a38dfab5c22920b83c007fbe1399c9b..4a55b784636d7e54164e9cf220f139f5c8268ada 100644 (file)
--- a/index.mdwn
+++ b/index.mdwn
@@ -57,9 +57,11 @@ docs:
 
   * [[General how-tos|howto]]
   * [[Available frontends|frontends]]
-  * [[Initial_Tagging]]
+  * [[Searching]]
+  * [[Excluding and deleting messages|excluding]]
+  * [[Initial tagging|Initial_Tagging]]
   * [[Tips for using notmuch within Emacs|emacstips]]
-  * [[Remote Usage|remoteusage]]
+  * [[Remote usage|remoteusage]]
   * [[Performance|performance]]
 
 Apart from the wiki, help is available via email.  Join the mailing