From 043a8b583570c6d946373cd1c00acc4573cadd75 Mon Sep 17 00:00:00 2001 From: Oswald Buddenhagen Date: Thu, 9 Dec 2021 19:05:06 +0100 Subject: [PATCH] documentation tweaks manual: - explain what "rename on move" really means - reword "remote" to "opposite" to make it less confusing (possibly renaming TrashRemoteNew left as an exercise for later) - mention example mbsyncrc - consistently capitalize Store/Channel/Group where they refer to the respective configuration entities - emphasize that SyncState may need a trailing slash (as we do for Path) - fix missing mention of global usage/default for some options example mbsyncrc: - add big fat note that empty lines matter - stop demoing deprecated options - point out that CertificateFile is optional REFMAIL: 877dd11jb3.fsf@angela.anarc.at --- src/mbsync.1 | 52 ++++++++++++++++++++++++++------------------- src/mbsyncrc.sample | 13 ++++++++---- 2 files changed, 39 insertions(+), 26 deletions(-) diff --git a/src/mbsync.1 b/src/mbsync.1 index 267517a..8cc6eee 100644 --- a/src/mbsync.1 +++ b/src/mbsync.1 @@ -50,11 +50,11 @@ Read configuration from \fIfile\fR. By default, the configuration is read from ~/.mbsyncrc. .TP \fB-a\fR, \fB--all\fR -Select all configured channels. Any channel/group specifications on the command -line are ignored. +Select all configured Channels. Any Channel/Group specifications on the +command line are ignored. .TP \fB-l\fR, \fB--list\fR -Don't synchronize anything, but list all mailboxes in the selected channels +Don't synchronize anything, but list all mailboxes in the selected Channels and exit. .TP \fB-C\fR[\fBf\fR][\fBn\fR], \fB--create\fR[\fB-far\fR|\fB-near\fR] @@ -144,8 +144,7 @@ Unix-like forward slashes. .SS All Stores These options can be used in all supported Store types. .br -In this context, the term "remote" describes the second Store within a Channel, -and not necessarily a remote server. +The term "opposite Store" refers to the other Store within a Channel. .br The special mailbox \fBINBOX\fR exists in every Store; its physical location in the file system is Store type specific. @@ -208,14 +207,15 @@ See \fBRECOMMENDATIONS\fR and \fBINHERENT PROBLEMS\fR below. .TP \fBTrashNewOnly\fR \fByes\fR|\fBno\fR When trashing, copy only not yet propagated messages. This makes sense if the -remote Store has a \fBTrash\fR as well (with \fBTrashNewOnly\fR \fBno\fR). +opposite Store has a \fBTrash\fR as well (with \fBTrashNewOnly\fR \fBno\fR). (Default: \fBno\fR) . .TP \fBTrashRemoteNew\fR \fByes\fR|\fBno\fR -When expunging the remote Store, copy not yet propagated messages to this -Store's \fBTrash\fR. When using this, the remote Store does not need an own -\fBTrash\fR at all, yet all messages are archived. +When expunging the opposite Store, copy not yet propagated messages to this +Store's \fBTrash\fR. +When using this, the opposite Store does not need an own \fBTrash\fR at all, +yet all messages are archived. (Default: \fBno\fR) . .SS Maildir Stores @@ -540,7 +540,7 @@ Note that \fBINBOX\fR is not matched by wildcards, unless it lives under \fBPath\fR. .br The mailbox list selected by \fBPatterns\fR can be overridden by a mailbox -list in a channel reference (a \fBGroup\fR specification or the command line). +list in a Channel reference (a \fBGroup\fR specification or the command line). .br Example: "\fBPatterns\fR\ \fI%\ !Trash\fR" . @@ -560,7 +560,7 @@ the actual date of the message) will be deleted first. Messages that are flagged (marked as important) and (by default) unread messages will not be automatically deleted. If \fIcount\fR is 0, the maximum number of messages is \fBunlimited\fR -(Default: \fI0\fR). +(Global default: \fI0\fR). . .TP \fBExpireUnread\fR \fByes\fR|\fBno\fR @@ -570,7 +570,7 @@ This ensures that you never miss new messages even after an extended absence. However, if your archive contains large amounts of unread messages by design, treating them as important would practically defeat \fBMaxMessages\fR. In this case you need to enable this option. -(Default: \fBno\fR). +(Global default: \fBno\fR). . .TP \fBSync\fR {\fBNone\fR|[\fBPull\fR] [\fBPush\fR] [\fBNew\fR] [\fBReNew\fR] [\fBDelete\fR] [\fBFlags\fR]|\fBAll\fR} @@ -586,7 +586,7 @@ Select the synchronization operation(s) to perform: a configured \fBMaxSize\fR. .br \fBDelete\fR - propagate message deletions. This applies only to messages that -are actually gone, i.e., were expunged. The affected messages in the remote +are actually gone, i.e., were expunged. The affected messages in the opposite Store are marked as deleted only, i.e., they won't be really deleted until that Store is expunged. .br @@ -622,6 +622,7 @@ row/column. For example, "\fBSync\fR\ \fBPullNew\fR\ \fBPullDelete\fR\ \fBPush\fR" will propagate message arrivals and deletions from the far side to the near side and any changes from the near side to the far side. +.br Note that it is not allowed to assert a cell in two ways, e.g. "\fBSync\fR\ \fBPullNew\fR\ \fBPull\fR" and "\fBSync\fR\ \fBPullNew\fR\ \fBDelete\fR\ \fBPush\fR" induce error messages. @@ -648,7 +649,8 @@ Note that for safety, non-empty mailboxes are never deleted. . .TP \fBExpunge\fR {\fBNone\fR|\fBFar\fR|\fBNear\fR|\fBBoth\fR} -Permanently remove all messages [on the far/near side] marked for deletion. +Permanently remove all messages [on the far/near side] which are marked +for deletion. See \fBRECOMMENDATIONS\fR below. (Global default: \fBNone\fR) . @@ -660,11 +662,11 @@ Enabling this makes sense in order to keep the time stamp based message sorting intact. Note that IMAP does not guarantee that the time stamp (termed \fBinternal date\fR) is actually the arrival time, but it is usually close enough. -(Default: \fBno\fR) +(Global default: \fBno\fR) . .P \fBSync\fR, \fBCreate\fR, \fBRemove\fR, \fBExpunge\fR, -\fBMaxMessages\fR, and \fBCopyArrivalDate\fR +\fBMaxMessages\fR, \fBExpireUnread\fR, and \fBCopyArrivalDate\fR can be used before any section for a global effect. The global settings are overridden by Channel-specific options, which in turn are overridden by command line switches. @@ -677,7 +679,8 @@ in the near side mailbox itself; this has the advantage that you do not need to handle the state file separately if you delete the mailbox, but it works only with Maildir mailboxes, obviously. Otherwise this is interpreted as a string to prepend to the near side mailbox -name to make up a complete path. +name to make up a complete path. Note that you \fBmust\fR append a slash if +you want to specify a directory. .br This option can be used outside any section for a global effect. In this case the appended string is made up according to the pattern @@ -702,7 +705,7 @@ used as mailbox name separators as well. . .TP \fBChannel\fR[\fBs\fR] \fIchannel\fR[\fB:\fIbox\fR[\fB,\fR...]] ... -Add the specified channels to the group. This option can be specified multiple +Add the specified Channels to the Group. This option can be specified multiple times within a Group. . .SS Global Options @@ -744,7 +747,7 @@ counters by default. The output will look like this: C: 1/2 B: 3/4 F: +13/13 *23/42 #0/0 N: +0/7 *0/0 #0/0 .in -4 .P -This represents the cumulative progress over channels, boxes, and messages +This represents the cumulative progress over Channels, boxes, and messages affected on the far and near side, respectively. The message counts represent added messages, messages with updated flags, and trashed messages, respectively. @@ -757,14 +760,14 @@ 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. +propagated by marking the messages as deleted in the opposite 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). +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 @@ -789,6 +792,10 @@ Mutt always does that, while mu4e needs to be configured to do it: .in +4 (setq mu4e-change-filenames-when-moving t) .in -4 +.br +The general expectation is that a completely new filename is generated +as if the message was new, but stripping the \fB,U=\fIxxx\fR infix is +sufficient as well. . .SH INHERENT PROBLEMS Changes done after \fBmbsync\fR has retrieved the message list will not be @@ -804,7 +811,8 @@ There is no risk as long as the IMAP mailbox is accessed by only one client .SH FILES .TP .B ~/.mbsyncrc -Default configuration file +Default configuration file. +See also the example file in the documentation directory. .TP .B ~/.mbsync/ Directory containing synchronization state files diff --git a/src/mbsyncrc.sample b/src/mbsyncrc.sample index afc274f..1bc9e38 100644 --- a/src/mbsyncrc.sample +++ b/src/mbsyncrc.sample @@ -4,6 +4,10 @@ Expunge None Create Both +# More sections follow +# +# !!!! Note that empty lines delimit sections !!!! + MaildirStore local Path ~/Mail/ Trash Trash @@ -32,7 +36,7 @@ Sync PullNew Push IMAPStore personal Host host.play.com Port 6789 -RequireSSL no +SSLType None Channel personal Far :personal: @@ -55,14 +59,14 @@ Channels work personal remote IMAPStore st1 Host st1.domain.com -RequireCRAM yes +AuthMech CRAM-MD5 +# Omit if you want to use the system certificate store. CertificateFile ~/.st1-certificate.crt IMAPStore st2 Host imap.another-domain.com Path non-standard/ -RequireSSL no -UseTLSv1 no +SSLVersions TLSv1.3 Channel rst Far :st1:somebox @@ -71,6 +75,7 @@ Near :st2: IMAPAccount server Host imaps:foo.bar.com +# Omit if you want to use the system certificate store. CertificateFile ~/.server-certificate.crt IMAPStore server