Synchronising multiple workspaces with Unison

This document describes how to synchronize multiple workspaces to a single unison server. If you're careful (and rigorous) about this you'll effectively be able to keep each of the workspaces synchronised.

You'll need to install unison. Before you do this, you should find out the exact version of the unison installation on your server. Your client version number must match this.

• Unison GUIs: This page has binary downloads for Unison GUIs. I downloaded the 2.27.57 GUI version from here though. There are many compiled OSX ports here

Alternatively you can install the latest version of unison using macports:

sudo port install unison

Before synchronizing for the first time you should set up a directory on the server that you will synchronize to. Assuming your home directory on the server is called /home/lorcan create a new folder called unison and a folder inside that called apple_home to which we will synchronise our workspace.

These instructions show how to synchronize a user's home directory to a remote server (called www.example.com in this example)

1. From the client computer (the machine who's workspace you want to back up), run Unison.
2. Create a new profile
   1. Enter a name for the profile, e.g. backup_home_directory
   2. Enter the name of the local root, e.g. /Users/lorcan
   3. Enter your remote user name and host (the username you use to log into the server you are backing up into and the host name of the server respectively)
   4. Enter the backup directory you created earlier, i.e., unison/apple_home
   5. Now save this profile (this will create a new file called backup_home_directory.prf in the .unison directory in your home directory)
3. You are now ready to synchronise. But, before you do you might want to tweak the setup…

Running Unison on its own synchronizes a lot of files that you probably don't want to save. We can tweak the unison settings slightly before we continue to synchronize. These settings are stored in .prf files in the .unison directory in your home directory (e.g., the example file created in this example is in /home/lorcan/.unison/.backup_home_directory.prf).

Looking at this file it should look something like this (this is only here as an illustration):

# Unison preferences file
root = /Users/lorcan
root = ssh://lorcan@www.example.com/unison/apple_home

We can add filters that tell unison to ignore certain files, either by their path or their name. If we are backing up a home directory there are certain files we probably don't want to synchronize, e.g., the Trash folder, any private (e.g., root owned) files, any subversion directorys or folders that are being backed up another way, or any large files that should not be transmitted over the network.

To ignore a file by name, e.g. .svn directories add the following line:

ignore = Name .svn

and to ignore a name by path, e.g., the Trash directory add the following line:

ignore = Path .Trash

You should also ignore the .unison directory with the following entry:

ignore = Path .unison

With these tweaks in place, unison should run faster first time around. By ignoring files and folders with the GUI interface further entries are added to your .prt file. You can always change things manually by editing that file directly.

The Unison GUI seems to have a few wrinkles still in it.

When synchronizing from an OSX install to a linux server for the first time, I get the following error:

Uncaught exception: *** -[NSCFArray objectAtIndex:]: index (0) beyond bounds (0)

The solution seems to be to run the command line version of unison (e.g., one installed with macports) to do an initial synchronization:

/opt/local/bin/unison test

This throws up the following warning about a first time synchronization:

Looking for changes
Warning: No archive files were found for these roots, whose canonical names are:
	/Users/lorcan/Documents
	//kind.ucd.ie//Volumes/Home/lorcan/backup/temp
This can happen either
because this is the first time you have synchronized these roots, 
or because you have upgraded Unison to a new version with a different
archive format.  

Update detection may take a while on this run if the replicas are 
large.

Unison will assume that the 'last synchronized state' of both replicas
was completely empty.  This means that any files that are different
will be reported as conflicts, and any files that exist only on one
replica will be judged as new and propagated to the other replica.
If the two replicas are identical, then no changes will be reported.

If you see this message repeatedly, it may be because one of your machines
is getting its address from DHCP, which is causing its host name to change
between synchronizations.  See the documentation for the UNISONLOCALHOSTNAME
environment variable for advice on how to correct this.

Donations to the Unison project are gratefully accepted: 
http://www.cis.upenn.edu/~bcpierce/unison

Complete your initial synchronization now and then rerun it through the GUI. Everything should not work fine. (TIP: you could ignore all suggestions on the command line interface and not actually synchronize anything and the GUI should still work second time around.)