Synchronization modes

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.

Modes

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 list command).
  • 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 list command). 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 configuration in ~/.mutagen.toml:

[sync]
mode = "<mode>"

Conflict resolution

Conflicts (which can occur in two-way-safe and 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.