From 66b0682010cf24a4d2e92465dd57bcd795d21970 Mon Sep 17 00:00:00 2001
From: Guilhem Moulin <guilhem@fripost.org>
Date: Mon, 27 Jul 2015 22:02:17 +0200
Subject: No longer try to guess whether a mailbox was deleted or renamed.

This was too error-prone.  Instead, abort if a naming conflict occurs,
and provide explicit commands --delete and --rename to delete or rename
a mailbox.
---
 imapsync.1 | 57 +++++++++++++++++++++++++++++++++++++++------------------
 1 file changed, 39 insertions(+), 18 deletions(-)

(limited to 'imapsync.1')

diff --git a/imapsync.1 b/imapsync.1
index 0f286ce..e274943 100644
--- a/imapsync.1
+++ b/imapsync.1
@@ -4,7 +4,7 @@
 imapsync \- IMAP-to-IMAP synchronization program for QRESYNC-capable servers
 
 .SH SYNOPSIS
-.B imapsync\fR [\fIOPTION\fR ...] [\fIMAILBOX\fR ...]
+.B imapsync\fR [\fIOPTION\fR ...] [\fICOMMAND\fR] [\fIMAILBOX\fR ...]
 
 
 .SH DESCRIPTION
@@ -69,6 +69,7 @@ Go back to step 2 if the server sent some updates in the meantime.
 .IP \n+[step].
 Go back to step 1 to proceed with the next unsynchronized mailbox.
 
+.SH COMMANDS
 .PP
 By default \fBimapsync\fR synchronizes each mailbox listed by the
 \(lqLIST "" "*"\(rq IMAP command;
@@ -86,16 +87,15 @@ their flags have changed in the meantime.
 Finally, after propagating the offline changes for these messages,
 \fBimapsync\fR resumes the synchronization for the rest of the mailbox.
 
-.SH OPTIONS
-.TP
-.B \-\-config=\fR\fIFILE\fR
-Specify an alternate configuration file.  Relative paths start from
-\fI$XDG_CONFIG_HOME\fR, or \fI~/.config\fR if the XDG_CONFIG_HOME
-environment variable is unset.
+.PP
+Specifying one of the commands below makes \fBimapsync\fR perform an
+action other than the default QRESYNC-based synchronization.
 
 .TP
-.B \-\-repair
+.B \-\-repair \fR[\fIMAILBOX\fR ...]
 List the database anomalies and try to repair them.
+(Consider only the given \fIMAILBOX\fRes if non-optional arguments are
+provided.)
 This is done by performing a so\-called \(lqfull synchronization\(rq,
 namely 1/ download all UIDs along with their flags from both the local
 and remote servers, 2/ ensure that each entry in the database corresponds
@@ -106,6 +106,37 @@ duplicate).
 Flag conflicts are solved by updating each message to the union of both
 lists.
 
+.TP
+.B \-\-delete \fIMAILBOX\fR [...]
+Delete the given \fIMAILBOX\fRes on each target (by default each server
+plus the database, unless \fB\-\-target\fR specifies otherwise) where
+it exists.
+Note that per [RFC3501] deletion is not recursive: \fIMAILBOX\fR's
+children are not deleted.
+
+.TP
+.B \-\-rename \fISOURCE\fR \fIDEST\fR
+Rename the mailbox \fISOURCE\fR to \fIDEST\fR on each target (by default
+each server plus the database, unless \fB\-\-target\fR specifies
+otherwise) where it exists.
+\fBimapsync\fR aborts if \fIDEST\fR already exists on either target.
+Note that per [RFC3501] the renaming is recursive: \fISOURCE\fR's
+children are moved to become \fIDEST\fR's children instead.
+
+
+.SH OPTIONS
+.TP
+.B \-\-config=\fR\fIFILE\fR
+Specify an alternate configuration file.  Relative paths start from
+\fI$XDG_CONFIG_HOME\fR, or \fI~/.config\fR if the XDG_CONFIG_HOME
+environment variable is unset.
+
+.TP
+.B \fB\-\-target=\fR{local,remote,database}
+Limit the scope of a \fB\-\-delete\fR or \fB\-\-rename\fR command
+to the given target.  Can be repeated to act on multiple targets.  By
+default all three targets are considered.
+
 .TP
 .B \-q\fR, \fB\-\-quiet\fR
 Try to be quiet.
@@ -231,21 +262,11 @@ Authorities, used for server certificate verification.
 
 .SH KNOWN BUGS AND LIMITATIONS
 
-.IP \[bu] 2
-Mailbox deletion and renaming are not very well tested yet.
 .IP \[bu]
 Using \fBimapsync\fR on two identical servers with a non-existent or
 empty database will duplicate each message due to absence of
 local/remote UID association.
 .IP \[bu]
-Detecting whether a mailbox has been renamed or deleted while
-\fBimapsync\fR wasn't running is done by looking for a mailbox with same
-UIDVALIDITY.  [RFC3501] describes the purpose of UIDVALIDITY as to let
-clients know when to invalidate their UID cache.  In particular, there
-is no requirement that two mailboxes can't share same UIDVALIDITY.
-However such a possibility would defeat \fBimapsync\fR's heuristic to
-detect whether a mailbox has been renamed or deleted offline.
-.IP \[bu]
 \fBimapsync\fR is single threaded and doesn't use IMAP command
 pipelining.  Performance improvement could be achieved by sending
 independent commands to each server in parallel, and for a given server,
-- 
cgit v1.2.3