Mutagen is a fast file synchronization tool designed for remote development. It is designed to replace tools like SSHFS, Unison, and SFTP editor plugins.
Mutagen uses a bidirectional version of the rsync algorithm to synchronize the filesystem contents at two locations. Each location can be either a local filesystem location or a remote location accessible via SSH. Filesystem contents are monitored for changes on both endpoints and any non-conflicting changes are propagated automatically.
Mutagen is unique amongst synchronizers in that it does not need to be installed on remote systems, has no dependencies, and runs completely in user space (no pesky kernel extensions required). It also has some nifty safety features to avoid accidental data deletion.
Although it can synchronize any content efficiently, Mutagen is tailored for synchronizing code for remote development. It handles cross-platform quirks by default, manages conflicts safely, and provides powerful configuration options for handling things like symlinks and ignores in a portable fashion.
Mutagen is also extremely robust to connection dropouts. Since the contents it deals with exist on the actual filesystem, they won't disappear or become unavailable if the connection drops, and they can continue to be accessed and edited offline. As soon as Mutagen can reconnect, it will automatically resume synchronization right where it left off.
Mutagen can manage any number of active synchronization sessions at once. It provides a number of subcommands that allow for the creation and management of sessions, as well as management of Mutagen's daemon component. The following sections outline usage of these commands. Additional usage information is available through the built-in help:
$ mutagen --help
More detailed information about Mutagen's design can be found in the README.
Mutagen can be installed by downloading the appropriate release for your platform and adding its contents to your path.
Alternatively, Homebrew users can install Mutagen with:
$ brew install havoc-io/mutagen/mutagen
There is no need to install Mutagen on remote systems.
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 endpoint, the daemon will automatically attempt to reconnect the session in the background.
The Mutagen daemon is started using the
$ mutagen daemon start
This command is fast and idempotent, so it can safely be
added to your shell initialization script
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
Experimental support for registering the daemon to start
automatically on login is available for macOS and
Windows via the
mutagen daemon register
Sessions can be created using the
$ mutagen create Projects/my_project user@hostname:~/my_project_copy
The locations specified can be local paths or SCP-style URLs. The order of the locations is not important — it only determines which will be referred to as "alpha" and which will be referred to as "beta."
Mutagen uses OpenSSH under the hood,
so all of your configuration, keys, and aliases will be
automatically available. If authentication is required
to connect to a remote endpoint, then the
create command will ask for credentials.
Each session is assigned a unique identifier that can be used to refer to it in subsequent commands. Sessions can also be referred to by a fragment of either endpoint path or hostname, so long as this specification is unambiguous.
list command shows the current status
of sessions, as well as any conflicts or problems that
have arisen in the propagation of changes between
$ mutagen list my_project 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
If no sessions are specified to the
command, it will simply print all sessions. More
detailed listing output is available through 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,
show information for the most recently created session.
Synchronization can be temporarily halted for a session
$ mutagen pause my_project
Sessions can be resumed using the
$ 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 because
authentication is required, the
command can be used to provide credentials.
Synchronization can be permanently halted for a session
(and the session deleted) using the
$ 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 the deletion).