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
This commit is contained in:
Oswald Buddenhagen 2021-12-09 19:05:06 +01:00
parent 16db3498b3
commit 043a8b5835
2 changed files with 39 additions and 26 deletions

View File

@ -50,11 +50,11 @@ Read configuration from \fIfile\fR.
By default, the configuration is read from ~/.mbsyncrc. By default, the configuration is read from ~/.mbsyncrc.
.TP .TP
\fB-a\fR, \fB--all\fR \fB-a\fR, \fB--all\fR
Select all configured channels. Any channel/group specifications on the command Select all configured Channels. Any Channel/Group specifications on the
line are ignored. command line are ignored.
.TP .TP
\fB-l\fR, \fB--list\fR \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. and exit.
.TP .TP
\fB-C\fR[\fBf\fR][\fBn\fR], \fB--create\fR[\fB-far\fR|\fB-near\fR] \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 .SS All Stores
These options can be used in all supported Store types. These options can be used in all supported Store types.
.br .br
In this context, the term "remote" describes the second Store within a Channel, The term "opposite Store" refers to the other Store within a Channel.
and not necessarily a remote server.
.br .br
The special mailbox \fBINBOX\fR exists in every Store; its physical location The special mailbox \fBINBOX\fR exists in every Store; its physical location
in the file system is Store type specific. in the file system is Store type specific.
@ -208,14 +207,15 @@ See \fBRECOMMENDATIONS\fR and \fBINHERENT PROBLEMS\fR below.
.TP .TP
\fBTrashNewOnly\fR \fByes\fR|\fBno\fR \fBTrashNewOnly\fR \fByes\fR|\fBno\fR
When trashing, copy only not yet propagated messages. This makes sense if the 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) (Default: \fBno\fR)
. .
.TP .TP
\fBTrashRemoteNew\fR \fByes\fR|\fBno\fR \fBTrashRemoteNew\fR \fByes\fR|\fBno\fR
When expunging the remote Store, copy not yet propagated messages to this When expunging the opposite Store, copy not yet propagated messages to this
Store's \fBTrash\fR. When using this, the remote Store does not need an own Store's \fBTrash\fR.
\fBTrash\fR at all, yet all messages are archived. When using this, the opposite Store does not need an own \fBTrash\fR at all,
yet all messages are archived.
(Default: \fBno\fR) (Default: \fBno\fR)
. .
.SS Maildir Stores .SS Maildir Stores
@ -540,7 +540,7 @@ Note that \fBINBOX\fR is not matched by wildcards, unless it lives under
\fBPath\fR. \fBPath\fR.
.br .br
The mailbox list selected by \fBPatterns\fR can be overridden by a mailbox 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 .br
Example: "\fBPatterns\fR\ \fI%\ !Trash\fR" 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 that are flagged (marked as important) and (by default) unread
messages will not be automatically deleted. messages will not be automatically deleted.
If \fIcount\fR is 0, the maximum number of messages is \fBunlimited\fR If \fIcount\fR is 0, the maximum number of messages is \fBunlimited\fR
(Default: \fI0\fR). (Global default: \fI0\fR).
. .
.TP .TP
\fBExpireUnread\fR \fByes\fR|\fBno\fR \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, However, if your archive contains large amounts of unread messages by design,
treating them as important would practically defeat \fBMaxMessages\fR. In this treating them as important would practically defeat \fBMaxMessages\fR. In this
case you need to enable this option. case you need to enable this option.
(Default: \fBno\fR). (Global default: \fBno\fR).
. .
.TP .TP
\fBSync\fR {\fBNone\fR|[\fBPull\fR] [\fBPush\fR] [\fBNew\fR] [\fBReNew\fR] [\fBDelete\fR] [\fBFlags\fR]|\fBAll\fR} \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. a configured \fBMaxSize\fR.
.br .br
\fBDelete\fR - propagate message deletions. This applies only to messages that \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 Store are marked as deleted only, i.e., they won't be really deleted until
that Store is expunged. that Store is expunged.
.br .br
@ -622,6 +622,7 @@ row/column. For example,
"\fBSync\fR\ \fBPullNew\fR\ \fBPullDelete\fR\ \fBPush\fR" will propagate "\fBSync\fR\ \fBPullNew\fR\ \fBPullDelete\fR\ \fBPush\fR" will propagate
message arrivals and deletions from the far side to the near side and any message arrivals and deletions from the far side to the near side and any
changes from the near side to the far side. 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. 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\ \fBPull\fR" and
"\fBSync\fR\ \fBPullNew\fR\ \fBDelete\fR\ \fBPush\fR" induce error messages. "\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 .TP
\fBExpunge\fR {\fBNone\fR|\fBFar\fR|\fBNear\fR|\fBBoth\fR} \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. See \fBRECOMMENDATIONS\fR below.
(Global default: \fBNone\fR) (Global default: \fBNone\fR)
. .
@ -660,11 +662,11 @@ Enabling this makes sense in order to keep the time stamp based message
sorting intact. sorting intact.
Note that IMAP does not guarantee that the time stamp (termed \fBinternal 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. date\fR) is actually the arrival time, but it is usually close enough.
(Default: \fBno\fR) (Global default: \fBno\fR)
. .
.P .P
\fBSync\fR, \fBCreate\fR, \fBRemove\fR, \fBExpunge\fR, \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. can be used before any section for a global effect.
The global settings are overridden by Channel-specific options, The global settings are overridden by Channel-specific options,
which in turn are overridden by command line switches. 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 to handle the state file separately if you delete the mailbox, but it works
only with Maildir mailboxes, obviously. only with Maildir mailboxes, obviously.
Otherwise this is interpreted as a string to prepend to the near side mailbox 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 .br
This option can be used outside any section for a global effect. In this case 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 the appended string is made up according to the pattern
@ -702,7 +705,7 @@ used as mailbox name separators as well.
. .
.TP .TP
\fBChannel\fR[\fBs\fR] \fIchannel\fR[\fB:\fIbox\fR[\fB,\fR...]] ... \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. times within a Group.
. .
.SS Global Options .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 C: 1/2 B: 3/4 F: +13/13 *23/42 #0/0 N: +0/7 *0/0 #0/0
.in -4 .in -4
.P .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. affected on the far and near side, respectively.
The message counts represent added messages, messages with updated flags, The message counts represent added messages, messages with updated flags,
and trashed messages, respectively. and trashed messages, respectively.
@ -757,14 +760,14 @@ slow, and semantically somewhat questionable. Specifically, Gmail needs to
be configured not to do it. be configured not to do it.
.P .P
By default, \fBmbsync\fR will not delete any messages - deletions are 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 Once you have verified that your setup works, you will typically want to
set \fBExpunge\fR to \fBBoth\fR, so that deletions become effective. set \fBExpunge\fR to \fBBoth\fR, so that deletions become effective.
.P .P
\fBmbsync\fR's built-in trash functionality relies on \fBmbsync\fR doing \fBmbsync\fR's built-in trash functionality relies on \fBmbsync\fR doing
the expunging of deleted messages. This is the case when it propagates the expunging of deleted messages. This is the case when it propagates
deletions of previously propagated messages, and the trash is on the target deletions of previously propagated messages, and the trash is on the target
store (typically your IMAP server). Store (typically your IMAP server).
.br .br
However, when you intend \fBmbsync\fR to trash messages which were not However, when you intend \fBmbsync\fR to trash messages which were not
propagated yet, the MUA must mark the messages as deleted without expunging 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 .in +4
(setq mu4e-change-filenames-when-moving t) (setq mu4e-change-filenames-when-moving t)
.in -4 .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 .SH INHERENT PROBLEMS
Changes done after \fBmbsync\fR has retrieved the message list will not be 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 .SH FILES
.TP .TP
.B ~/.mbsyncrc .B ~/.mbsyncrc
Default configuration file Default configuration file.
See also the example file in the documentation directory.
.TP .TP
.B ~/.mbsync/ .B ~/.mbsync/
Directory containing synchronization state files Directory containing synchronization state files

