README

notmuchsync
===========

notmuchsync synchronizes your notmuch tags with your maildir flags 
(or the other way around).

The source code is hosted is at http://github.com/spaetz/notmuchsync/.

Copyright (C) 2010 Sebastian Spaeth 
This program comes with ABSOLUTELY NO WARRANTY. It is released under
the GNU GPL v2 (or later).

Overview & Motivation
---------------------

It syncs (-s) your notmuch tags back to maildir tags, so that an email
you read with notmuch will appear as read on other clients (such as
your iphone or your webmail).

You can also "reverse sync" (-r) your maildir flags into the notmuch
database (e.g. on initial import you seldomly want all your emails
being tagged as unread). However doing this using notmuchsync is
likely to be somewhat slower than integrating patches into notmuch
that achieve the same on a "notmuch new".

notmuchsync can also purge (-p) your emails that you have tagged as
"delete" or "Maildir::trashed", ie, it will physically delete the mail
files.

System Requirements
-------------------

* a notmuch shared library (libnotmuch.so.*),
* the python bindings cnotmuch (http://pypi.python.org/pypi/cnotmuch),
* Python >=2.5.


Usage
-----

See syncscript.example for the script that I use in order to
synchronize my IMAP server with notmuch. I also run a periodic
"notmuchsync -p" in order to prune old mail files.

Usage: notmuchsync [options]
Options:
  --version         show program's version number and exit
  -h, --help        show this help message and exit
  -p, --prune       prune deleted mails (use --dryrun for no real action
  --dry-run         do not really modify notmuch db or mail files.
                    Works with -p -r -s commands
  --sync-deleted    Also sync "deleted"/trashed tag/flag (disabled by default)
                    Works with -r -s commands.
  -d, --debug       really verbose debug output
  -v, --log-errors  log only errors
  -q, --quiet       just a normal output

By default it will only look for mails from the last 30 days.
Use --all to look at earlier mails too.

Note that if timestamps are more than 30 days in the future,
we won't handle it.
    -a, --all       examine all mails for -r and -s rather than only the
                    last 30 days.
    -s, --sync      sync from notmuch tags to maildir flags.
                    "deleted" tag syncing disabled by default.
    -r, --revsync   sync tags from maildir to notmuch. Doing this via notmuch
                    sync is slower than integrating the patches into notmuch
                    which achieve the same. See e.g. http://github.com/spaetz
                    /notmuch-all-
                    feature/commit/cefea1f29aa6ec5789fc3b3ac4a37ba79ed9c37f
                    for one option to do that.
                    "deleted" tag syncing disabled by default.

Maildir flags
-------------
At end of filename, flags start with ":2,". New flags may be defined later.
Flags must be stored in ASCII order.
 
This one is handled by notmuchsync:
 * "S" (seen): the user has viewed this message.
 * "T" (delete): the user has moved this message to the trash (disabled by 
                 default, see --sync-deleted)
 * "D" (draft): the user considers this message a draft
 * "F" (flagged): user-defined flag; toggled at user discretion. 
 * "R" (replied): the user has replied to this message.

I don't know how to support these:
 * Flag "P" (passed): the user has resent/forwarded/bounced this msg.