Mutagen logo

Mutagen

Mutagen is a cross-platform, continuous, bidirectional file synchronization utility designed to be simple, robust, and performant. It can operate locally or over SSH.

Source Code | License | Download


On a lighter note: Mutagen is looking for testers, and it will definitely reach its full potential in the near future. If you want to follow Mutagen's development status then please star and follow it on GitHub!

Installation

Download the appropriate release for your platform and add its contents to your path. There is no need to install Mutagen on remote systems. Basic usage information is available through the built-in help.


$ mutagen --help
usage: mutagen [-V|--version] [-h|--help] [-l|--legal] <command> [<args>]

Supported commands include:

    create          Start a new synchronization session
    list            List current synchronization sessions
    monitor         Perform live monitoring of a synchronization session
    pause           Pause a synchronization session
    resume          Resume a synchronization session
    terminate       Stop and remove a synchronization session
    daemon          Control the synchronization daemon lifecycle

To see help for a particular command, use 'mutagen <command> --help'.

Initialization

Mutagen has a small daemon component that runs on a per-user basis in the background and performs watching, synchronization, and reconnection. The daemon is started using the daemon command.


$ mutagen daemon

This command is fast and idempotent, so it can safely be added to your shell initialization script (.bashrc, etc). The daemon will automatically stop at shutdown, but you can also manually stop it using mutagen daemon -s.

Creating a synchronization session

Mutagen creates synchronization sessions between two endpoints (alpha and beta) via the create command. Endpoints can be local or remote (via SSH).


$ mutagen create --ignore='**/.git' /local/path user@somewhere:~/remote/path
Connecting to agent
user@somewhere's password:

Whatever content the endpoint URLs point to will be kept in sync, be it files or directories. All non-conflicting changes (including deletions!) to either side will be propagated to the other.

Listing sessions

The list command shows the current status of each session, 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
Ignored paths:
        **/.git
Status: Watching for changes
Alpha:
        URL: /local/path
        Status: Connected
Beta:
        URL: user@somewhere:~/remote/path
        Status: Connected

Monitoring a session

The monitor command shows live monitoring information for a session.


$ mutagen monitor 7bb4a56b-f4be-4083-be24-7f590beda02e
Session: 7bb4a56b-f4be-4083-be24-7f590beda02e
Ignored paths:
        **/.git
Alpha: /local/path
Beta: user@somewhere:~/remote/path
Staging files on alpha: 75% (8942/11782)

Pausing a session

Synchronization can be temporarily halted using the pause command.


$ mutagen pause 7bb4a56b-f4be-4083-be24-7f590beda02e

Resuming a session

Sessions can be resumed via the resume command. This command will ensure that a session is unpaused and synchronizing. If the daemon can't automatically reconnect to an endpoint because authentication is required, the resume command can be used to provide credentials.


$ mutagen resume 7bb4a56b-f4be-4083-be24-7f590beda02e
Connecting to agent
user@somewhere's password:

Terminating a session

Synchronization can be permanently halted for a session (and the session removed) using the terminate command. This will not delete files on either endpoint (but should be done before completely deleting files on either endpoint to avoid propagating the complete deletion).


$ mutagen terminate 7bb4a56b-f4be-4083-be24-7f590beda02e