Unlike traditional file copying and synchronization tools, Mutagen doesn’t have
the notion of “source” and “destination” locations. Instead, it conceptualizes
synchronization as occurring between two endpoints whose identities are
determined by the order in which they are specified to the
create command (the
first endpoint is identified as “alpha” and the second endpoint is identified as
“beta”) and whose roles are determined based on the “synchronization mode”
specified for the corresponding synchronization session.
Mutagen provides four different synchronization modes:
two-way-safe(Default): In this bidirectional synchronization mode, both endpoints are treated with equal precedence, and conflicts are only automatically resolved if they don’t result in data loss (e.g. modifications on one endpoint can can overwrite deletions of the corresponding content on the other endpoint). If conflicts can’t be automatically resolved, they are stored in the session state (and can be enumerated with the
two-way-resolved: This is the same as
two-way-safe, except that the alpha endpoint automatically wins all conflicts, including cases where alpha’s deletions would overwrite beta’s modifications or creations. No conflicts can occur in this synchronization mode.
one-way-safe: In this unidirectional synchronization mode, changes are only allowed to propagate from alpha to beta. Deletions on beta are overwritten by content from alpha (i.e. the content comes right back), but modifications and creations on beta can’t be overwritten by alpha (unless both endpoints have made the same modifications or created the same content). Conflicting contents on beta that can’t be overwritten will be recorded to the session state (and can be enumerated with the
listcommand). Extra content on beta that doesn’t conflict with contents on alpha is simply ignored.
one-way-replica: In this unidirectional synchronization mode, beta becomes an exact replica of alpha. Any modifications or additional content on beta are instantly overwritten or removed, respectively. No conflicts can occur in this synchronization mode.
These modes can be specified on a per-session basis by passing the
-m/--sync-mode=<mode> flag to the
create command. These modes can be
specified on a default per-session basis by including the following
[sync] mode = "<mode>"
Conflicts (which can occur in
one-way-safe modes) can be
resolved manually by deleting the content on the endpoint which you wish to lose
the conflict. Once deleted, the conflict will no longer exist since deletions
can be overwritten.