How to Use Unison for Syncing Files (Unison tutorial)

By Xah Lee. Date: ,

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: Sync Files Across Machines: rsync Tutorial

Unison logo

For brief into and history, see Wikipedia Unison. Unison home page is at: unison.

Both machines must have unison installed.

Unison version must be the same on both machines (or, the versions being compatible). Type: unison -version to find out what version you are running.

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

To start with a particular version, start you command like this: unison-2.32 ….


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://

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

PC and Mac

Syncing my PC and Mac:

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

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:

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@

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.