Unison Tutorial (Sync Files)

By Xah Lee. Date: 2007-03-30. Last updated: 2010-06-25.

Unison lets you sync files in both directions across 2 machines. For each file that differ, unison asks you which direction you want to overwrite for each difference in file/dir.

The rsync tool does just one way. (It overwrites any changes on the destination machine) 〔see Linux: rsync Tutorial〕

For brief into and history, see Wikipedia ~~https://en.wikipedia.org/wiki/Unison_(file_synchronizer)~~. Unison home page is at: http://www.cis.upenn.edu/~bcpierce/unison/docs.html .

Both machines must have unison installed.
Unison version must be the same on both machines (or, the versions being compatible).

unison -version: show version.
unison -help: list of options.
unison -doc topics: tutorial.
unison-2.32 …: Start a specific version.

Usually, you install multiple versions of Unison on the same machine.

Examples

Local Machine to Remote Machine

Here are some examples of commands that i actually use. I use it for syncing my local files and a remote server, both running OS X:

unison -servercmd /sw/bin/unison ~/uci-server/vmm -ignore "Name .DS_Store" ssh://xahlee@example.com//Library/WebServer/Documents/vmm

In this server, it contains works done by other people, so i can't just update it one-way with rsync.

-servercmd /sw/bin/unison specifies the path of the unison command on the server. (needed when it is not in the default search path on remote machine's user account)
~/uci-server/vmm is the local dir.
ssh://xahlee@example.com//Library/WebServer/Documents/vmm specifies the protocol to connect, login name, remote machine domain name, and dir.
-ignore "Name .DS_Store" tells it to ignore the Mac's temp file “.DS_Store”.

PC and Mac

Syncing my PC and Mac:

unison -servercmd /usr/bin/unison c:/Users/xah/web ssh://xah@169.254.145.104//Users/xah/web

If you are syncing from Mac and Windows, you many want to add -rsrc false, which will ignore resource fork and file type info.

Note that Unison as of version 2.27, it may have problems with file names containing Unicode chars. So, if you have files with Chinese chars, math symbols, etc, Unison will still work but the result file name will be gibberish. You might checkout the option “-unicode”.

Ignore Files and Ignore Permissions

You can use the “-ignore” option to ignore Mac's DS_Store file or emacs “*~” files. There can be multiple “-ignore” options. Examples:

-ignore "Name .DS_Store"
-ignore "Regex .+~"

When syncing among Windows and Unix, sometimes it is a pain to deal with permissions because they are different.

If you want to ignore file permissions, you can use -perms 0

Dir Ending in Slash or No?

WARNING: It is important to know whether directory path should end in a slash or not. Also, it makes a difference whether it is the source dir or destination dir.

For a example discussion of different semantics of this, see: Idiocy Of Unix Copy Command .

For many language and tools, with a slash or without a slash at the end means the same thing. However, for some tools it has different meanings, and their meanings may not be the same. For example, in rsync, the following:

rsync -r -v -t --delete --rsh="ssh -l xah" ~/Documents ~/web ~/Pictures ~/ErgoEmacs_Source ~/Shared ~/cinse_pixra3 xah@169.254.153.147:~/

If you added a slash in one of the source dir, the dir won't be copied over but only their children, resulting spam in the top level destination dir, or overwriting dirs of the same name.

If you missed the slash at the destination dir above, it will wipe out all dirs in the destination. (because the --delete option.)

Most tool's documentation usually isn't very clear or precise about this. Best thing to do is to test some sample cases yourself.