= unison2.48+4.08.1

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.

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

== Unison versions and packages

Unison comes in several complementary packages for Cygwin:

Package name       Unison version  OCaml version  Unison executable
------------       --------------  -------------  -----------------
unison2.27         2.27.*          4.01.0         /usr/bin/unison-2.27
unison2.32         2.32.*          4.01.0         /usr/bin/unison-2.32
unison2.40         2.40.*          4.02.3         /usr/bin/unison-2.40
unison2.45         2.45.*          4.01.1         /usr/bin/unison-2.45
unison2.48+4.04.2  2.48.*          4.04.2         /usr/bin/unison-2.48+4.04.2
unison2.48+4.08.1  2.48.*          4.08.1         /usr/bin/unison-2.48+4.08.1
unison2.49         2.49.*          4.02.3         /usr/bin/unison-2.49
unison2.51         2.51.*          4.04.2         /usr/bin/unison-2.51

You can install any number of these packages side-by-side. Separate packages are
needed because in order to synchronize your files, you have to run compatible
versions of Unison on the client and server. Two Unison executables are
compatible if and only if:

(1) They have the same first two numbers of the Unison version. For example, all
Unison versions 2.48.* are compatible with each other. But if you try to use
version 2.51.x to sync with a server running version 2.48.y, Unison will issue
an error message about incompatible versions and quit.

AND

(2) They were built with compatible versions of the OCaml compiler. OCaml has
changed its format over time for "marshaling" or serializing data. If you run
Unison executables that were built with OCaml versions that use different
marshaling formats, even if the Unison versions are the same, 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.

Apparently OCaml introduced breaking changes to its marshaling format in
versions 4.08 and 4.11. So versions pre-4.08, between 4.08 and 4.11, or
post-4.11 should be mutually compatible. But this hasn't been tested much. For
discussion of OCaml version incompatibilities, see
https://lists.seas.upenn.edu/pipermail/unison-hackers/2020-August/001972.html .

By installing one or more of the packages listed above, you can run whichever
version you need in order to synchronize with your server. If you need a
different combination of Unison and OCaml versions than is available in the
current packages, please send a report to cygwin@cygwin.com. It may be possible
to create a new package for it.

== Setting a default version

The package postinstallation scripts use 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. You can change that using alternatives:

  alternatives --config unison

(recommended) or manually. See "man alternatives" for 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.

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