Sunday, September 29, 2013

Sync Files Across Your Macs With Unison

Awhile ago I wrote about Bittorrent Sync, basically your own bittorrent network for syncing your files on your home network. I wrote about it because they included a PowerPC binary with their Linux downloads, but unfortunately their OS X client required Intel so if you wanted to use this on your PowerPC Macs, they all had to be running Linux.

This left me still out to sea. I use a mix of Tiger and Debian machines, so Bittorrent Sync ultimately wasn't for me (it's also closed source and unavailable for security auditing). So having tired of SFTPing my files around and expending brain power to keep all the versions straight, I went looking for another option, one like Bittorrent Sync where I could sync on my home network and without involving the cloud.

At first I looked at rsync, venerable I guess you'd call it, not old :), but that offers mirroring, not two-way syncing. Finally I stumbled upon Unison, an rsync-like utility that's exactly what I need, two-way syncing, and it's multi-platform--Windows, Linux, OS X, everything.

You can get Unison in command line form or as a GUI. The command line can be installed with Macports or Tigerbrew on OS X and is in the Debian repositories. Debian also has the GUI, unison-gtk. Does that leave OS X out of the GUI party? No sirree. Universal binaries for Tiger and Leopard have been made available here, and the thing to note is you need the same version on all computers. Meaning if you install 2.32 on Tiger from the previous link, you also must have 2.32 on every other system you're syncing with. Fortunately Debian makes multiple version available for just this situation, so now I have 2.32-12 on my Tiger laptop and 2.32-52-gtk on my Jessie system (the 12 and 52 don't matter).

Using Unison is as simple or as complex as you want it. You can start by using the GUI app and then graduate to the command line for more complex operations which you can automate with cron jobs. But for now I'll give you a quick rundown of getting started with the GUI.

First, it's recommended you copy the folders you want to sync over to your target computer so you start out with identical folders. Then you start up the Unison GUI and create a profile. Here's an example for syncing my Tiger home folder with my Debian home folder on an iBook:

Unison profile on OS X

About the "Remote" part, note this is all done over SSH, so make sure you have Remote Login enabled in your OS X Sharing Preferences or have openssh-server running on Linux. Also note that SSH gives you rock-solid security (unless your password is "password"). For "Host", it could be or your computer's hostname.

Now save it, but say you don't want to sync everything in your home folder. What if you only want Documents, Music, and Pictures synced? You could create a separate profile for each folder or mess around with symlinks, but a much better way is to edit your .prf file to define those paths. In OS X you'll find it in ~/Library/Application Support/Unison, and in Linux it's in ~/.unison. Here's a simple example of my "powerbook to icebook.prf":

# Unison preferences file
root = /Users/dan
root = ssh://dan@icebook.local//home/dan

# folders to sync
path = Documents
path = Music
path = Pictures

# filenames to ignore
ignore = Name .DS_Store
ignore = Name .localized

# save log file somewhere, anywhere but the home
# folder
logfile = /Users/dan/Library/Logs/unison.log

The first three lines were created when we saved the profile in the GUI, but the rest were added. In the second section, I define the paths of the specific folders I want synced (you don't have to write out the full path as the root is already defined in the first section), the third section tells Unison to ignore those hidden .DS_Store and .localized files in OS X, and the last section tells it where to save the log file (the default is your home folder).

The only trouble I had was with spaces in the folder names. Say if I wanted to enter "path = Pictures/vacation photos" it won't work. Adding \ or enclosing with quotes didn't work, either, so the only solution I can think of is to eliminate the spaces in the original folder's name.

The procedure for all this is pretty much identical in the Debian GUI.

So now you want to get your sync on. So you start up Unison, double click your profile and perform the first syncing. Remember, you're starting out with identical folders, so the first sync is just Unison recording what's what. The only thing you have to note is the direction of the arrows. "-->" means local to remote and "<--" means remote to local. Mark all changes by clicking the left-to-right arrow, then click the "Go" button and it should finish shortly. From then on Unison should only transfer the files that have been changed, and only the parts of those files that need updating. That way you're not uploading huge files when you just need to update small parts of them.

This is also really useful for syncing to a USB thumb drive. You wanna minimize the writes, right? When setting up a profile for that, you just use the "Local" option instead of "Remote" and enter the drive's path. There are a couple of cautions for us PowerPC users, though, in syncing to a USB drive formatted as FAT32 (or any OS X to Windows syncing). Unison will give you errors about permissions and resource forks, so you want to add the following lines to your thumb drive profile:

perms = 0
rsrc = false

These will tell Unison to leave out permissions and resource forks. If you need to preserve resource forks, you can compress the file in a .sit container. And one more thing, when syncing make sure your drive is actually mounted, because if it isn't Unison will think the sync folder is empty and will attempt to delete your files. :o

Anyway, here are a few more links for further reading, including all about syncing more than two computers--star topology--and all that. Have fun!

Unison Manual
UNIX/Linux: HowTo Use unison File Synchronizer
File Synchronization with Unison
Unison - ArchWiki

(UPDATE: Note to self, when changing the names of folders, make sure to also change the corresponding folder names in my .prf file. Otherwise much confusion arises.)


  1. Thank you for this. As an alternative, I was able to install the sync client for OwnCloud on my iBookG4/Wheezy by temporarily allowing Synaptic to download the files from jessie. Described here

    1. Thanks for the link. I should do a post on Owncloud. Somebody also sent me a link on how to get the client working on Leopard: