Introduction
This cheatsheet provides a concise overview of common Mutagen commands, flags, and workflows to help you efficiently manage file synchronization in your development environment.
Basic Commands
Installation
Command (macOS using Homebrew):
brew install mutagen-io/mutagen/mutagen
Description:
Installs Mutagen on macOS via Homebrew. For other platforms, refer to the respective installation instructions in our tutorials.
Check Installation and Version
Command:
mutagen version
Description:
Displays the currently installed Mutagen version to verify that the installation was successful.
Sync Session Management
Create a Sync Session
Command Example:
mutagen sync create --name my-sync-session --ignore "node_modules/**" /path/to/local docker://container-name/path/in/container
Key Options:
--name
: Assigns a unique identifier to the sync session.--ignore
: Excludes files or directories (useful for ignoring unnecessary files).- Endpoints:
Specify the local source and target container path (use thedocker://
prefix for container endpoints).
List Active Sync Sessions
Command:
mutagen sync list
Description:
Lists all active sync sessions and their statuses. Use this to monitor your ongoing sessions.
Pause a Sync Session
Command:
mutagen sync pause my-sync-session
Description:
Temporarily suspends synchronization for the specified session, useful during maintenance.
Resume a Sync Session
Command:
mutagen sync resume my-sync-session
Description:
Restarts a previously paused sync session.
Terminate a Sync Session
Command:
mutagen sync terminate my-sync-session
Description:
Stops and removes the specified sync session, allowing you to start a new session if needed.
Advanced Options and Configuration
Sync Modes Overview
two-way-resolved
mode (Default): Synchronizes changes in both directions, ideal for collaborative workflows.one-way-safe
mode: Propagates changes only from the source to the destination, protecting source data.one-way-replica
mode: Mirrors the source exactly at the destination, useful for backups and deployment.
Additional Flags
Specifying Sync Mode:
--mode two-way-resolved
Multiple Ignore Patterns:
mutagen sync create --name my-sync --ignore "node_modules/**" --ignore "*.log" /local/path docker://container/path
Daemon Management:
mutagen daemon start
Ensure the Mutagen daemon is running to manage synchronization tasks.
Troubleshooting Tips
Duplicate Session Error:
If a session with the same name already exists, check with:mutagen sync list
and terminate the duplicate session:
mutagen sync terminate <session-name>
Command Not Recognized:
If themutagen
command isn’t found, ensure the installation directory is in your system’s PATH.Log Checks:
Enable detailed logging (refer to our Installation and Configuring Mutagen tutorial for more info) for troubleshooting issues.
Further Reading
Explore More Articles
Here are more articles from the same category to help you dive deeper into the topic.
Reuse
Citation
@online{kassambara2025,
author = {Kassambara, Alboukadel},
title = {Mutagen {Cheatsheet:} {Quick} {Reference} for {File}
{Synchronization}},
date = {2025-03-09},
url = {https://www.datanovia.com/learn/tools/mutagen/cheatsheet.html},
langid = {en}
}