Unison Sync Tool

AlexanderEder 23rd September 2017 at 10:07pm
en Publish

Keeps per created profile two directories, local (as well as mounted / connected as network drive) or remote, synchronized

Unison will not overwrite any file changed in both directories since the last synchronization without special configuration or permission. Unison shows an overview with the direction each change will be propagated to before starting the synchronization. This overview should in fact be used, to identify unexpected actions before they get done. This useful idea protects against accidental loss of data. If a file was changed in both directories, only the author / authors can estimate which change is more important or if both changes need to be merged manually. No algorithm can do that. Even if both files will be saved as backup somewhere, the questions where the backup is, whether the backup works and what happens with it on the next conflict of the same files, remain open. Even if all of this is no problem, a conflict can remain unnoticed. Is it discovered somtime later on, it's harder to remember the exact circumstances. A problem must always become visible as soon as possible. Unison behaves correctly here, because of its default of showing the overview before the actual change.

Some windows GUI binaries need the GTK libs. They get installed together with e.g. Gimp (in its installation's bin directory or 32\bin for 64 bit installations) or Pidgin. Since Unison does not have a windows installer, the simplest way to start Unison is copying the binaries into the directory with the GTK libs. A method without mixing programs that don't belong together is making a lnk file. Under Shortcut fill in the Start in field with the above mentioned Gimp path.

On some Android devices Unison reports always present lockfiles on the start of a profile. After you checked that this is false alarm, you can start Unison with the parameter --ignorelocks.

The Unison version on both sides of a remote synchronization should be as close as possible.

Android Device as Provider of a Local Path


Android Device as Unison Server

If you have shell access via SSH, e.g. with SSHelper, a Unison binary can be placed on the device that can be started by the other synchronization partner via the servercmd setting.

# Unison preferences
root = /home/yourlogin/Documents
root = ssh://yourotherlogin@
sshargs = -p 2222
servercmd = /data/data/com.arachnoid.sshelper/home/unison-2.48.4-linux-i386-text-static

Connect to Unison Server from Windows via ssh

Putty project's PLink binary equips windows with a ssh client. The command line parameters differ compared to a normal ssh client. The ssh2plink script ssh2plink.bat as sshcmd setting in a Unison profile puts that straight. You have to adapt the line set PLINKEXE=... to plink on your computer. If you use the ssh feature for passwordless login, you have to set the corresponding key file with sshargs = -i <path/to/key>

root = C:\Users\Yourlogin\Documents
root = ssh://yourotherlogin@
sshcmd = C:\Users\Yourlogin\path\to\ssh2plink.bat
sshargs = -i C:\Users\Yourlogin\.ssh\id_rsa.ppk

Adapt Filesystem Structure with Symlinks

The option follow = pathspec causes Unison to synchronize the content of the destination file or destination directory, not as usual the symlink itself. This way you can e.g. handle the content of different machines with different filesystem structures in one configuration file.

root = /home/user/opt/matchdestinationmachinedirs
root = /mnt/destinationmachine
fat = true
follow = Path {User/Documents/archive}
follow = Path {Public/*}

path = User/Documents/archive
path = Public/Documents
path = Public/Music
ignore = Path {Public/Music/Sample Music}
path = Public/Pictures
ignore = Name {Thumbs.db}
ignore = Name {desktop.ini}

Dir /home/user/opt/matchdestinationmachinedirs

User/Documents/archive -> /home/user/ar
Public/Documents -> /home/user/pubdocs
Public/Music -> home/user/Music
Public/Pictures -> /home/user/publish/pics

Build Unison for Target Architecture Yourself

There are no current binaries for arm devices. Because Unison is written in OCaml and, because of unknown type sizes in its configure script, OCaml is not cross compilable, one remaining way is using qemu with debootstrap. Example for 64 bit arm Debian Jessie:

mkdir debian-arm64
sudo debootstrap --foreign --arch arm64 jessie debian-arm64 http://ftp.de.debian.org/debian/
sudo apt install qemu-user-static
sudo cp /usr/bin/qemu-aarch64-static debian-arm64/usr/bin
sudo mount -t proc proc debian-arm64/proc
sudo chroot debian-arm64 qemu-aarch64-static /bin/dash
/debootstrap/debootstrap --second-stage
apt install gcc make
cd <OCAMLSRC> && make world.opt && make install
cd <UNISONSRC> && make UISTYLE=text STATIC=true

Now you have Unison without graphical interface for the chosen architecture. This is enough to start Unison as a server on an Android or NAS device. If you like to build Unison with graphical interface, you need lablgtk and don't specify an UISTYLE:

cd <LABLGTKSRC> && ./configure && make world && sudo make old-install
cd <UNISONSRC> && make STATIC=true

Clean Up Unison Working Directory

For each of the two root entries in every profile a ar... (archive) and a fp... (fingerprint) file gets created. For ten profiles in use the working directory ($HOME/.unison or %USERPROFILE%\.unison, adjustable via environment variable UNISON) thus contains 50 files: The ten profiles plus 2 * 10 ar... plus 2 * 10 fp.... If a profile has become unnecessary, gets deleted or a root entry changes, the corresponding archives and fingerprints are useless. The first three lines of an archive are enough to find the match.

user@computer:~/.unison$ head -3 ar02a985d21ec41da5c07fc6b034e16744 
Unison archive format 22
Archive for root //computer//media/user/USBStick/Documents synchronizing roots //computer//home/user/Documents, //computer//media/user/USBStick/Documents
Written at 2017-03-12 at  9:34:07 - Unicode case insensitive mode

So the above three lines of the file ar02a985d21ec41da5c07fc6b034e16744 show the archive for root //computer//media/user/USBStick/Documents out of the profile that keeps this directory in sync with //computer//home/user/Documents. If the profile gets obsolete, the archive can be deleted, too, as well as the fingerprints, whose filename must be fp02a985d21ec41da5c07fc6b034e16744. Now the second archive Archive for root //computer//home/user/Documents synchronizing roots //computer//home/user/Documents, //computer//media/user/USBStick/Documents and the fingerprint matching in filename can be deleted.

You can leave a message: