Safety mechanisms

Mutagen has several best-effort safety mechanisms aimed at avoiding unintentional bulk content deletion or replacement. Each of these mechanisms detects an “irregular” condition during synchronization and halts the synchronization session. Resolving the irregular condition and resuming the session depends on the user’s intent. If the deletion or replacement is desired, then the session can be resumed by manually deleting the content that would be deleted or replaced and then invoking mutagen sync resume. In the case of accidental deletion, the synchronization session history can be reset (which will cause Mutagen see the undeleted content as new content and propagate it back to the other side) using the mutagen sync reset command. More generally, a synchronization session can simply be deleted and/or recreated if some other resolution behavior is necessary.

It’s important to note that these safety mechanisms don’t control directionality or conflict resolution in synchronization, which are instead controlled by the synchronization mode.

Root deletion

One of the changes that Mutagen avoids propagating is complete deletion of the synchronization root on one endpoint. This can be an indication of either accidental deletion or a non-persistent filesystem (such as a container filesystem). This detection is best-effort since directory deletion is non-atomic and Mutagen may see (and propagate) deletion of a large portion of a synchronization root before seeing that the entire root was deleted (though Mutagen does its best to avoid operating during concurrent file modifications when it detects them).

Root emptying

Mutagen also looks for cases where both synchronization endpoints are directories and one endpoint (but not both) deletes a non-trivial amount of content from the synchronization root and leaves it empty. This is generally an indication of a non-persistent filesystem (such as a container filesystem) being used as a synchronization root. This detection is best-effort for the same reasons described above.

Root type change

Finally, Mutagen looks for replacement of the synchronization root with a root of a different type on one endpoint. This avoids (for example) accidentally overwriting a large directory with a single file.