View File

@ -4,6 +4,10 @@
Expunge None Expunge None
Create Both Create Both
# More sections follow
#
# !!!! Note that empty lines delimit sections !!!!
MaildirStore local MaildirStore local
Path ~/Mail/ Path ~/Mail/
Trash Trash Trash Trash
@ -32,7 +36,7 @@ Sync PullNew Push
IMAPStore personal IMAPStore personal
Host host.play.com Host host.play.com
Port 6789 Port 6789
RequireSSL no SSLType None
Channel personal Channel personal
Far :personal: Far :personal:
@ -55,14 +59,14 @@ Channels work personal remote
IMAPStore st1 IMAPStore st1
Host st1.domain.com Host st1.domain.com
RequireCRAM yes AuthMech CRAM-MD5
# Omit if you want to use the system certificate store.
CertificateFile ~/.st1-certificate.crt CertificateFile ~/.st1-certificate.crt
IMAPStore st2 IMAPStore st2
Host imap.another-domain.com Host imap.another-domain.com
Path non-standard/ Path non-standard/
RequireSSL no SSLVersions TLSv1.3
UseTLSv1 no
Channel rst Channel rst
Far :st1:somebox Far :st1:somebox
@ -71,6 +75,7 @@ Near :st2:
IMAPAccount server IMAPAccount server
Host imaps:foo.bar.com Host imaps:foo.bar.com
# Omit if you want to use the system certificate store.
CertificateFile ~/.server-certificate.crt CertificateFile ~/.server-certificate.crt
IMAPStore server IMAPStore server