From a03b8bfbd26f4c71eaff359d10576afe012d3de1 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Sun, 26 Jul 2015 20:02:01 +0200 Subject: Reformulate introduction in the manpage. --- imapsync.1 | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) (limited to 'imapsync.1') diff --git a/imapsync.1 b/imapsync.1 index 8c22222..0f286ce 100644 --- a/imapsync.1 +++ b/imapsync.1 @@ -12,12 +12,12 @@ imapsync \- IMAP-to-IMAP synchronization program for QRESYNC-capable servers .B imapsync\fR performs stateful synchronization between two IMAP4rev1 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 -- cgit v1.2.3 From 66b0682010cf24a4d2e92465dd57bcd795d21970 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin 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 From 36b7d017145bac2f883cca12289e66b6b369a5e3 Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Mon, 27 Jul 2015 23:45:09 +0200 Subject: Enable fine-grained control on the mailboxes to consider. Add 3 options: - list-mailbox - list-select-opts - ignore-mailbox The first two control the initial LIST command, while the last one is a regular expression to filter out mailboxes to exclude from the LIST response. --- imapsync.1 | 46 ++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 44 insertions(+), 2 deletions(-) (limited to 'imapsync.1') diff --git a/imapsync.1 b/imapsync.1 index e274943..59093ef 100644 --- a/imapsync.1 +++ b/imapsync.1 @@ -73,8 +73,14 @@ Go back to step 1 to proceed with the next unsynchronized mailbox. .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. +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 @@ -181,6 +187,42 @@ This option is only available in the default section. (Default: \(lq\fIhost\fR.db\)\(rq, where \fIhost\fR is taken from the \(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 -- cgit v1.2.3 From ebeb0ba4c5cf3a6faccade5459db897ab7e50ecb Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Tue, 28 Jul 2015 00:47:32 +0200 Subject: typo --- imapsync.1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'imapsync.1') diff --git a/imapsync.1 b/imapsync.1 index 59093ef..b86c9e5 100644 --- a/imapsync.1 +++ b/imapsync.1 @@ -210,7 +210,7 @@ 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). +with children matching one of the \fIlist-mailbox\fR patterns above). This option is only available in the default section. .TP -- cgit v1.2.3 From 076792d13dbc93d374a0bbbb63901c5610278e7d Mon Sep 17 00:00:00 2001 From: Guilhem Moulin Date: Thu, 30 Jul 2015 00:07:07 +0200 Subject: Reformulation. --- imapsync.1 | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'imapsync.1') diff --git a/imapsync.1 b/imapsync.1 index b86c9e5..d794d1a 100644 --- a/imapsync.1 +++ b/imapsync.1 @@ -306,13 +306,14 @@ Authorities, used for server certificate verification. .IP \[bu] Using \fBimapsync\fR on two identical servers with a non-existent or -empty database will duplicate each message due to absence of +empty database will duplicate each message due to the absence of local/remote UID association. .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, -by sending independent commands (such as flag updates) in a pipeline. +pipelining. Synchronization could be boosted by sending independent +commands (such as the initial LIST/STATUS command) to each server in +parallel, and for a given server, by sending independent commands (such +as flag updates) in a pipeline. .IP \[bu] Because the IMAP protocol doesn't have a specific response code for when a message is moved to another mailbox (using the MOVE command from -- cgit v1.2.3