Unison

References

• Homepage
• Manual
  • Unison manual is usually found locally at /usr/share/doc/unison*/ or obtained via unison -doc all|less.
  • Sample Profiles
• Download: all available versions
• Unison: Backup & synchronize files

Unison also has built-in help:

unison -help               # Brief help
unison -doc topics         # Get list of details documentation
unison -doc all            # Get the whole manual

Alternatives to Unison

• SyncThing (link fails in Opera)
• Bit-torrent Sync (see this tutorial)

Limitation

• (from the manual) Unison does not understand hardlinks. So copying a repo with hardlinks will just create a new repo where all hard-links are unique (unlinked) copies.

mkdir repo1 repo2
echo foo > repo1/foo
ln repo1/foo repo1/bar
unison -batch -ignorearchives repo1 repo2
find -type f -printf '%n %p\n'
# 2 ./repo1/foo
# 2 ./repo1/bar
# 1 ./repo2/foo
# 1 ./repo2/bar

Unison vs rsync

By default, Unison uses its own implementation of rsync algorithms for diffs-only transfer. But for whole-file copy of new file, this implementation is not very optimized. Unison can be configured to address these shortcomings.

Basic usage

• Synchronize two directories

unison <dir-a> <dir-b>

• Selecting files to synchronize
  • Synchronize home directory, using Ignore facility to skip some files.
  • Create a subdirectory called shared, and synchronize that directory only.
  • (Linux only) Create a subdirectory called shared, with symbolic links to other local directories, and synchronize that directory only using follow (making symlink transparent).
  • Synchronize home directory as root, using -path switch on the command line:

    unison /home/username ssh://remotehost//home/username -path shared
    

    The -path option can be used as many times as needed, to synchronize several files or subdirectories:

    unison /home/username ssh://remotehost//home/username \
        -path shared \
        -path pub \
        -path .netscape/bookmarks.html
    

    These -path arguments can also be put in your preference file.

Configuration tips

• On Samba / CIFS file system, ignore permissions:

perms = 0

In some cases, you also need to use the preferences dontchmod.

• When running unison with ssh, uses servercmd if unison is not found in the path:

servercmd = /usr/bin/unison

Basic Profile

Here we assume that all profiles will include the default one. If not, a more complex solution is to create a file .unison/common-prefs, that would be included by all profiles, including the default one.

Here a basic setup to backup pen usb stick on Cygwin:

~/.unison/default.prf (<file name="default.prf" tag="source">download</file>)

# Unison default preferences file

# Fastcheck - by default false on windows machine, and true on Unix machine.
# When true, uses modification date + file size as inone number. Otherwise do a full scan
fastcheck = true

# If any new preferences are added by Unison (e.g. 'ignore'
# preferences added via the graphical UI), then store them in the
# default profile file
addprefsto = default.prf

# Ignore file permissions (necessary on samba/CIFS fs)
perms = 0

# Make sure that both roots are mounted
mountpoint = .

# Common Ignore specification
ignore = Name System Volume Information

~/.unison/usb-pen-backup.prf (<file name="usb-pen-backup.prf" tag="source">download</file>)

# Roots of the synchronization
root = /cygdrive/f
root = /cygdrive/z

# Common include
include default.prf

Compile from sources

Compile on powerpc/arm

References:

• Instructions from Tom Booschaert ([1]).

These are instructions to compile unison from sources on NAS devices with powerpc/arm cpu, and using ipkg package management.

# install OCaml, Gnu C Compiler en Make:
ipkg install ocaml
ipkg install gcc
ipkg install make

# get Unison source and unpack:
wget http://www.seas.upenn.edu/~bcpierce/unison//download/releases/stable/unison-2.32.52.tar.gz
# Other versions:
# wget http://www.seas.upenn.edu/~bcpierce/unison//download/releases/unison-2.27.57/unison-2.27.57.tar.gz
# wget http://www.seas.upenn.edu/~bcpierce/unison//download/releases/unison-2.40.102/unison-2.40.102.tar.gz
tar -xzf unison-2.32.52.tar.gz

# use make to compile:
cd unison-2.32.52
make NATIVE=false UISTYLE=text

# copy executable to bin folder so it can be executed anywhere:
cp unison /opt/bin/

Compilation error

• Error /bin/sh: etags: not found can be freely ignored.
• When building with ocaml 3.12, we get the following error:

ocamlc -I lwt -I ubase -custom -g -c /root/build/tmp/unison-2.27.57/update.ml
File "/root/build/tmp/unison-2.27.57/update.ml", line 1, characters 0-1:
Error: The implementation /root/build/tmp/unison-2.27.57/update.ml
       does not match the interface update.cmi:
       Modules do not match:

This is a known bug. Patch file update.mli as follows (see [2]):

sed -ri '/^module NameMap : Map/s/Map.S/MyMap.S/' update.mli

• On ARM, we had the following error:

+ gcc -o 'unison'   '-Llwt' '-Lubase' '-L/opt/lib/ocaml'  '/tmp/camlprimed354e.c' '-lcamlstr' '-lunix' '-lutil' 'osxsupport.o' 'pty.o' '-lcamlrun' 
-I'/opt/lib/ocaml' -lm  -ldl  -lpthread
/opt/lib/gcc/arm-none-linux-gnueabi/4.2.3/../../../../arm-none-linux-gnueabi/bin/ld: Warning: /lib/libc.so.6: Unknown EABI object attribute 44
/opt/lib/gcc/arm-none-linux-gnueabi/4.2.3/../../../../arm-none-linux-gnueabi/lib/libdl.so: undefined reference to `_dl_tls_get_addr_soft@GLIBC_PRIVATE'

To fix it we temporarily link to a different libdl.so library [3]:

mv /opt/arm-none-linux-gnueabi/lib/libdl.so /opt/arm-none-linux-gnueabi/lib/libdl.so.old
ln -s /lib/libdl.so.2 /opt/arm-none-linux-gnueabi/lib/libdl.so
# Compile Unison with the new library:
make NATIVE=false UISTYLE=text
# Restore the library link
mv /opt/arm-none-linux-gnueabi/lib/libdl.so.old /opt/arm-none-linux-gnueabi/lib/libdl.so

test Unison

unison -version
# unison version 2.27.57
unison -selftest
# Contacting server...
# Connected [//Mnemosyne//root/test-a.tmp -> //Mnemosyne//root/test-b.tmp]
# Running internal tests...
# backups 1 (local)...
# backups 2...
# backups 2a...
# backups 3...
# backups 4...
# backups 5 (directories)...
# backups 6 (backup prefix/suffix)...
# links 1 (directories and links)...
# links 2 (symlink to nowhere)...
# Success :-)