Installation Options

The Makefile in the distribution includes several switches that can be used to control how Unison is built. Here are the most useful ones:

• Building with NATIVE=true uses the native-code OCaml compiler, yielding an executable that will run quite a bit faster. We use this for building distribution versions.
• Building with make DEBUGGING=true generates debugging symbols.
• Building with make STATIC=true generates a (mostly) statically linked executable. We use this for building distribution versions, for portability.

---

Tutorial

Preliminaries

Unison can be used with either of two user interfaces:

1. a straightforward textual interface and
2. a more sophisticated graphical interface

The textual interface is more convenient for running from scripts and works on dumb terminals; the graphical interface is better for most interactive use. For this tutorial, you can use either. If you are running Unison from the command line, just typing unison will select either the text or the graphical interface, depending on which has been selected as default when the executable you are running was built. You can force the text interface even if graphical is the default by adding -ui text. The other command-line arguments to both versions are identical.

The graphical version can also be run directly by clicking on its icon, but this may require a little set-up (see the Click-starting Unison section). For this tutorial, we assume that you’re starting it from the command line.

Unison can synchronize files and directories on a single machine, or between two machines on a network. (The same program runs on both machines; the only difference is which one is responsible for displaying the user interface.) If you’re only interested in a single-machine setup, then let’s call that machine the client. If you’re synchronizing two machines, let’s call them client and server.

Local Usage

Let’s get the client machine set up first and see how to synchronize two directories on a single machine.

Follow the instructions in the Installation section to either download or build an executable version of Unison, and install it somewhere on your search path. (If you just want to use the textual user interface, download the appropriate textui binary. If you just want to the graphical interface—or if you will use both interfaces [the gtkui binary actually has both compiled in]—then download the gtkui binary.)

Create a small test directory a.tmp containing a couple of files and/or subdirectories, e.g.,

       mkdir a.tmp
       touch a.tmp/a a.tmp/b
       mkdir a.tmp/d
       touch a.tmp/d/f

Copy this directory to b.tmp:

       cp -r a.tmp b.tmp

Now try synchronizing a.tmp and b.tmp. (Since they are identical, synchronizing them won’t propagate any changes, but Unison will remember the current state of both directories so that it will be able to tell next time what has changed.) Type:

       unison a.tmp b.tmp

(You may need to add -ui text, depending how your unison binary was built.)

Textual Interface:

• You should see a message notifying you that all the files are actually equal and then get returned to the command line.

Graphical Interface:

• You should get a big empty window with a message at the bottom notifying you that all files are identical. Choose the Exit item from the File menu to get back to the command line.

Next, make some changes in a.tmp and/or b.tmp. For example:

        rm a.tmp/a
        echo "Hello" > a.tmp/b
        echo "Hello" > b.tmp/b
        date > b.tmp/c
        echo "Hi there" > a.tmp/d/h
        echo "Hello there" > b.tmp/d/h

Run Unison again:

       unison a.tmp b.tmp

This time, the user interface will display only the files that have changed. If a file has been modified in just one replica, then it will be displayed with an arrow indicating the direction that the change needs to be propagated. For example,

                 <---  new file   c  [f]

indicates that the file c has been modified only in the second replica, and that the default action is therefore to propagate the new version to the first replica. To follow Unison’s recommendation, press the “f” at the prompt.

If both replicas are modified and their contents are different, then the changes are in conflict: <-?-> is displayed to indicate that Unison needs guidance on which replica should override the other.

     new file  <-?->  new file   d/h  []

By default, neither version will be propagated and both replicas will remain as they are.

If both replicas have been modified but their new contents are the same (as with the file b), then no propagation is necessary and nothing is shown. Unison simply notes that the file is up to date.

These display conventions are used by both versions of the user interface. The only difference lies in the way in which Unison’s default actions are either accepted or overridden by the user.

Textual Interface:

