Design and usage

Mutagen is designed and operated around the concept of synchronization sessions. A session handles synchronization between an arbitrary pair of endpoints.1 Each endpoint is just a filesystem location, either local or remote, specified by a URL which Mutagen maps to one of its underlying transports. Mutagen monitors the filesystem contents at each of these locations and triggers a synchronization cycle any time a change is detected. These cycles are fast enough that content synchronizes in effectively real-time. Each cycle uses information about the most recently agreed-upon filesystem contents to identify changes and conflicts between the two endpoints.

Mutagen’s sessions are highly configurable, with various synchronization modes and configurable behavior for ignoring content, permission handling, symbolic link handling, and filesystem watching.

Mutagen can manage any number of concurrent synchronization sessions, and sessions can be as ephemeral or long-lasting as required. The mutagen command is designed entirely around managing session lifecycles. This guide provides an outline of the Mutagen session lifecycle by demonstrating the creation, modification, and termination of a Mutagen session.

This guide doesn’t aim to be an exhaustive exploration of the mutagen command, and many other options can be discovered in other parts of the documentation and via the command’s built-in help information:

$ mutagen --help
$ mutagen <command> --help

Starting the daemon

Mutagen relies on a daemon that runs in the background as a per-user process and manages synchronization sessions. If a session becomes disconnected from a remote system, the daemon will automatically attempt to reconnect the session in the background.

The Mutagen daemon is started using the daemon command:

$ mutagen daemon start

This command is fast and idempotent, so it can safely be added to your shell initialization script (e.g. .bashrc, etc).

The daemon will automatically stop at shutdown, but you can also manually stop it using mutagen daemon stop. Make sure to stop the daemon before upgrading Mutagen and to restart it afterwards.

Experimental support for registering the daemon to start automatically on login is available for macOS and Windows via the mutagen daemon register command.

Creating a synchronization session

Sessions can be created using the create command, e.g.:

$ mutagen create Projects/my_project user@hostname:~/my_project_copy

The create command takes two endpoint specifications and creates a synchronization session between them. The order of the endpoints determines their identities (the first is referred to as “alpha” and the second as “beta”) and the synchronization mode specified for the session determines their roles (for more information, see the Synchronization modes guide).

Endpoint specifications can be local paths, SSH-accessible locations, or Docker® container filesystem locations. They can refer to individual files or entire directory hierarchies - Mutagen can handle either. For SSH-accessible locations, Mutagen uses OpenSSH under the hood, so all of your settings, keys, and aliases will be automatically available. If confirmation or authentication is required to connect to a remote endpoint, then the create command will prompt accordingly.

Mutagen can create synchronization sessions between arbitrary pairs of endpoints — one needn’t be local. For example, you could set up synchronization between an SSH-accessible filesystem location and a Docker container filesystem location without ever having a copy of the files locally. The Mutagen daemon simply acts as a proxy and arbiter for endpoints.

Listing sessions

The list command shows the current status of sessions, as well as any conflicts or problems that have arisen in the propagation of changes between endpoints:

$ mutagen list
Session: 7bb4a56b-f4be-4083-be24-7f590beda02e
Alpha:
    URL: /Users/me/Projects/my_project
    Status: Connected
Beta:
    URL: user@hostname:~/my_project_copy
    Status: Connected
Status: Watching for changes

Each session is assigned a unique identifier that can be used to refer to it in Mutagen commands. This identifier will be printed by the create command and can be seen in the list command’s output. Sessions can also be referred to (in list and other commands) by a prefix of this identifier or a fragment of either endpoint’s path or hostname, so long as this specification is unambiguous.

If no sessions are specified to the list command, it will simply print all sessions. More detailed listing output is available through the -l/--long flag.

Monitoring a session

The monitor command shows live monitoring information for a session:

$ mutagen monitor my_project
Session: 7bb4a56b-f4be-4083-be24-7f590beda02e
Alpha: /Users/me/Projects/my_project
Beta: user@hostname:~/my_project_copy
Status: Staging files on beta: 75% (8942/11782)

If no session is specified, monitor will show information for the most recently created session.

Pausing sessions

Synchronization can be temporarily halted for a session using the pause command:

$ mutagen pause my_project

A session will remain paused until manually resumed.

Resuming sessions

Sessions can be resumed using the resume command:

$ mutagen resume my_project

This command will ensure that a session is unpaused and attempting to synchronize. If the daemon can’t automatically reconnect to an endpoint in the background because confirmation or authentication is required, the resume command can be used to provide the necessary input.

This command is also used to resume synchronization when Mutagen’s safety mechanisms detect a synchronization anomaly.

Flushing sessions

Synchronization cycles can be manually triggered for sessions using the flush command:

$ mutagen flush my_project

This command will manually trigger a synchronization cycle for the session. This is particularly useful when combined with the no-watch filesystem watching mode, allowing users to manually control when synchronization occurs and to integrate with external filesystem watching tools.

Terminating sessions

Synchronization can be permanently halted for a session (and the session deleted) using the terminate command:

$ mutagen terminate my_project

This will not delete files on either endpoint (but should be done before completely deleting files on either endpoint to avoid propagating any deletions).


1 Although Mutagen only synchronizes directly between two endpoints, multiple synchronization sessions involving a single location can be used to build more complex synchronization topologies, e.g. a star topology with a developer’s local copy at the center.