man: Add more complete description of one-way sync

diff --git a/doc/man/doveadm-sync.1.in b/doc/man/doveadm-sync.1.in
index 2d56391e63c966be533da6cab743bcc193c7363a..7b69bbe599ca14894d953e23d877b5b1ed018e42 100644 (file)
--- a/doc/man/doveadm-sync.1.in
+++ b/doc/man/doveadm-sync.1.in
@@ -74,6 +74,33 @@ multiple times, then switch mails to be delivered to the new mailbox and
 run
 .B doveadm sync \-1
 once more to transfer any last new mails from the old mailbox.
+.IP
+The one\-way algorithm is the same as two-way dsync algorithm except the
+source account is not modified. It fetches the message's GUID (Global UID),
+which is used to identify any conflicting UIDs in messages. As long as the
+source and destination side has matching UID<\->GUID mapping, those emails
+are assumed to be synced correctly. Only after the first mismatch will
+changes begin.
+.IP
+Example: Source mailbox has messages UID 1..5; source mailbox is sync'd
+using
+.B doveadm backup
+to the destination. Subsequently, UID 6 is delivered to the source mailbox
+and UID 1 is expunged from the destination mailbox. In this example, UID 1
+is kept removed (in destination) because UID 1..5 have identical
+Date+Message\-ID headers. UID 6 is not seen in destination so it's copied.
+.IP
+If both source and destination have UID 6, but the messages are different,
+the headers don't match and both the messages are kept in the destination but
+they're given new UIDs 7 and 8 just to be sure any client didn't get confused
+about what UID 11 actually was. Thus, one\-way sync begins to quickly diverge
+from the source mailbox once changes start to occur on either side; one\-way
+sync should therefore normally only be used within a short period of time
+after a
+.B doveadm backup
+or
+.B doveadm sync
+command was used to synchronize the mailboxes.
 .\"-------------------------------------
 .RE
 .PP