Merge branch 'master' into debian

1 files changed, 45 insertions, 10 deletions

diff --git a/doc/interimap.1.md b/doc/interimap.1.md
index 387850a..ee92668 100644
--- a/doc/interimap.1.md
+++ b/doc/interimap.1.md
@@ -85,7 +85,10 @@ However if some extra argument are provided on the command line,
 `interimap` ignores these options and synchronizes the given
 *MAILBOX*es instead.  Note that each *MAILBOX* is taken “as is”; in
 particular, it must be [UTF-7 encoded][RFC 2152], unquoted, and the list
-wildcards ‘\*’ and ‘%’ are passed verbatim to the IMAP server.
+wildcards ‘\*’ and ‘%’ are passed verbatim to the IMAP server.  If the
+local and remote hierarchy delimiter differ, then within the *MAILBOX*
+names the *local* delimiter should be used (it is transparently
+substituted for remote commands and responses).
 
 If the synchronization was interrupted during a previous run while some
 messages were being replicated (but before the `UIDNEXT` or
@@ -175,10 +178,11 @@ Options
 
 `--debug`
 
-:   Turn on debug mode.  Debug messages are written to the given *logfile*.
-    Note that this include all IMAP traffic (except literals).
-    Depending on the chosen authentication mechanism, this might include
-    authentication credentials.
+:   Turn on debug mode.  Debug messages, which includes all IMAP traffic
+    besides literals, are written to the given *logfile*.  The `LOGIN`
+    and `AUTHENTICATE` commands are however redacted (in order to avoid
+    disclosing authentication credentials) unless the `--debug` flag is
+    set multiple times.
 
 `-h`, `--help`
 
@@ -245,7 +249,13 @@ Valid options are:
     Two wildcards are available, and passed verbatim to the IMAP server:
     a ‘\*’ character matches zero or more characters, while a ‘%’
     character matches zero or more characters up to the hierarchy
-    delimiter.
+    delimiter.  Hardcoding the hierarchy delimiter in this setting is
+    not advised because the server might silently change it at some
+    point. A null character should be used instead.  For instance, if
+    *list-mailbox* is set `"foo\x00bar"` then, assuming the hierarchy
+    delimiter is ‘/’, only the mailbox named `foo/bar` is considered for
+    synchronization.
+
     This option is only available in the default section.
     (The default pattern, `*`, matches all visible mailboxes on the
     server.)
@@ -266,7 +276,10 @@ Valid options are:
 :   An optional Perl Compatible Regular Expressions ([PCRE]) covering
     mailboxes to exclude: any ([UTF-7 encoded][RFC 2152] and unquoted)
     mailbox listed in the initial `LIST` responses is ignored if it
-    matches the given expression.
+    matches the given expression after trimming the reference names and
+    substituting the hierarchy delimiter with the null character.  For
+    instance, specifying `^virtual(?:\x00|$)` excludes the mailbox named
+    “virtual” as well as its descendants.
     Note that the *MAILBOX*es given as command-line arguments bypass the
     check and are always considered for synchronization.  This option is
     only available in the default section.
@@ -277,6 +290,19 @@ Valid options are:
     default these messages are written to the error output.)  This
     option is only available in the default section.
 
+*log-prefix*
+
+:   A `printf`(3)-like format string to use as prefix for each log
+    message.  Interpreted sequences are `%n` and `%m`, expanding
+    respectively to the component name (*local*/*remote*) and to the
+    name of the mailbox relevant for the log entry.  Conditions on a
+    specifier `%X` can be obtained with `%?X?then?` or `%?X?then&else?`,
+    which expands to *then* if the `%X` specifier expands to a non-empty
+    string, and to *else* (or the empty string if there is no else
+    condition) if it doesn't.  Literal `%` characters need to be escaped
+    as `%%`, while `&`, `?` and `\` characters need to be `\`-escaped.
+    (Default: `%?n?%?m?%n(%m)&%n?: ?`.)
+
 *type*
 
 :   One of `imap`, `imaps` or `tunnel`.
@@ -422,9 +448,10 @@ Known bugs and limitations
 
  * Using `interimap` on two identical servers with a non-existent or
    empty *database* will duplicate each message due to the absence of
-   local ↔ remote UID association.  Hence one needs to manually empty
-   the mail store on one end when migrating to `interimap` from another
-   synchronisation solution.
+   local ↔ remote UID association.  (Should they arise, an external tool
+   such as [`doveadm-deduplicate`(1)] can be used to weed them out.)
+   Hence one needs to manually empty the mail store on one end when
+   migrating to `interimap` from another synchronization solution.
 
  * `interimap` is single threaded and doesn't use IMAP command
    pipelining.  Synchronization could be boosted up by sending
@@ -439,6 +466,13 @@ Known bugs and limitations
    was deleted while another one (which is replicated again) was added
    to the other mailbox in the meantime.
 
+ * Because the [IMAP protocol][RFC 3501] doesn't provide a way for
+   clients to determine whether a disappeared mailbox was deleted or
+   renamed, `interimap` aborts when a known mailbox disappeared from one
+   server but not the other.  The `--delete` (resp. `rename`) command
+   should be used instead to delete (resp. rename) the mailbox on both
+   servers as well as within `interimap`'s internal database.
+
  * `PLAIN` and `LOGIN` are the only authentication mechanisms currently
    supported.
 
@@ -524,3 +558,4 @@ Standards
 [PCRE]: https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions
 [`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/ciphers.html
 [`verify`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/verify.html
+[`doveadm-deduplicate`(1)]: https://wiki.dovecot.org/Tools/Doveadm/Deduplicate