mutagen

Start a synchronization session between a local directory and a remote host

$ mutagen sync create --name=[session_name] /[path/to/local/directory]/ [user]@[host]:/[path/to/remote/directory]/

$ mutagen sync create --name=[session_name] /[path/to/local/directory]/ docker://[user]@[container_name]/[path/to/remote/directory]/

$ mutagen sync terminate [session_name]

$ mutagen project start

$ mutagen project terminate

$ mutagen project list

mutagen [GLOBAL_OPTIONS] command [command_options] [arguments]

Common commands:
mutagen sync create [OPTIONS] source_path destination_url
mutagen sync monitor [OPTIONS] [session_identifier]
mutagen sync terminate [OPTIONS] [session_identifier]
mutagen daemon start
mutagen project start [OPTIONS]

-m, --mode
    Sets the synchronization mode. Common modes include two-way-resolved (bidirectional with conflict resolution), one-way-replica (source to destination), and one-way-replica-pull (destination to source).

-i, --ignore
    Specifies paths to ignore during synchronization. Can be specified multiple times. Supports patterns similar to .gitignore.

--symlink-mode
    Determines how symlinks are handled. Options include portable (replicate symlinks as-is) or posix-raw (raw byte replication).

--watch-mode
    Configures how filesystem changes are detected. Options like portable (OS-native events) or no-watch (manual scanning required).

--file-mode
    Sets default permissions for synchronized files, in octal format (e.g., 0644).

--dir-mode
    Sets default permissions for synchronized directories, in octal format (e.g., 0755).

--name
    Assigns a friendly name to the synchronization session for easier identification and management.

--label
    Applies a label to the session. Can be used for filtering or grouping sessions, especially with mutagen project.

source_path
    The local path to synchronize from. Can be an absolute or relative path.

destination_url
    The remote URL to synchronize to, typically in the format [user@]host[:port][/path], or Docker/Kubernetes specific formats.

Mutagen is an advanced command-line tool designed for fast, robust, and cross-platform file synchronization, primarily accelerating remote development workflows. It establishes secure, bidirectional connections to keep files consistent between a local filesystem and a remote environment, such as Docker containers, Kubernetes pods, virtual machines, or remote servers. Unlike traditional tools like rsync or scp, Mutagen operates in real-time, detecting changes instantly and propagating them efficiently. This makes it ideal for software development, where code modifications need immediate reflection in a remote build or execution environment. Mutagen supports various synchronization modes (e.g., two-way-resolved, one-way-replica), includes sophisticated conflict resolution mechanisms, and offers robust error recovery. Its performance is highly optimized for handling a large number of small files and low-latency updates, using SSH for secure transport. It provides extensive configuration options for path ignoring, symlink handling, and watch modes, ensuring flexible and efficient synchronization.

Mutagen relies on a background mutagen daemon process, which must be running for synchronization sessions to operate. Initial synchronization of very large datasets or projects with an extremely high number of files can consume significant time and resources. While optimized, network latency and high rates of concurrent file changes can impact performance. Users should carefully understand synchronization modes and conflict resolution to avoid unexpected data behavior, especially in two-way-resolved mode. Path normalization differences between operating systems (e.g., Windows vs. Linux) can sometimes lead to subtle issues.

Mutagen operates using a persistent background daemon that manages all synchronization sessions. Commands like mutagen daemon start, mutagen sync list, mutagen sync monitor, and mutagen sync terminate are used to control and observe these sessions. Sessions can also be managed via project configurations.

For complex setups or project-specific configurations, Mutagen supports configuration files, typically named mutagen.yml or mutagen.toml. These files allow defining multiple synchronization sessions, labels, ignores, and other settings in a version-controllable manner using the mutagen project commands.

Developed by Mutagen.io, Mutagen emerged as an open-source solution to address the persistent challenges of slow and inefficient file synchronization in modern remote development environments, particularly with technologies like Docker Desktop, WSL, and various cloud-based virtual machines. Its development focused on performance, robustness, and cross-platform compatibility, aiming to provide a seamless 'native' development experience even when code resides remotely. It gained traction within the developer community due to its ability to significantly improve feedback loops and reduce friction in cloud-native and containerized development workflows. The project remains under active development with a focus on stability, performance, and new features.

rsync(1), ssh(1), scp(1), unison(1)