Merge branch 'master' into debian

1 files changed, 90 insertions, 44 deletions

diff --git a/imapsync.1 b/imapsync.1
index f4f6965..59093ef 100644
--- a/imapsync.1
+++ b/imapsync.1
@@ -4,21 +4,20 @@
 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
 .PP
 .B imapsync\fR performs stateful synchronization between two IMAP4rev1
-servers, then (unless the flag \fB\-\-oneshot\fR is set) keeps both
-connection open and wait for new changes to arrive.
+servers.
 Such synchronization is made possible by the QRESYNC extension from
-[RFC7162]; for convenience reasons support for LIST\-EXTENDED [RFC5258],
-LIST\-STATUS [RFC5819] and UIDPLUS [RFC4315] is also required.
-Furthermore, support for LITERAL+ [RFC2088] and MULTIAPPEND [RFC3502]
-is recommended: while they are not needed for \fBimapsync\fR to work,
-these extensions greatly improve performance by reducing the number of
-required round trips.
+[RFC7162]; for convenience reasons servers must also support
+LIST\-EXTENDED [RFC5258], LIST\-STATUS [RFC5819] and UIDPLUS [RFC4315].
+Furthermore, while \fBimapsync\fR 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.
 
 .PP
 Stateful synchronization is only possible for mailboxes supporting
@@ -70,20 +69,18 @@ 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;
-providing extra arguments limits the synchronization to the given
-\fIMAILBOX\fRes only.
-
-.PP
-In its default mode (unless the flag \fB\-\-oneshot\fR or
-\fB\-\-repair\fR is set), \fBimapsync\fR does not exit once all
-mailboxes have been synchronized.  Instead, it keeps both connection
-open and uses the NOTIFY command from [RFC5465] to be notified of new
-changes (on any mailbox) as soon as they arrive.  If no update is sent
-in 15 minutes, a NOOP command is issued in order not to trigger the
-servers' inactivity timeout and be logged out.
+the \fIlist-mailbox\fR, \fIlist-select-opts\fR and \fIignore-mailbox\fR
+options from the configuration file can be used to shrink that list and
+save bandwidth.
+However if some extra argument are provided on the command line,
+\fBimapsync\fR ignores said options and synchronizes the given
+\fIMAILBOX\fRes instead.  Note that each \fIMAILBOX\fR is taken \(lqas
+is\(rq; in particular, it must be UTF-7 encoded, unquoted, and the list
+wildcards \(oq*\(cq and \(oq%\(cq are not interpolated.
 
 .PP
 If the synchronization was interrupted during a previous run while some
@@ -96,23 +93,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.
-
-.TP
-.B \-1\fR, \fB\-\-oneshot\fR
-Exit as soon as all mailboxes are synchronized, instead of passively
-waiting for updates from the open connections.
-Using \fB\-\-oneshot\fR removes the requirement that IMAP servers must
-advertise support the NOTIFY extension [RFC5465].
+.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
@@ -124,6 +113,37 @@ 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.
 
@@ -168,6 +188,42 @@ This option is only available in the default section.
 \(lq[remote]\(rq or \(lq[local]\(rq sections, in that order.
 
 .TP
+.I list-mailbox
+A space separated list of mailbox patterns to use when issuing the
+initial LIST command (overridden by the \fIMAILBOX\fRes given as
+command-line arguments).
+Note that each pattern containing special characters such as spaces or
+brackets (see [RFC3501] for the exact syntax) must be quoted.
+Furthermore, non-ASCII names must be UTF\-7 encoded.
+Two wildcards are available: a \(oq*\(cq character matches zero or more
+characters, while a \(oq%\(cq character matches zero or more characters
+up to the mailbox's hierarchy delimiter.
+This option is only available in the default section.
+(The default pattern, \(lq*\(rq, matches all visible mailboxes on the
+server.)
+
+.TP
+.I list-select-opts
+An optional space separated list of selectors for the initial LIST
+command.  (Requires a server supporting the LIST-EXTENDED [RFC5258]
+extension.)  Useful values are
+\(lqSUBSCRIBED\(rq (to list only subscribed mailboxes),
+\(lqREMOTE\(rq (to also list remote mailboxes on a server supporting
+mailbox referrals), and \(lqRECURSIVEMATCH\(rq (to list parent mailboxes
+with children matching one of the \fIlist-mailbox\fR pattern above).
+This option is only available in the default section.
+
+.TP
+.I ignore-mailbox
+An optional Perl Compatible Regular Expressions (PCRE) covering
+mailboxes to exclude:
+any (UTF-7 encoded, unquoted) mailbox listed in the initial LIST
+responses is ignored if it matches the given expression.
+Note that the \fIMAILBOX\fRes given as command-line arguments bypass the
+check and are always considered for synchronization.
+This option is only available in the default section.
+
+.TP
 .I logfile
 A file name to use to log debug and informational messages.  This option is
 only available in the default section.
@@ -248,21 +304,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,