= unison2.48

Unison is a file synchronizer for Unix and Windows. It allows two replicas of a
collection of files and directories to be stored on different hosts (or
different disks on the same host), modified separately, and then brought up to
date by propagating the changes in each replica to the other.

== Unison versions and packages

Unison comes in several complementary packages for Cygwin:

Package name  Unison version  Executable name       OCaml version
------------  --------------  --------------------  -------------
unison2.27     2.27.*         /usr/bin/unison-2.27  ?
unison2.32     2.32.*         /usr/bin/unison-2.32  ?
unison2.40     2.40.*         /usr/bin/unison-2.40  ?
unison2.45     2.45.*         /usr/bin/unison-2.45  ?
unison2.48     2.48.*         /usr/bin/unison-2.48  4.08.1
unison2.49     2.49.*         /usr/bin/unison-2.49  ?
unison2.51     2.51.*         /usr/bin/unison-2.51  ?

Separate packages and executables are needed because Unison's protocol for
exchanging information on the network is incompatible between these versions.
Two versions of Unison are compatible if and only if the first two numbers in
their version strings are the same.  For example, all versions 2.48.* are
compatible with each other, and incompatible with versions 2.51.*.  If you try
to use e.g. Unison version 2.48.4 to synchronize with a server running version
2.51.2, Unison will issue an error message about incompatible versions and quit.
By installing one or more of the packages listed above, you can run whichever
version you need in order to synchronize with your server.

The package postinstallation script uses alternatives(8) to install a symlink
/usr/bin/unison that points to one of the above-named executables.  By default
this symlink will track the highest-numbered version of Unison that you install
on your system, unless you reset it, either manually or using alternatives(8).
See alternatives(8) for more details.

If the server provides multiple versions of Unison, then you can invoke Unison
on the client with e.g. '-servercmd /usr/bin/unison-2.48' to run the version
you want on the server, or put 'servercmd /usr/bin/unison-2.48' into the
client's preference file.

== OCaml versions

There is unfortunately another layer of incompatibility in Unison: Two Unison
executables are only compatible if they were built with the same version of
OCaml, even if they have the same Unison versions. If you use, say, Unison 2.48
on two different hosts, but one was built with OCaml 4.08.1 and the other with
OCaml 4.10.0, you'll get the dreaded error message

  Fatal error: Fatal error during unmarshaling (input_value: ill-formed
  message), possibly because client and server have been compiled with different
  versions of the OCaml compiler.

This is a bad feature, of OCaml apparently. It means that in order to be sure of
being able to sync with another host, we could potentially need a separate
Unison package for every combination of Unison and OCaml versions.

For now, Unison packages are being built with the OCaml version that seems to
make them most generally compatible with other Linux distros. The OCaml versions
are documented in the table above. Packages with "?" for the OCaml version are
older builds, where the OCaml version isn't currently known.

For more about the OCaml version incompatibility problem, see
http://lists.seas.upenn.edu/pipermail/unison-hackers/2020-August/001972.html .

== User interface

All of the Unison packages for Cygwin use the text UI.  There is also a GTK2 UI
for Unison, but I haven't been able to get it working yet under Cygwin.  At some
time in the future I may make unison-gtk2 packages available for Cygwin.

Source home page:   http://www.cis.upenn.edu/~bcpierce/unison/
Source download:    http://www.cis.upenn.edu/~bcpierce/unison/download/releases/unison-2.48/unison-2.48.tar.gz
Cygwin maintainer:  Andrew Schulman <schulman.andrew@epa.gov>
License:            GPL

Please address questions and bug reports to the Cygwin mailing list
<cygwin@cygwin.com>.
