Bidirectional Sync Using Unison

Pavan Bagde

When it comes to syncing files across directories or devices, most developers and power users turn to time tested tool like rsync. It’s fast, efficient, and ideal for one way synchronization. But what if you need true bidirectional sync, where changes in either directory are reflected in the other, automatically resolving conflicts and preserving the most recent updates?

That’s where Unison comes in.

Why Not Just Use rsync?

rsync excels at unidirectional sync, usually from a source to a target. However, It does not fit for use-case of trying to have a mirrored locally mounted directories of two cloud providers:

  • If a file changes in both locations, rsync will overwrite one copy with the other.
  • Lacking Conflict resolution strategies.
  • Can’t sync between two local directories, There must be one remote location involved.

Enter Unison

Unison is a powerful file synchronization Which fits well for this use-case. It:

  • Works across local and remote machines.
  • Supports Linux, macOS, and Windows.
  • Tracks file changes and provide some strategies to resolves conflicts.
  • Can be customized for performance, backup behavior, conflict resolution, and logging.
  • Can use rsync under the hood for optimized file transfer, but have its own algorithms too.

Unison Wiki and manual for more in-depth options.

My Use Case

image

Sync a directory inside locally mounted iCloud, IDrive-cloud-drive directory on macOS as that is my primary machine.

I have some devices using icloud and some iDrive and wanted to have a shared directory between them with bidirectional sync.

  • An iCloud directory on my Mac.
  • An IDrive-synced directory elsewhere on disk.

This setup ensures I can work with files from multiple devices and have them mirrored in both cloud services.

Unison Installation and Configuration

On macOS unison can be installed using Homebrew.

brew install unison
iCloud directory path on macOS
/Users/pavan/Library/Mobile Documents/iCloud~md~SyncedFiles/Documents/SyncedFiles
iDrive directory path on macOS
/Users/pavan/Cloud-Drive/Docs/mastersync/SyncedFiles

To start we need to create a profile file for each set of directories we want to sync, for example we create a file named e.g. icloud-idrive-SyncedFiles, and store it where Unison expects to find them e.g. below location on macOS:

$HOME/Library/Application Support/Unison

Here’s a sample profile content that works for syncing two directorys (you can adapt the paths for your use case):

# Unison profile configuration
root = /Users/pavan/Library/Mobile Documents/iCloud~md~SyncedFiles/Documents/SyncedFiles
root = /Users/pavan/Cloud-Drive/Docs/mastersync/SyncedFiles

# Common options
batch = true
  
# Automatically accept default decisions for conflicts and other prompts (Danger: data loss possible)
auto = true

# auto resolve conflict by choosing the newer version of the file. (Danger: data loss possible )
prefer = newer

# Automatically confirm deletions of large files.
confirmbigdel = false

# Do not create copies of conflicted files.
copyonconflict = false

# Use a faster check for differences between files.
fastcheck = true

# Synchronize modification times of files.
times = true

# Don't synchronize file permissions.
perms = 0

# Central backup to avoid scattering backups across directories
backup = Name *
backuplocation = central
backupdir = /Users/pavan/unison/backup
maxbackups = 2

# Optional - Optimize for large files
copyprog = rsync --inplace --compress
copyprogrest = rsync --partial --inplace --compress

# Logging
log = /Users/pavan/unison/logs
logfile = true

ignore = Name .DS_Store
ignore = Path somePath/*

Once profile is created, with following command, directories can be mirrored as per the setup in profile:

unison icloud-idrive-SyncedFiles

Scheduling with Crontab

To run the sync automatically every hour, you can schedule it using macOS Crontab. This helps ensure your directories are always in sync without manual intervention.

⚠️ Caution When Ignoring Files

Warning: If you ignore a file or directory, do not rename it.
Since Unison tracks changes between sync points, renaming an ignored file may result in the file being deleted during the next sync cycle.

Copyprog Deprecation Notice

The copyprog and copyprogrest options in Unison—used to accelerate syncs via rsync—are being deprecated.

If you’re syncing large files and relying on these options, consider alternate methods or monitor future Unison versions for updated support.

With a bit of setup, Unison enables seamless two-way sync between icloud and iDrives locally mounted directories on multiple devices.