Unison FAQ - General Questions

What are the differences between Unison and rsync?

Rsync is a mirroring tool; Unison is a synchronizer. That is, rsync needs to be told "this replica contains the true versions of all the files; please make the other replica look exactly the same." Unison is capable of recognizing updates in both replicas and deciding which way they should be propagated.

Both Unison and rsync use the so-called "rsync algorithm," by Andrew Tridgell and Paul Mackerras, for performing updates. This algorithm streamlines updates in small parts of large files by transferring only the parts that have changed.

What are the differences between Unison and VCS (Version Control Systems such as CVS, Subversion, git, etc.)?

Both VCSes and Unison can be used to keep a remote replica of a directory structure up to date with a central repository. Both are capable of propagating updates in both directions and recognizing conflicting updates. Unison and CVS in particular both use the rsync protocol for file transfer.

Unison's main advantage is being somewhat more automatic and easier to use, especially on large groups of files. CVS requires manual notification whenever files are added or deleted. Moving files is a bit tricky. And if you decide to move a directory... well, heaven help you.

The full-blown version control systems have many other features (version history, multiple branches, etc.) that Unison (which is just a file synchronizer) doesn't have.

Can Unison and CVS/SVN/git/etc. be used together?

Unison and a VCS can be used together. The easiest way is to replicate your files with Unison but keep your VCS repository on just one machine (and do a commit on that machine after each time you synchronize with Unison, if files in that directory have changed). More complex schemes are also possible (e.g., using a remote VCS server and checking in from any host with one of the replicas), but should be used with care. In particular, if you use a remote CVS server, it is important that you do _not_ tell Unison to ignore the files in the CVS subdirectory.

Another approach is to use "path" variables to tell Unison to sync folders containing files for which you don't need revision history, and just use your VCS to commit in folders where you do need to track changes in detail.

How long has Unison been around?

The very first version of Unison was written in a research language called Pict, in 1995. There was a Java version in 1997. Benjamin Pierce, Trevor Jim and Jerome Vouillon started working on the present codebase in Objective Caml in 1998.

Will unison behave correctly if used transitively? That is, if I synchronize both between host1:dir and host2:dir and between host2:dir and host3:dir at different times? Are there any problems if the "connectivity graph" has loops?

This mode of usage will work fine. As far as each "host pair" is concerned, filesystem updates made by Unison when synchronizing any other pairs of hosts are exactly the same as ordinary user changes to the filesystem. So if a file started out having been modified on just one machine, then every time Unison is run on a pair of hosts where one has heard about the change and the other hasn't will result in the change being propagated to the other host. Running unison between machines where both have already heard about the change will leave that file alone. So, no matter what the connectivity graph looks like (as long as it is not partitioned), eventually everyone will agree on the new value of the file.

The only thing to be careful of is changing the file again on the first machine (or, in fact, any other machine) before all the machines have heard about the first change -- this can result in Unison reporting conflicting changes to the file, which you'll then have to resolve by hand. The best topology for avoiding such spurious conflicts is a star, with one central server that synchronizes with everybody else.

Is it OK to run several copies of Unison concurrently?

This will work fine, as long as each running copy is synchronizing a different pair of roots (i.e., as long as each copy is using a different archive file).

What will happen if I do a local (or NFS, etc.) sync and some file happens to be part of both replicas?

It will look to Unison as though somebody else has been modifying the files it is trying to synchronize, and it will fail (safely) on these files.

What happens if Unison gets killed while it is working? Do I have to kill it nicely, or can I use kill -9? What if the network goes down during a synchronization? What if one machine crashes but the other keeps running?

Don't worry; be happy. See the section "Invariants" of the user manual.

What about race conditions when both Unison and some other program or user are both trying to write to a file at exactly the same moment?

Unison works hard to make these ``windows of danger'' as short as possible, but they cannot be eliminated completely without relying on (non-portable) support from the operating system.

What will happen if I run Unison after my archive files get deleted or damaged?

A missing or damaged archive is treated the same as a completely empty one. This means that Unison will consider all the files in both replicas to be new. Any files that exist only in one replica will be transferred to the other replica (because it will look as though they have just been created); files that exist on both replicas but have different contents will be flagged as conflicts; files that have the same contents on both replicas will simply be noted in the rebuilt archive. See also "-confirmbigdeletes" option and other safety measures.

Do you remember that other wiki about something really similar to Unison?

Feel free to list related projects on the WikiNode.

So, where is the Unison source code?

Because Unison is open source, anyone can look at the code (and developer documentation). It was formerly kept in a SVN repository at https://webdav.seas.upenn.edu/viewvc/unison/branches/, which still exists as an historical artifact (not updated since version 2.48). Unison is currently maintained in a GIT repository at https://github.com/bcpierce00/unison/.

I'm having trouble checking out the Unison source code from svn...

You should use the current git repository mentioned above. But if you must...

Geir Aalberg contributed this hint:

svn checkout of Unison fails with the following error:

~ $ svn checkout https://webdav.seas.upenn.edu/svn/unison
Error validating server certificate for 'https://webdav.seas.upenn.edu:443':
- The certificate is not issued by a trusted authority. Use the
  fingerprint to validate the certificate manually!
Certificate information:
- Hostname: webdav.seas.upenn.edu
- Valid: from Sep 17 22:47:26 2006 GMT until Sep 17 22:47:26 2009 GMT
- Issuer: Equifax Secure Certificate Authority, Equifax, US
- Fingerprint: fe:88:78:3c:ed:70:fa:5d:8a:d5:fc:0f:9b:b8:78:ad:67:30:6c:66
(R)eject, accept (t)emporarily or accept (p)ermanently?
svn: PROPFIND request failed on '/svn/unison'
svn: PROPFIND of '/svn/unison': Server certificate verification failed: issuer is not trusted (https://webdav.seas.upenn.edu)

The easiest way around this I've found is to run the follow command first, which enables you to accept the certificate permanently:

    svn list https://webdav.seas.upenn.edu/svn/unison

UnisonFAQGeneral