commit 8b2bc912b462f8b6b7444616a42288a3bd36c5e4
parent 4481702da300cebe1ebe94923f574c7b311bd292
Author: Oswald Buddenhagen <ossi@users.sf.net>
Date: Sat, 14 Dec 2013 12:37:11 +0100
elaborate on expunging and trashing
Diffstat:
1 file changed, 32 insertions(+), 2 deletions(-)
diff --git a/src/mbsync.1 b/src/mbsync.1
@@ -20,7 +20,7 @@
\" As a special exception, mbsync may be linked with the OpenSSL library,
\" despite that library's more restrictive license.
..
-.TH mbsync 1 "2013 Aug 3"
+.TH mbsync 1 "2013 Dec 14"
..
.SH NAME
mbsync - synchronize IMAP4 and Maildir mailboxes
@@ -167,7 +167,8 @@ under \fBPath\fR, including the "INBOX\fIdelim\fR" prefix.
.TP
\fBTrash\fR \fImailbox\fR
Specifies a mailbox (relative to \fBPath\fR) to copy deleted messages to
-prior to expunging. See \fBINHERENT PROBLEMS\fR below.
+prior to expunging.
+See \fBRECOMMENDATIONS\fR and \fBINHERENT PROBLEMS\fR below.
(Default: none)
..
.TP
@@ -483,6 +484,7 @@ does not exist.
.TP
\fBExpunge\fR {\fINone\fR|\fIMaster\fR|\fISlave\fR|\fIBoth\fR}
Permanently remove all messages [on the Master/Slave] marked for deletion.
+See \fBRECOMMENDATIONS\fR below.
(Global default: \fINone\fR)
..
.TP
@@ -549,6 +551,34 @@ in particular modern systems like ext4, btrfs and xfs. The performance impact
on older file systems may be disproportionate.
(Default: \fIyes\fR)
..
+.SH RECOMMENDATIONS
+Make sure your IMAP server does not auto-expunge deleted messages - it is
+slow, and semantically somewhat questionable. Specifically, Gmail needs to
+be configured not to do it.
+.P
+By default, \fBmbsync\fR will not delete any messages - deletions are
+propagated by marking the messages as deleted on the remote store.
+Once you have verified that your setup works, you will typically want to
+set \fBExpunge\fR to \fBBoth\fR, so that deletions become effective.
+.P
+\fBmbsync\fR's built-in trash functionality relies on \fBmbsync\fR doing
+the expunging of deleted messages. This is the case when it propagates
+deletions of previously propagated messages, and the trash is on the target
+store (typically your IMAP server).
+.br
+However, when you intend \fBmbsync\fR to trash messages which were not
+propagated yet, the MUA must mark the messages as deleted without expunging
+them (e.g., \fBMutt\fR's \fBmaildir_trash\fR option). Note that most
+messages are propagated a long time before they are deleted, so this is a
+corner case you probably do not want to optimize for. This also implies
+that the \fBTrashNewOnly\fR and \fBTrashRemoteNew\fR options are typically
+not very useful.
+.P
+If your server supports auto-trashing (as Gmail does), it is probably a
+good idea to rely on that instead of \fBmbsync\fR's trash functionality.
+If you do that, and intend to synchronize the trash like other mailboxes,
+you should not use \fBmbsync\fR's \fBTrash\fR option at all.
+..
.SH INHERENT PROBLEMS
Changes done after \fBmbsync\fR has retrieved the message list will not be
synchronised until the next time \fBmbsync\fR is invoked.
