Automatically Syncing Files with Your Workspace

Keep files in sync between your local development environment and your workspace so you can edit locally and run remotely.

Mutagen (Recommended)

Mutagen provides real-time, bidirectional file synchronization with excellent performance. It handles large projects efficiently, detects conflicts, and works across macOS, Linux, and Windows.

Installation

# macOS
brew install mutagen-io/mutagen/mutagen

# Windows (via Scoop)
scoop install mutagen

See mutagen.io/documentation/introduction/installation for other platforms.

Creating a Sync Session

mutagen sync create ~/local/project wsm.my_workspace:/home/web/html \
  --ignore=.git \
  --ignore=node_modules \
  --ignore=vendor

This starts a persistent background session that watches for changes on both sides and syncs them automatically.

Managing Sessions

# List active sessions
mutagen sync list

# Monitor sync status in real time
mutagen sync monitor

# Pause a session
mutagen sync pause --all

# Resume a session
mutagen sync resume --all

# Terminate a session
mutagen sync terminate --all

Configuration File

For repeatable setups, create a mutagen.yml in your project root:

sync:
  defaults:
    ignore:
      paths:
        - ".git"
        - "node_modules"
        - "vendor"
        - "*.log"
  workspace:
    alpha: "."
    beta: "wsm.my_workspace:/home/web/html"
    mode: "two-way-resolved"

Then start with:

mutagen project start

Sync Modes

• two-way-safe (default) — Syncs both directions, flags conflicts for manual resolution
• two-way-resolved — Syncs both directions, alpha (local) wins on conflict
• one-way-safe — Local → remote only, won’t overwrite remote changes not yet synced back
• one-way-replica — Local → remote only, remote is an exact mirror

For most development workflows, two-way-resolved works well — your local edits take priority.

rsync

rsync is a simpler alternative for one-way synchronization or scripted workflows.

Basic Usage

# Push local changes to workspace
rsync -avz --progress ~/local/project/ wsm.my_workspace:/home/web/html/

# Pull workspace changes to local
rsync -avz --progress wsm.my_workspace:/home/web/html/ ~/local/project/

Automatic Sync with File Watching

macOS (fswatch)

brew install fswatch

#!/bin/bash
PROJECT_DIR="$HOME/local/project"
WORKSPACE="wsm.my_workspace:/home/web/html/"

fswatch -o "$PROJECT_DIR" | while read f; do
  rsync -avz --delete \
    --exclude '.git' \
    --exclude 'node_modules' \
    --exclude 'vendor' \
    "$PROJECT_DIR/" "$WORKSPACE"
done

Linux (inotifywait)

#!/bin/bash
PROJECT_DIR="$HOME/local/project"
WORKSPACE="wsm.my_workspace:/home/web/html/"

while inotifywait -r -e modify,create,delete,move "$PROJECT_DIR"; do
  rsync -avz --delete \
    --exclude '.git' \
    --exclude 'node_modules' \
    --exclude 'vendor' \
    "$PROJECT_DIR/" "$WORKSPACE"
done

Excluding Files

Use an exclude file (similar to .gitignore):

.rsyncignore

.git
node_modules
vendor
*.log
.env
.DS_Store

rsync -avz --exclude-from='.rsyncignore' \
  ~/local/project/ wsm.my_workspace:/home/web/html/

Or leverage your existing .gitignore:

rsync -avz --filter=':- .gitignore' \
  ~/local/project/ wsm.my_workspace:/home/web/html/

Caution

Be careful with --delete when pulling from remote — it will remove local files that don’t exist on the workspace.

Choosing Between Mutagen and rsync

	Mutagen	rsync
Direction	Bidirectional	One-way per invocation
Real-time	Yes (background daemon)	Requires file watcher script
Conflict handling	Built-in resolution	Manual
Performance	Optimized for large trees	Good, but re-scans on each run
Setup	One command	Script required for automation

Use Mutagen for day-to-day development. Use rsync for one-off transfers, CI scripts, or environments where you can’t install Mutagen.

Related Documentation

• SSH Access – Configure SSH access to workspaces
• Connecting JetBrains IDEs – Use JetBrains built-in sync
• Connecting Visual Studio Code – Use VS Code Remote-SSH