Unison File Synchronizer

Meta

Please read this entire README and
https://github.com/bcpierce00/unison/wiki/Reporting-Bugs-and-Feature-Requests
before creating or commenting on a github issue.

TL;DR: Do not ask questions or ask for help in issues. Upgrade to the latest release.

For compatibility information with version 2.52, see
https://github.com/bcpierce00/unison/wiki/2.52-Migration-Guide

About

Unison is a file-synchronization tool for POSIX-compliant systems
(e.g. *BSD and GNU/Linux), macOS and Windows, with the caveat that the
platform must be supported by OCaml. 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 has been in use for over 20 years and many people use it to
synchronize data they care about.

Unison shares a number of features with tools such as configuration
management packages (CVS, Subversion, git, Mercurial, etc.),
distributed filesystems (Coda, etc.), uni-directional mirroring
utilities (rsync, etc.), and other synchronizers. However, there are
several points where it differs:

• Unison runs on almost any system with an OCaml compiler. Moreover,
  Unison works across platforms, allowing you to synchronize a
  Windows laptop with a Unix server, for example.

• Unlike simple mirroring or backup utilities, Unison can deal with
  updates to both replicas of a distributed directory
  structure. Updates that do not conflict are propagated
  automatically. Conflicting updates are detected and displayed.

• Unlike many network filesystems, Unison copies data so that
  already-synchronized data can be read and written while offline.

• Unlike most distributed filesystems, Unison is a user-level program
  that simply uses normal systems calls: there is no need to modify
  the kernel, to have superuser privileges on either host, or to have
  a FUSE implementation.

• Unison works between any pair of machines connected to the
  internet, typically communicating over ssh, but also directly over
  TCP. It is careful with network bandwidth, and runs well over slow
  links such as PPP connections. Transfers of small updates to large
  files are optimized using a compression protocol similar to rsync.

• Unison is resilient to failure. It is careful to leave the replicas
  and its own private structures in a sensible state at all times,
  even in case of abnormal termination or communication failures.

• Unison has a clear and precise specification.

• Unison is Free; full source code is available under the GNU Public
  License, Version 3.

Note that only a very small number of people are actively working on
maintaining unison. An estimate is 2.5 people and 0.1 Full-Time
Equivalents. This has a substantial impact on the handling of bug
reports and enhancement reports; see the wiki page linked at the top.
Help in terms of high-quality bug reports, fixes, and proposed changes
is very welcome. Help in answering mailinglist questions is also
welcome. Please do not answer questions asked in the bug tracker,
which is contrary to bug tracker usage guidance.

While much of Unison activity is now at
https://github.com/bcpierce00/unison/ additional information can be
found at: http://www.cis.upenn.edu/~bcpierce/unison

Getting Unison

The Unison project provides Unison as source code. Many packaging
systems (including GNU/Linux distributions) provide binary packages of
Unison. Results from Continuous Integration builds, while performed
for the purposes of testing, are available for use on a limited set of
platforms.

See the manual in doc/ for building instructions, or read the CI
recipes. (Currently, this is probably less well explained than it
should be.)

You may be able to find a pre-built binary for your operating system,
version, and CPU type. For a list of sources, See
https://github.com/bcpierce00/unison/wiki/Downloading-Unison

Generally, you should use the most recent formal release, currently
2.52. Earlier branches (e.g. 2.51 and 2.48) are no
longer maintained, and bug reports are not accepted about these
versions. This is true even though many packaging systems (including
GNU/Linux distributions) continue to have 2.48. There are sometimes
release candidates. There is always the master branch in git, which
historically has been quite stable.

Version compatibility

For Unison versions 2.52 and newer, see
https://github.com/bcpierce00/unison/wiki/2.52-Migration-Guide

The information below is true for Unison versions older than 2.52.

Beware that Unison uses OCaml's built-in data marshalling, and that
this facility is unstable across versions of "ocaml" (the standard
implementation of the OCaml language). Additionally, Unison has
incompatible changes across minor releases (e.g. 2.48 vs 2.51, but
2.51.2 and 2.51.3 are compatible). Therefore, you must use the same
Unison minor version built with the same ocaml version on all systems.

Mailinglists

There are two mailinglists: unison-users and unison-hackers.
Descriptions and instructions are at
https://github.com/bcpierce00/unison/wiki/Mailing-Lists

Development and Submitting Proposed Changes

If you want to play with the internals, have a look at the file
src/ROADMAP.txt for some basic orientation. Discussion of the source
code, proposed changes, etc. is most appropriate on the unison-hackers
mailinglist.

Proposed code changes are also welcome (as pull requests). For
significant changes, an enhancement request or bug report is likely in
order to provide the proposed semantics ahead of time. For changes
that are likely to be widely viewed as clearly desired, that might be
enough. Others should be discussed on unison-hackers.

Proposed changes should change documentation in concert with code, and
should pass CI.

Unison operates under the widely-used "inbound=outbound" contribution
license process. Therefore, all contributions to Unison must be
licensed under the project's license, currently GPLv3 (unless a file
under a different license is being modified). New files of
significance must have a copyright statement and grant permission to
copy under the project's license. Significant changes should include
copyright statements and/or add authors. Submitting a pull request or
posting a contribution on a mailinglist is an assertion that the
submitter has the authority to license their changes under the
project's license. (This paragraph is intended to summarize the
normal conventions, and is not intended to create any new norms. See
https://sfconservancy.org/blog/2014/jun/09/do-not-need-cla/ for a
longer discussion.)