• The status of each modified file is displayed, in turn. When the copies of a file in the two replicas are not identical, the user interface will ask for instructions as to how to propagate the change. If some default action is indicated (by an arrow), you can simply press Return to go on to the next changed file. If you want to do something different with this file, press “<” or “>” to force the change to be propagated from right to left or from left to right, or else press “/” to skip this file and leave both replicas alone. When it reaches the end of the list of modified files, Unison will ask you one more time whether it should proceed with the updates that have been selected.

  When Unison stops to wait for input from the user, pressing “?” will always give a list of possible responses and their meanings.

Graphical Interface:

• The main window shows all the files that have been modified in either a.tmp or b.tmp. To override a default action (or to select an action in the case when there is no default), first select the file, either by clicking on its name or by using the up- and down-arrow keys. Then press either the left-arrow or “<” key (to cause the version in b.tmp to propagate to a.tmp) or the right-arrow or “>” key (which makes the a.tmp version override b.tmp).

  Every keyboard command can also be invoked from the menus at the top of the user interface. (Conversely, each menu item is annotated with its keyboard equivalent, if it has one.)

  When you are satisfied with the directions for the propagation of changes as shown in the main window, click the “Go” button to set them in motion. A check sign will be displayed next to each filename when the file has been dealt with.

Remote Usage

Next, we’ll get Unison set up to synchronize replicas on two different machines.

Follow the instructions in the Installation section to download or build an executable version of Unison on the server machine, and install it somewhere on your search path. (It doesn’t matter whether you install the textual or graphical version, since the copy of Unison on the server doesn’t need to display any user interface at all.)

It is important that the version of Unison installed on the server machine is the same as the version of Unison on the client machine. But some flexibility on the version of Unison at the client side can be achieved by using the -addversionno option; see the Preferences section.

Now there is a decision to be made. Unison provides two methods for communicating between the client and the server:

• Remote shell method: To use this method, you must have some way of invoking remote commands on the server from the client’s command line, using a facility such as ssh. This method is more convenient (since there is no need to manually start a “unison server” process on the server) and also more secure (especially if you use ssh).
• Socket method: This method requires only that you can get TCP packets from the client to the server and back. A draconian firewall can prevent this, but otherwise it should work anywhere.

Decide which of these you want to try, and continue with the Remote Shell Method section or the Socket Method section, as appropriate.

Remote Shell Method

The standard remote shell facility on Unix systems is ssh, which provides the same functionality as the older rsh but much better security. Ssh is available from http://www.openssh.org. See section A.2 for installation instructions for the Windows version.

Running ssh requires some coordination between the client and server machines to establish that the client is allowed to invoke commands on the server; please refer to the ssh documentation for information on how to set this up. The examples in this section use ssh, but you can substitute rsh for ssh if you wish.

First, test that we can invoke Unison on the server from the client. Typing

        ssh remotehostname unison -version

should print the same version information as running

        unison -version

locally on the client. If remote execution fails, then either something is wrong with your ssh setup (e.g., “permission denied”) or else the search path that’s being used when executing commands on the server doesn’t contain the unison executable (e.g., “command not found”).

Create a test directory a.tmp in your home directory on the client machine.

Test that the local unison client can start and connect to the remote server. Type

          unison -testServer a.tmp ssh://remotehostname/a.tmp

Now cd to your home directory and type:

          unison a.tmp ssh://remotehostname/a.tmp

The result should be that the entire directory a.tmp is propagated from the client to your home directory on the server.

After finishing the first synchronization, change a few files and try synchronizing again. You should see similar results as in the local case.

If your user name on the server is not the same as on the client, you need to specify it on the command line:

          unison a.tmp ssh://username@remotehostname/a.tmp

Notes:

• If you want to put a.tmp some place other than your home directory on the remote host, you can give an absolute path for it by adding an extra slash between remotehostname and the beginning of the path:

            unison a.tmp ssh://remotehostname//absolute/path/to/a.tmp
  

