Syncing with Unison

When it comes to synchronization tools, the first thing which comes to mind: there are a lot of them. Most of those tools have their use in different scenarios, like Dropbox for sharing of (limited amounts of) non-sensible data.

Here we take a look at Unison to sync various folders on our computer with an USB drive.

Why Unison?

Why should you care? Well, the Unison website lists a couple of features to answer that, such as:

  • portability; you can even sync an ordinary Windows laptop with a Unix server
  • no superuser privileges needed
  • network bandwith optimization
  • clear and precise specification
  • free & open source under the GNU Public License

However, these two features are the most notable and distinctive ones compared to most of the other tools:

Unlike simple mirroring or backup utilities, Unison can deal with updates to both replicas of a distributed directory structure. Updates that do not conflict are propagated automatically. Conflicting updates are detected and displayed.


Unison is resilient to failure. It is careful to leave the replicas and its own private structures in a sensible state at all times, even in case of abnormal termination or communication failures.

To summarize: Unison enables bi-directional syncing of documents on your desktop with an USB drive or your computer at work, in a simple to use commandline interface.


The latest stable version can be found on the official download mirror. However, we Homebrew users on Mac OS X simply do:

brew install unison
# <installation process>
unison -version
unison version 2.40.102


I recommend reading the Basic Concepts and the Tutorial of the documentation. From then on, you will mostly refer to the Reference Guide in normal use.

After you've tried to repeatedly sync two local directories while modifying files in the process, you're ready to create profiles in your .unison folder. To start with a template, you can fork my dotunison repo on Github and change the *.prf profiles as needed. The io.prf could be considered an advanced profile and includes most of the useful stuff for everyday use.

Going deeper

Here are some things I learned in the process of using Unison.


Most USB sticks are formatted with FAT, one of the few truly portable (if poorly featured) filesystems. We don't want Unison to consider file permissions, as FAT only supports a subset of the permissions compared to *nix systems:

perms = 0

You can also protect your sync folders from being wiped by accident, which can happen when dealing with mount points and removable media. To Unison, an unmounted drive looks like a missing directory, which is dutifully replicated to your local path. You can prevent this with:

mountpoint = <somefile>

From the docs about Mount Points and Removable Media:

To prevent accidents, Unison provides a preference called mountpoint. Including a line like [the obove] in your preference file will cause Unison to check, after it finishes detecting updates, that something actually exists at the path foo on both replicas; if it does not, the Unison run will abort.

Mac OS X

Syncing resource forks is not worth the hassle, so ignore them:

rsrc = false

Also, ignore those special OS X files wich even may be updated during a sync. Take a look at my ignores file.