Add README file.

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..5db5b9e
--- /dev/null
+++ b/README
@@ -0,0 +1,59 @@
+imapsync performs stateful synchronization between two IMAP4rev1
+servers.  Such synchronization is made possible by the QRESYNC extension
+from [RFC7162]; for convenience reasons servers must also support
+LIST-EXTENDED [RFC5258], LIST-STATUS [RFC5819] and UIDPLUS [RFC4315].
+Furthermore, while imapsync can work with servers lacking support for
+LITERAL+ [RFC2088] and MULTIAPPEND [RFC3502], these extensions greatly
+improve performance by reducing the number of required round trips hence
+are recommended.
+
+
+Stateful synchronization is only possible for mailboxes supporting
+persistent message Unique Identifiers (UID) and persistent storage of
+mod-sequences (MODSEQ); any non-compliant mailbox will cause imapsync to
+abort.  Furthermore, because UIDs are allocated not by the client but by
+the server, imapsync needs to keep track of associations between local
+and remote UIDs for each mailbox.  The synchronization state of a
+mailbox consists of its UIDNEXT and HIGHESTMODSEQ values on each server;
+it is then assumed that each message with UID < $UIDNEXT have been
+replicated to the other server, and that the metadata (such as flags) of
+each message with MODSEQ <= $HIGHESTMODSEQ have been synchronized.
+Conceptually, the synchronization algorithm is derived from [RFC4549]
+with the [RFC7162, section 6] amendments, and works as follows:
+
+
+ 1. SELECT (on both servers) a mailbox the current UIDNEXT or
+    HIGHESTMODSEQ values of which differ from the values found in the
+    database (for either server).  Use the QRESYNC SELECT parameter from
+    [RFC7162] to list changes (vanished messages and flag updates) since
+    $HIGHESTMODSEQ to messages with UID<$UIDNEXT.
+
+ 2. Propagate these changes onto the other server: get the corresponding
+    UIDs from the database, then a/ issue an UID STORE + UID EXPUNGE
+    command to remove messages that have not already been deleted on
+    both servers, and b/ issue UID STORE commands to propagate flag
+    updates (send a single command for each flag list in order the
+    reduce the number of round trips).  (Conflicts may occur if the
+    metadata of a message has been updated on both servers with
+    different flag lists; in that case imapsync issues a warning and
+    updates the message on each server with the union of both flag
+    lists.)  Repeat this step if the server sent some updates in the
+    meantime.  Otherwise, update the HIGHESTMODSEQ value in the
+    database.
+
+ 3. Process new messages (if the current UIDNEXT value differ from the
+    one found in the database) by issuing an UID FETCH command and for
+    each message RFC822 body received, issue an APPEND command to the
+    other server on-the-fly.  Repeat this step if the server received
+    new messages in the meantime.  Otherwise, update the UIDNEXT value
+    in the database.  Go back to step 2 if the server sent some updates
+    in the meantime.
+
+ 4. Go back to step 1 to proceed with the next unsynchronized mailbox.
+
+
+Consult the manual for more information.
+
+imapsync is Copyright© 2015 Guilhem Moulin ⟨guilhem@fripost.org⟩, and
+licensed for use under the GNU General Public License version 3 or
+later.  See ‘COPYING’ for specific terms and distribution information.