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:
parent
16db3498b3
commit
043a8b5835
52
src/mbsync.1
52
src/mbsync.1
|
@ -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
|
||||||
|
|
|
@ -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
|
||||||
|
|
Loading…
Reference in New Issue
Block a user