• You can give an explicit path for the unison executable on the server by using the command-line option -servercmd /full/path/name/of/unison or adding servercmd=/full/path/name/of/unison to your profile (see the Profile section). Similarly, you can specify a explicit path for the ssh program using the -sshcmd option. Extra arguments can be passed to ssh by setting the -sshargs preference.

Socket Method

Warning: The socket method is insecure: not only are the texts of your changes transmitted over the network in unprotected form, it is also possible for anyone in the world to connect to the server process and read out the contents of your filesystem! (Of course, to do this they must understand the protocol that Unison uses to communicate between client and server, but all they need for this is a copy of the Unison sources.) The socket method is provided only for expert users with specific needs; everyone else should use the ssh method.

To run Unison over a socket connection, you must start a Unison daemon process on the server. This process runs continuously, waiting for connections over a given socket from client machines running Unison and processing their requests in turn.

To start the daemon, type

       unison -socket NNNN

on the server machine, where NNNN is the socket number that the daemon should listen on for connections from clients. (NNNN can be any large number that is not being used by some other program; if NNNN is already in use, Unison will exit with an error message.) Note that paths specified by the client will be interpreted relative to the directory in which you start the server process; this behavior is different from the ssh case, where the path is relative to your home directory on the server.

Create a test directory a.tmp in your home directory on the client machine. Now type:

       unison a.tmp socket://remotehostname:NNNN/a.tmp

The result should be that the entire directory a.tmp is propagated from the client to the server (a.tmp will be created on the server in the directory that the server was started from). After finishing the first synchronization, change a few files and try synchronizing again. You should see similar results as in the local case.

Since the socket method is not used by many people, its functionality is rather limited. For example, the server can only deal with one client at a time.

Using Unison for All Your Files

Once you are comfortable with the basic operation of Unison, you may find yourself wanting to use it regularly to synchronize your commonly used files. There are several possible ways of going about this:

1. Synchronize your whole home directory, using the Ignore facility (see the Ignore section) to avoid synchronizing temporary files and things that only belong on one host.
2. Create a subdirectory called shared (or current, or whatever) in your home directory on each host, and put all the files you want to synchronize into this directory.
3. Create a subdirectory called shared (or current, or whatever) in your home directory on each host, and put links to all the files you want to synchronize into this directory. Use the follow preference (see the Symbolic Links section) to make Unison treat these links as transparent.
4. Make your home directory the root of the synchronization, but tell Unison to synchronize only some of the files and subdirectories within it on any given run. This can be accomplished by using the -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. See the Preferences section for an example.

Most people find that they only need to maintain a profile (or profiles) on one of the hosts that they synchronize, since Unison is always initiated from this host. (For example, if you’re synchronizing a laptop with a fileserver, you’ll probably always run Unison on the laptop.) This is a bit different from the usual situation with asymmetric mirroring programs like rdist, where the mirroring operation typically needs to be initiated from the machine with the most recent changes. the Profile section covers the syntax of Unison profiles, together with some sample profiles.

Some tips on improving Unison’s performance can be found on the Frequently Asked Questions page.

Using Unison to Synchronize More Than Two Machines

Unison is designed for synchronizing pairs of replicas. However, it is possible to use it to keep larger groups of machines in sync by performing multiple pairwise synchronizations.

If you need to do this, the most reliable way to set things up is to organize the machines into a “star topology,” with one machine designated as the “hub” and the rest as “spokes,” and with each spoke machine synchronizing only with the hub. The big advantage of the star topology is that it eliminates the possibility of confusing “spurious conflicts” arising from the fact that a separate archive is maintained by Unison for every pair of hosts that it synchronizes.

 

Example:

To sync two files and update every 1 second without asking for confirmation etc:

unison -auto -repeat 1 c:\test2\test2.txt c:\test1\test1.txt

A good way is to schedule a script and run in the background.