How to Use Unison for Syncing Files (Unison tutorial)

Perm url with updates:

How to Use Unison for Syncing Files (Unison tutorial)

Xah Lee, 2007-03, 2010-06-25

This page gives you some practical tips on using Unison for syncing files on a local machine and a remote server. (or 2 directories on the same machine)


Unison lets you sync files in both directions. The “rsync” tool does just one way sync. (It overwrites any changes on the destination machine) The “unison” asks you which direction you want to overwrite for each difference in file/dir.

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

Both machines must have unison installed.

  • Type “unison -help” for list of options.
  • Type “unison -doc topics” for tutorial on different topics.

Unison version must be the same on both machines. 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 OS X to remote OS X

Here are some examples of commands that i actually use. I use it for synching 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.

The “-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)

The “~/uci-server/vmm” is the local dir. The “ssh://” specifies the remote dir, remote machine's domain name, login account, and the protocol to use.

The -ignore "Name .DS_Store" tells it to ignore the Mac's temp file “.DS_Store”.

PC and Mac

Synching 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. If you want to ignore file permissions, you can use “-perms 0”.

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”.

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 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 --exclude="**/My *" --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 basically all dirs in the destination.

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

Popular posts from this blog

11 Years of Writing About Emacs

does md5 creates more randomness?

Google Code shutting down, future of ErgoEmacs