This tutorial assumes that you have got Unison installed on your computers on the network and have been able to synchronize directories on different computers. Having got a start, now you wish to use other features of Unison to get the maximum benefit from its usage. Also, I assume that you have the secure shell, ssh, server and client programs installed on all your machines. Also, to keep things simple, please ensure that the same version of Unison is installed on all computers.
A replica is a set of files organized in a directory tree structure which need to synchronized with similar structure at another location, which may be a node at the local file system or at a remote host.
A replica is identified by its root. The root gives the location of a replica, either as a node in local file system,
or at a remote host. A root may be absolute or relative. In case it is absolute, its value starts with /
, the root of a file
system. Otherwise it is relative to the file system directory where Unison has been started. For example,
A path refers to a point in a replica. A path may refer to
A path is specified relative to the root. For example, if the root abc/def is being synchronized with another replica and then path ghi/jkl refers to the string abc/def/ghi/jkl, which may be one of the above-mentioned four possibilities. An empty path denotes the root.
An update refers to change in contents of a path since Unison was used to synchronize the replica last time. If the path is
an ordinary file, the contents are the actual bytes in the file and its permission bits. If the path is a symbolic link, its contents are
the string giving the link in the file system. If the path is a directory, its contents are the token DIRECTORY
along with the
permission bits of the directory. If the path is nothing, that is, it is not a file, symbolic link or directory, its contents are
the token "ABSENT".
Unison keeps a record of contents of all paths at the time of last synchronization. It compares the current contents with the contents at the time of last synchronization to figure out whether the contents of a path have been updated.
A path is conflicting, if it has been updated in one of the replicas and the contents in the two replicas are not identical.
Based on the analysis of its archive files and current contents of paths, Unison identifies the paths, which are the same in both replicas and, for these, nothing needs to be done. Then, there are paths which have been updated and need to be synchronized. Updated paths can be categorized into two groups. First, the paths which are not conflicting, for example new files that have been created since the last synchronization. For these, Unison suggests a default action to the user. Then, there are updated paths which are conflicting. Unison lists the conflicting updates, one by one, giving the opportunity to the user to examine the relevant path in more detail and choose an appropriate action.
Unison can be run from the shell by giving one of the following commands,
unison [options]
unison root1 root2 [options]
unison profilename [options]
We will get back to the above-mentioned command formats but first, let's look at the concepts of .unison directory, preferences and profiles..
Unison related data is stored in .unison directory. Its location depends on the UNISON environment variable. If set, its value is the name of this directory. Otherwise the default is $HOME/.unison. The archive file for each replica and profiles are stored in the .unison directory.
It is possible to pass parameters to Unison so that fine tune its processing as per your requirements. These parameters are known as preferences. Some preferences are boolean valued flags, these are either set or not set. Other preferences have specific values. Some of the preferences are, for example,
Preferences can be stored in a text file so that they need not be typed every time Unison is run. This text file is called a profile.
Profiles are stored in .unison directory. The default profile name is default.prf. If unison is started with
no arguments on the command line, unison looks for default.prf in .unison directory for the values of
roots of two replicas and other preferences. Also, if unison is started with just one argument, say, profilename,
(other than options, which are preferences preceded by -
), it looks for a profile named profilename.prf in .unison directory.
There are two lists that are important. These are backup list and ignore list. Yes, the concept of ignore list is important and can not be ignored. But, first let us look at backup list. When Unison is run, it overwrites files during synchronization. Using the backup preference, you can ask Unison to take a backup of a file before overwriting it. The preference is,
backup pattern
Where pattern can one of the three forms,
Regex regexp
Name name
Path path
In all cases backup is taken of any path that matches the pattern. The first form of pattern is keyword Regex
followed by a Posix regular expression. In the second case the last component of path must match name.
In the third case the whole path must match path. Both name and
path are not regular expressions. They are globs which means you can use characters like *
and ?
and other globbing conventions that you use while using the familiar ls
command for listing files in a directory
from shell.
You can give multiple backup preferences to add to the backup list. There are some more preferences
related to backup. The backuplocation preference determines whether the backups are kept near
the files
(backuplocation = local) in the same directory or kept centrally in a designated directory
(backuplocation = central). If backuplocation is set to
central, backupdir indicates the directory in which files are to be
backed up. The backupprefix and backupsuffix account for the naming
of backups. Also, maxbackups preference determines the number of backups to be kept. The default is 2.
Similarly, there is the concept of ignore list. There are often not so important files like temporary files, caches, big binaries downloaded from external sites, etc in replicas, which you do not wish to synchronize. These can be excluded by using the ignore preference,
ignore = pattern
which causes all paths matching the pattern to be ignored in the synchronization process.
As mentioned above, Unison can be run from the shell by giving one of the following commands,
unison [options]
unison root1 root2 [options]
unison profilename [options]
In all the three forms options are optional and represent preferences, prefixed by -
and
separated by spaces, given on the command line. In the first form, Unison tries to synchronize as per the default profile,
default.prf file in the .unison directory. In the second form, Unison tries to synchronize the two
replicas given by their respective roots, root1 and root2. In the third
form, Unison tries to synchronize based on the contents of the profile, profilename.prf in the
.unison directory.
Obviously, you would like to have a profile so as to minimize typing for periodic synchronization. let's say you wish to synchronize
your home directory between your laptop and desktop computers. Assuming the laptop is the client from where
unison command is given, you may wish to have a profile name default.prf
in your .unison
directory something like this,
# Roots for synchronization
root = /home/me
root = ssh://me@192.168.1.2//home/me
# paths to synchronize
path = src
path = doc
path = www
# Ignore some names and paths
ignore = Name tmp*
ignore = Name temp*
ignore = Name .*
ignore = Path */new/copy/src/*
ignore = Name *.o
# keep backups
backuplocation = central
backupdir = /home/me/backups
backup = Name *
backupprefix = $VERSION.
# keep log
log = true
# skip asking for confirmations for non-conflicting changes
auto = true
With a profile like this, you can synchronize by simply giving the command,
unison
Home Milestones Tutorials Papers Troubleshooting News About SoftPrayog Photographs Blog Privacy Policy Contact Us Site Map
All text is available under the terms of
GNU Free Documentation License