Scroll to navigation

UNISON(1) General Commands Manual (urm) UNISON(1)

NAME

unison — a multi-platform bi-directional file synchronization tool

SYNOPSIS

unison [options]

unison root1 root2 [options]

unison profilename [options]

DESCRIPTION

Unison is a file-synchronization tool for POSIX-compliant systems (e.g. *BSD and GNU/Linux), macOS 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 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 other tools. Some of the distinguishing features are:

  • Unlike simple mirroring or backup utilities, Unison can deal with updates to both replicas of a distributed directory structure.
  • Unison works across platforms, allowing you to synchronize a Windows laptop with a Unix server, for example.
  • 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(1), but also directly over TCP. It is careful with network bandwidth, and runs well over slow links. Transfers of small updates to large files are optimized using a compression protocol similar to rsync(1).
  • 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.

OPTION SUMMARY



  General:
   -doc xxx            show documentation ('-doc topics' lists topics)
   -version            print version and exit

  What to sync:
   -group              synchronize group attributes
   -ignore xxx         add a pattern to the ignore list
   -ignorenot xxx      add a pattern to the ignorenot list
   -nocreation xxx     prevent file creations on one replica
   -nodeletion xxx     prevent file deletions on one replica
   -noupdate xxx       prevent file updates and deletions on one replica
   -owner              synchronize owner
   -path xxx           path to synchronize
   -perms n            part of the permissions which is synchronized
   -root xxx           root of a replica (should be used exactly twice)
   -times              synchronize modification times

  How to sync:
   -batch              batch mode: ask no questions at all

  How to sync (text interface (CLI) only):
   -auto               automatically accept default (nonconflicting) actions
   -silent             print nothing except error messages
   -terse              suppress status messages

  Text interface (CLI):
   -i                  interactive profile mode (text UI); command-line only



  Fine-tune sync:
   -atomic xxx         add a pattern to the atomic list
   -follow xxx         add a pattern to the follow list
   -force xxx          force changes from this replica to the other
   -forcepartial xxx   add a pattern to the forcepartial list
   -ignorecase xxx     identify upper/lowercase filenames (true/false/default)
   -immutable xxx      add a pattern to the immutable list
   -immutablenot xxx   add a pattern to the immutablenot list
   -links xxx          allow the synchronization of symbolic links
                       (true/false/default)
   -merge xxx          add a pattern to the merge list
   -nocreationpartial xxx add a pattern to the nocreationpartial list
   -nodeletionpartial xxx add a pattern to the nodeletionpartial list
   -noupdatepartial xxx add a pattern to the noupdatepartial list
   -prefer xxx         choose this replica's version for conflicting changes
   -preferpartial xxx  add a pattern to the preferpartial list
   -rsrc xxx           synchronize resource forks (true/false/default)

  How to sync:
   -backup xxx         add a pattern to the backup list
   -backupcurr xxx     add a pattern to the backupcurr list
   -backupcurrnot xxx  add a pattern to the backupcurrnot list
   -backupdir xxx      directory for storing centralized backups
   -backuploc xxx      where backups are stored ('local' or 'central')
   -backupnot xxx      add a pattern to the backupnot list
   -backupprefix xxx   prefix for the names of backup files
   -backups            (deprecated) keep backup copies of all files (see also
                       'backup')
   -backupsuffix xxx   a suffix to be added to names of backup files
   -confirmbigdel      ask about whole-replica (or path) deletes (default true)
   -confirmmerge       ask for confirmation before committing results of a merge
   -copyonconflict     keep copies of conflicting files
   -dontchmod          when set, never use the chmod system call
   -fastcheck xxx      do fast update detection (true/false/default)
   -fat                use appropriate options for FAT filesystems
   -ignoreinodenumbers ignore inode number changes when detecting updates
   -maxbackups n       number of backed up versions of a file
   -numericids         don't map uid/gid values by user/group names
   -sortbysize         list changed files by size, not name
   -sortfirst xxx      add a pattern to the sortfirst list
   -sortlast xxx       add a pattern to the sortlast list
   -sortnewfirst       list new before changed files

  How to sync (text interface (CLI) only):
   -repeat xxx         synchronize repeatedly (text interface only)
   -retry n            re-try failed synchronizations N times (text ui only)

  Text interface (CLI):
   -color xxx          use color output for text UI (true/false/default)
   -dumbtty            do not change terminal settings in text UI

  Graphical interface (GUI):
   -height n           height (in lines) of main window in graphical interface

  Remote connections:
   -addversionno       add version number to name of unison on server
   -clientHostName xxx set host name of client
   -halfduplex         (deprecated) force half-duplex communication with the
                       server
   -killserver         kill server when done (even when using sockets)
   -listen xxx         listen on this name or addr in server socket mode (can
                       repeat)
   -rsync              activate the rsync transfer mode (default true)
   -servercmd xxx      name of unison executable on remote server
   -socket xxx         act as a server on a socket
   -sshargs xxx        other arguments (if any) for remote shell command
   -sshcmd xxx         path to the ssh executable
   -stream             (deprecated) use a streaming protocol for transferring
                       file contents (default true)
   -testserver         exit immediately after the connection to the server
   -xferbycopying      optimize transfers using local copies (default true)

  Archive management:
   -ignorearchives     ignore existing archive files

  Other:
   -addprefsto xxx     file to add new prefs to
   -contactquietly     suppress the 'contacting server' message during startup
   -copymax n          maximum number of simultaneous copyprog transfers
   -copyprog xxx       external program for copying large files
   -copyprogrest xxx   variant of copyprog for resuming partial transfers
   -copyquoterem xxx   add quotes to remote file name for copyprog
                       (true/false/default)
   -copythreshold n    use copyprog on files bigger than this (if >=0, in Kb)
   -diff xxx           set command for showing differences between files
   -ignorelocks        ignore locks left over from previous run (dangerous!)
   -include xxx        include a profile's preferences
   -key xxx            define a keyboard shortcut for this profile (in some UIs)
   -label xxx          provide a descriptive string label for this profile
   -log                record actions in logfile (default true)
   -logfile xxx        logfile name
   -maxerrors n        maximum number of errors before a directory transfer is
                       aborted
   -maxsizethreshold n prevent transfer of files bigger than this (if >=0, in
                       Kb)
   -maxthreads n       maximum number of simultaneous file transfers
   -mountpoint xxx     abort if this path does not exist
   -rootalias xxx      register alias for canonical root names
   -showarchive        show 'true names' (for rootalias) of roots and archive
   -source xxx         include a file's preferences
   -ui xxx             select UI ('text' or 'graphic'); command-line only
   -unicode xxx        assume Unicode encoding in case insensitive mode
   -watch              when set, use a file watcher process to detect changes


   -debug xxx          debug module xxx ('all' -> everything, 'verbose' -> more)
   -dumparchives       dump contents of archives just after loading
   -fastercheckUNSAFE  skip computing fingerprints for new files (experts only!)
   -selftest           run internal tests and exit

OPTIONS

Most of the options can be given as command line arguments or in a profile. On command line, but not in a profile, the options are specified with a leading dash. Like this: -option.

xxx
ignore clauses) will be appended to whatever preference file Unison was told to load at the beginning of the run. Setting the preference addprefsto filename makes Unison add new preferences to the file named filename instead.
true, Unison will use currentmajorversionnumber instead of just unison as the remote server command (note that the minor version number is dropped -- e.g., unison-2.51). This allows multiple binaries for different versions of unison to coexist conveniently on the same server: whichever version is run on the client, the same version will be selected on the server.
xxx
backupcurr however has no effect on atomic directories.
true, this flag causes the user interface to skip asking for confirmations on non-conflicting changes. (More precisely, when the user interface is done setting the propagation direction for one entry and is about to move to the next, it will skip over all non-conflicting entries and go directly to the next conflict.)
xxx
-backup pathspec causes Unison to keep backup files for each path that matches pathspec; directories (nor their permissions or any other metadata) are not backed up. These backup files are kept in the directory specified by the backuplocation preference. The backups are named according to the backupprefix and backupsuffix preferences. The number of versions that are kept is determined by the maxbackups preference. The syntax of pathspec is described in Section “Path Specification” in the manual.
xxx
-backupcurr pathspec causes Unison to keep a backup of the version of every file matching pathspec. This file will be saved as a backup with version number 000. Such backups can be used as inputs to external merging programs, for instance. See the documentatation for the merge preference. For more details, see Section “Merging Conflicting Versions” in the manual. The syntax of pathspec is described in Section “Path Specification” in the manual.
xxx
backupcurr, like the ignorenot preference.
xxx
backup preference, when backuplocation is set to central. It is checked the UNISONBACKUPDIR environment variable.
xxx
backupdir preference. If set to local, backups will be kept in the same directory as the original files, and if set to central, backupdir will be used instead.
xxx
not be backed up, even if the backup preference selects them—i.e., it selectively overrides backup.
xxx
NAME is created, it is stored in a directory specified by backuplocation, in a file called backupprefixNAMEbackupsuffix. backupprefix can include a directory name (causing Unison to keep all backup files for a given directory in a subdirectory with this name), and both backupprefix and backupsuffix can contain the string $VERSION, which will be replaced by the of the backup (1 for the most recent, 2 for the second most recent, and so on...). This keyword is ignored if it appears in a directory name in the prefix; if it does not appear anywhere in the prefix or the suffix, it will be automatically placed at the beginning of the suffix. One thing to be careful of: If the backuploc preference is set to local, Unison will automatically ignore all files whose prefix and suffix match backupprefix and backupsuffix. So be careful to choose values for these preferences that are sufficiently different from the names of your real files.
(Deprecated) Setting this flag to true is equivalent to setting backuplocation to local and backup to Name *.
xxx
backupprefix for full documentation.
true, the user interface will ask no questions at all. Non-conflicting changes will be propagated; conflicts will be skipped.
xxx
xxx
true, this flag enables color output in text mode user interface. When set to false, all color output is disabled. Default is to enable color if the NO_COLOR environment variable is not set.
true, Unison will request an extra confirmation if it appears that the entire replica has been deleted, before propagating the change. If the batch flag is also set, synchronization will be aborted. When the path preference is used, the same confirmation will be requested for top-level paths. (At the moment, this flag only affects the text user interface.) See also the mountpoint preference.
n
-repeat watch and -prefer newer preferences.
xxx
rsync with appropriate options—most users should not need to change it.
xxx
copyprog that names an external program that should be used to continue the transfer of a large file that has already been partially transferred. Typically, copyprogrest will just be copyprog with one extra option (e.g., , for rsync). The default setting invokes rsync with appropriate options—most users should not need to change it.
xxx
true, this flag causes Unison to add an extra layer of quotes to the remote path passed to the external copy program. This is needed by rsync, for example, which internally uses an ssh connection requiring an extra level of quoting for paths containing spaces. When this flag is set to default, extra quotes are added if the value of copyprog contains the string rsync.
n
copyprog. Specifying 0 will cause all copies to use the external program; a negative number will prevent any files from using it. The default is -1. See Section “Making Unison Faster on Large Files” in the manual for more information.
xxx
debug can be found by looking for calls to Util.debug in the sources (using, e.g., grep). Setting -debug all causes information from all modules to be printed (this mode of usage is the first one to try, if you are trying to understand something that Unison seems to be doing wrong); -debug verbose turns on some additional debugging output from some modules (e.g., it will show exactly what bytes are being sent across the network).
xxx
diff -u OLDER NEWER'. If the value of this preference contains the substrings CURRENT1 and CURRENT2, these will be replaced by the names of the files to be diffed. If the value of this preference contains the substrings NEWER and OLDER, these will be replaced by the names of files to be diffed, NEWER being the most recently modified file of the two. Without any of these substrings, the two filenames will be appended to the command. In all cases, the filenames are suitably quoted.
xxx
-doc secname causes unison to display section secname of the manual on the standard output and then exit. Use -doc all to display the whole manual, which includes exactly the same information as the printed and HTML manuals, modulo formatting. Use -doc topics to obtain a list of the names of the various sections that can be printed.
true, this flag makes the text mode user interface avoid trying to change any of the terminal settings. (Normally, Unison puts the terminal in `raw mode', so that it can do things like overwriting the current line.) This is useful, for example, when Unison runs in a shell inside of Emacs. When dumbtty is set, commands to the user interface need to be followed by a carriage return before Unison will execute them. (When it is off, Unison recognizes keystrokes as soon as they are typed.) This preference has no effect on the graphical user interface.
xxx
true, Unison will use the modification time and length of a file as a `pseudo inode number' when scanning replicas for updates, instead of reading the full contents of every file. (This does not apply to the very first run, when Unison will always scan all files regardless of this switch). Under Windows, this may cause Unison to miss propagating an update if the modification time and length of the file are both unchanged by the update. However, Unison will never such an update with a change from the other replica, since it always does a safe check for updates just before propagating a change. Thus, it is reasonable to use this switch under Windows most of the time and occasionally run Unison once with fastcheck set to false, if you are worried that Unison may have overlooked an update. For backward compatibility, yes, no, and default can be used in place of true, false, and auto. See Section “Fast Update Detection” in the manual for more information.
When this flag is set to true, Unison will compute a 'pseudo-fingerprint' the first time it sees a file (either because the file is new or because Unison is running for the first time). This enormously speeds update detection, but it must be used with care, as it can cause Unison to miss conflicts: If a given path in the filesystem contains files on sides that Unison has not yet seen, and if those files have the same length but different contents, then Unison will not notice the presence of a conflict. If, later, one of the files is changed, the changed file will be propagated, overwriting the other. Moreover, even when the files are initially identical, setting this flag can lead to potentially confusing behavior: if a newly created file is later touched without being modified, Unison will treat this conservatively as a potential change (since it has no record of the earlier contents) and show it as needing to be propagated to the other replica. Most users should leave this flag off -- the small time savings of not fingerprinting new files is not worth the cost in terms of safety. However, it can be very useful for power users with huge replicas that are known to be already synchronized (e.g., because one replica is a newly created duplicate of the other, or because they have previously been synchronized with Unison but Unison's archives need to be rebuilt). In such situations, it is recommended that this flag be set only for the initial run of Unison, so that new archives can be created quickly, and then turned off for normal use.
true, Unison will use appropriate options to synchronize efficiently and without error a replica located on a FAT filesystem on a non-Windows machine: do not synchronize permissions (perms = 0); never use chmod (dontchmod = true); treat filenames as case insensitive (ignorecase = true); do not attempt to synchronize symbolic links (links = false); ignore inode number changes when detecting updates (ignoreinodenumbers = true). Any of these change can be overridden by explicitly setting the corresponding preference in the profile.
xxx
-follow pathspec causes Unison to treat symbolic links matching pathspec as `invisible' and behave as if the object pointed to by the link had appeared literally at this position in the replica. See Section “Symbolic Links” in the manual for more details. The syntax of pathspec is described in Section “Path Specification” in the manual.
xxx
-force root causes Unison to resolve all differences (even non-conflicting changes) in favor of root. This effectively changes Unison from a synchronizer into a mirroring utility. You can also specify -force newer (or -force older) to force Unison to choose the file with the later (earlier) modtime. In this case, the -times preference must also be enabled. This preference is overridden by the forcepartial preference. This preference should be used only if you are sure you know what you are doing!
xxx
forcepartial = PATHSPEC -> root causes Unison to resolve all differences (even non-conflicting changes) in favor of root for the files in PATHSPEC (see Section “Path Specification” in the manual for more information). This effectively changes Unison from a synchronizer into a mirroring utility. You can also specify forcepartial PATHSPEC -> newer (or forcepartial PATHSPEC older) to force Unison to choose the file with the later (earlier) modtime. In this case, the -times preference must also be enabled. This preference should be used only if you are sure you know what you are doing!
true, the group attributes of the files are synchronized. Whether the group names or the group identifiers are synchronized depends on the preference numerids.
(Deprecated) When this flag is set to true, Unison network communication is forced to be half duplex (the client and the server never simultaneously emit data). If you experience unstabilities with your network link, this may help.
n
batch and silent remain applicable to synchronization functionality.
xxx
-ignore pathspec causes Unison to completely ignore paths that match pathspec (as well as their children). This is useful for avoiding synchronizing temporary files, object files, etc. The syntax of pathspec is described in Section “Path Specification” in the manual, and further details on ignoring paths is found in Section “Ignoring Paths” in the manual.
xxx
true, this flag causes Unison to treat filenames as case insensitive—i.e., files in the two replicas whose names differ in (upper- and lower-case) `spelling' are treated as the same file. When the flag is set to false, Unison will treat all filenames as case sensitive. Ordinarily, when the flag is set to default, filenames are automatically taken to be case-insensitive if either host is running Windows or OSX. In rare circumstances it may be useful to set the flag manually.
that no other instance of Unison might be concurrently accessing the same archive files (e.g., because there was only one instance of unison running and it has just crashed or you have just killed it). It is probably not a good idea to set this option in a profile: it is intended for command-line use.
xxx
ignore. It gives a list of patterns (in the same format as ignore) for paths that should definitely not be ignored, whether or not they happen to match one of the ignore patterns. Note that the semantics of ignore and ignorenot is a little counter-intuitive. When detecting updates, Unison examines paths in depth-first order, starting from the roots of the replicas and working downwards. Before examining each path, it checks whether it matches ignore and does not match ignorenot; in this case it skips this path . This means that, if some parent of a given path matches an ignore pattern, then it will be skipped even if the path itself matches an ignorenotpattern. In particular, putting ignore = Path * in your profile and then using ignorenot to select particular paths to be synchronized will not work. Instead, you should use the pathpreference to choose particular paths to synchronize.
xxx
xxx
immutable.
xxx
include name reads the profile “name” (or file “name” in the .unison directory if profile “name” does not exist) and includes its contents as if it was part of a profile or given directly on command line.
xxx
true, this flag causes Unison to kill the remote server process when the synchronization is finished. This behavior is the default for ssh connections, so this preference is not normally needed when running over ssh; it is provided so that socket-mode servers can be killed off after a single run of Unison, rather than waiting to accept future connections. (Some users prefer to start a remote socket server for each run of Unison, rather than leaving one running all the time.)
xxx
true, this flag causes Unison to synchronize symbolic links. When the flag is set to false, symbolic links will result in an error during update detection. Ordinarily, when the flag is set to default, symbolic links are synchronized except when one of the hosts is running Windows. On a Windows client, Unison makes an attempt to detect if symbolic links are supported and allowed by user privileges. You may have to get elevated privileges to create symbolic links.
xxx
on a file.
xxx
unison.log in your .unison directory. Set this preference if you prefer another file. It can be a path relative to your .unison directory. Sending SIGUSR1 will close the logfile; the logfile will be re-opened (and created, if needed) automatically, to allow for log rotation.
n
backup. The default is 2.
n
n
n
xxx
pathspec -> cmd is described in Section “Path Specification” in the manual, and further details on Merging functions are present in Section “Merging Conflicting Versions” in the manual.
xxx
-mountpoint PATH causes Unison to double-check, at the end of update detection, that exists and abort if it does not. This is useful when Unison is used to synchronize removable media. This preference can be given more than once. See Section “Mount Points and Removable Media” in the manual.
xxx
-nocreation root prevents Unison from performing any file creation on root root. This preference can be included twice, once for each root, if you want to prevent any creation.
xxx
nocreationpartial = PATHSPEC -> root prevents Unison from performing any file creation in PATHSPEC on root root (see Section “Path Specification” in the manual for more information). It is recommended to use BelowPath patterns when selecting a directory and all its contents.
xxx
-nodeletion root prevents Unison from performing any file deletion on root root. This preference can be included twice, once for each root, if you want to prevent any deletion.
xxx
nodeletionpartial = PATHSPEC -> root prevents Unison from performing any file deletion in PATHSPEC on root root (see Section “Path Specification” in the manual for more information). It is recommended to use BelowPath patterns when selecting a directory and all its contents.
xxx
-noupdate root prevents Unison from performing any file update or deletion on root root. This preference can be included twice, once for each root, if you want to prevent any update.
xxx
noupdatepartial = PATHSPEC -> root prevents Unison from performing any file update or deletion in PATHSPEC on root root (see Section “Path Specification” in the manual for more information). It is recommended to use BelowPath patterns when selecting a directory and all its contents.
true, groups and users are synchronized numerically, rather than by name. The special uid 0 and the special group 0 are never mapped via user/group names even if this preference is not set.
true, the owner attributes of the files are synchronized. Whether the owner names or the owner identifiers are synchronizeddepends on the preference numerids.
xxx
path preference is given, Unison will simply synchronize the two entire replicas, beginning from the given pair of roots. If one or more path preferences are given, then Unison will synchronize only these paths and their children. (This is useful for doing a fast sync of just one directory, for example.) Note that path preferences are interpreted literally—they are not regular expressions.
n
fat preference instead of this preference. If you need Unison not to set permissions at all, set the value of this preference to $0$ and set the preference dontchmod to true.
xxx
-prefer root causes Unison always to resolve conflicts in favor of root, rather than asking for guidance from the user, except for paths marked by the preference merge. (The syntax of root is the same as for the root preference, plus the special values newer and older.) This preference is overridden by the preferpartial preference. This preference should be used only if you are sure you know what you are doing!
xxx
preferpartial = PATHSPEC -> root causes Unison always to resolve conflicts in favor of root, rather than asking for guidance from the user, for the files in PATHSPEC (see Section “Path Specification” in the manual for more information). (The syntax of root is the same as for the root preference, plus the special values newer and older.) This preference should be used only if you are sure you know what you are doing!
xxx
watch, Unison relies on an external file monitoring process to synchronize whenever a change happens.
n
xxx
root in the profile, or to give no values in the profile and provide two on the command line. Details of the syntax of roots can be found in Section “Roots” in the manual. The two roots can be given in either order; Unison will sort them into a canonical order before doing anything else. It also tries to `canonize' the machine names and paths that appear in the roots, so that, if Unison is invoked later with a slightly different name for the same root, it will be able to locate the correct archives.
xxx
xxx
true, this flag causes Unison to synchronize resource forks and HFS meta-data. On filesystems that do not natively support resource forks, this data is stored in Carbon-compatible ._AppleDouble files. When the flag is set to false, Unison will not synchronize these data. Ordinarily, the flag is set to default, and these data are automatically synchronized if either host is running OSX. In rare circumstances it is useful to set the flag manually.
xxx
rootalias preference.
true, the textual user interface will print nothing at all, except in the case of errors. Setting silent to true automatically sets the batch preference to true.
xxx
This preference (as well as the other sorting flags, but not the sorting preferences that require patterns as arguments) can be set interactively and temporarily using the 'Sort' menu in the graphical and text user interfaces.
xxx
sortfirst is a pattern pathspec, which describes a set of paths. Files matching any of these patterns will be listed first in the user interface. The syntax of pathspec is described in Section “Path Specification” in the manual.
xxx
sortfirst, except that files matching one of these patterns will be listed at the very end.
xxx
source name reads the file “name” in the .unison directory and includes its contents as if it was part of a profile or given directly on command line.
xxx
ssh command used to invoke the remote server. The backslash is an escape character.
xxx
(Deprecated) When this preference is set, Unison will use an experimental streaming protocol for transferring file contents more efficiently. The default value is true.
true, the user interface will not print status messages.
true, file modification times (but not directory modtimes) are propagated.
xxx
graphic or text. Because this option is processed specially during Unison's start-up sequence, it can be used on the command line. In preference files it has no effect. If the Unison executable was compiled with only a textual interface, this option has no effect. (The pre-compiled binaries are all compiled with both interfaces available.)
xxx
true, this flag causes Unison to perform case insensitive file comparisons assuming Unicode encoding. This is the default. When the flag is set to false, a Latin 1 encoding is assumed. When Unison runs in case sensitive mode, this flag only makes a difference if one host is running Windows or Mac OS X. Under Windows, the flag selects between using the Unicode or 8bit Windows API for accessing the filesystem. Under Mac OS X, it selects whether comparing the filenames up to decomposition, or byte-for-byte.
true.

ROOTS

A replica’s root tells Unison where to find a set of files to be synchronized, either on the local machine or on a remote host. For example,

relative/path/of/root

specifies a local root relative to the directory where Unison is started, while

/absolute/path/of/root

specifies a root relative to the top of the local filesystem, independent of where Unison is running. Remote roots can begin with ssh:// to indicate that the remote server should be started with ssh(1):

ssh://remotehost//absolute/path/of/root
ssh://user@remotehost/relative/path/of/root

If the remote server is already running (in the socket mode), then the syntax

socket://remotehost:portnum//absolute/path/of/root
socket://remotehost:portnum/relative/path/of/root
socket://[IPv6literal]:portnum/path

is used to specify the hostname and the port that the client Unison should use to contact it. Syntax

socket://{path/of/socket}//absolute/path/of/root
socket://{path/of/socket}/relative/path/of/root

is used to specify the Unix domain socket the client Unison should use to contact the server.

The syntax for roots is based on that of URIs (described in RFC 2396). The full grammar is:

  replica ::= [protocol:]//[user@][host][:port][/path]
           |  path

  protocol ::= file
            |  socket
            |  ssh

  user ::= [-_a-zA-Z0-9]+

  host ::= [-_a-zA-Z0-9.]+
        |  \[ [a-f0-9:.]+ zone? \]     IPv6 literals (no future format).
        |  { [^}]+ }                   For Unix domain sockets only.

  zone ::= %[-_a-zA-Z0-9~%.]+

  port ::= [0-9]+
When path is given without any protocol prefix, the protocol is assumed to be file:. Under Windows, it is possible to synchronize with a remote directory using the file: protocol over the Windows Network Neighborhood. For example,

unison foo //host/drive/bar

synchronizes the local directory foo with the directory drive:\bar on the machine , provided that host is accessible via Network Neighborhood. When the file: protocol is used in this way, there is no need for a Unison server to be running on the remote host. However, running Unison this way is only a good idea if the remote host is reached by a very fast network connection, since the full contents of every file in the remote replica will have to be transferred to the local machine to detect updates.

PATHS

A path refers to a point within a set of files being synchronized; it is specified relative to the root of the replica. Formally, a path is just a sequence of names, separated by /. Note that the path separator character is always a forward slash, no matter what operating system Unison is running on. The empty path (i.e., the empty sequence of names) denotes the whole replica.

PATH SPECIFICATION

Several Unison preferences (e.g., , follow, , backup, merge, etc.) specify individual paths or sets of paths. These preferences share a common syntax based on regular expressions. Each preference is associated with a list of path patterns; the paths specified are those that match any one of the path pattern.

Each pattern can have one of three forms. The most general form is a Posix extended regular expression introduced by the keyword . (The collating sequences and character classes of full Posix regexps are not currently supported.)

Regex regexp

For convenience, three other styles of pattern are also recognized:

Name name

matches any path in which the last component matches name,

Path path

matches exactly the path path, and

BelowPath path

matches the path path and any path below. The name and path arguments of the latter forms of patterns are not regular expressions. Instead, standard “globbing” conventions can be used in name and path:

  • a matches any sequence of characters not including / (and not beginning with ., when used at the beginning of a name)
  • a matches any single character except / (and leading .)
  • matches any character from the set {x, y, z}
  • matches any one of a, bb, or ccc. (Be careful not to put extra spaces after the commas: these will be interpreted literally as part of the strings to be matched!)

The path separator in path patterns is always the forward-slash character “/” — even when the client or server is running under Windows, where the normal separator character is a backslash. This makes it possible to use the same set of path patterns for both Unix and Windows file systems.

A path specification may be followed by the separator “ -> ” itself followed by a string which will be associated to the matching paths:

Path path -> associated string

Not all pathspec preferences use these associated strings but all pathspec preferences are parsed identically and the strings may be ignored. Only the last match of the separator string on the line is used as a delimiter. Thus to allow a path specification to contain the separator string, append an associated string to it, even if it is not used. The associated string cannot contain the separator string.

PROFILES

A profile is a text file that specifies permanent settings for roots, paths, ignore patterns, and other preferences, so that they do not need to be typed at the command line every time Unison is run. Profiles should reside in the .unison directory on the client machine. If Unison is started with just one argument name on the command line, it looks for a profile called .prf in the .unison directory. If it is started with no arguments, it scans the .unison directory for files whose names end in .prf and offers a menu (when using the graphical user interface; for the text interface, you have to use the -i option). If a file named default.prf is found, its settings will be used as the default preferences.

To set the value of a preference p permanently, add to the appropriate profile a line of the form

p = true

for a boolean flag or

p = <value>

for a preference of any other type. Whitespaces around p and the value are ignored. A profile may also include blank lines and lines beginning with #; both are ignored.

When Unison starts, it first reads the profile and then the command line, so command-line options will override settings from the profile.

ENVIRONMENT

Unison stores a variety of information in a private directory on each host. If the environment variable UNISON is defined, then its value will be used as the path for this directory. This can be just a name, or a path. If UNISON is not defined, then the directory depends on which operating system you are using. In Unix, the default is to use $HOME/.unison. In Windows, if the environment variable is defined, then the directory will be $USERPROFILE\.unison; otherwise, it will be c:\.unison. On macOS, $HOME/.unison will be used if it is present, but $HOME/Library/Application Support/Unison will be created and used by default.
The function that finds the canonical hostname of the local host (which is used, for example, in calculating the name of the archive file used to remember which files have been synchronized) normally uses the operating system call. However, if the environment variable UNISONLOCALHOSTNAME is set, its value will be used instead. This makes it easier to use Unison in situations where a machine’s name changes frequently (e.g., because it is a laptop and gets moved around a lot).
When backups are stored centrally, the directory used to hold them is controlled by the preference backupdir and the environment variable UNISONBACKUPDIR. If both are specified then the environment variable overrides the preference. If neither of these are set, then the directory $UNISON/backup is used (see environment variable UNISON above).
Used by the text interface as the pager when displaying the differences between changed files.
If the environment variable NO_COLOR is set then Unison's text interface will not produce any color output by default. The color preference overrides this environment variable.

FILES

~/.unison
Unison stores a variety of information in a private directory on each host. This is the default path of this private directory. This path may be changed by the UNISON environment variable.

~/.unison/*.prf
Profile files. Each profile is stored in a file named .prf.

~/.unison/ar*
 
~/.unison/tm*
 
~/.unison/sc*
Main and temporary archive files. These files may be deleted if you know what you are doing. Deleting an archive file is equivalent to using the -ignorearchives option.

~/.unison/fp*
Fingerprint cache files. These files may be safely deleted. Keep in mind that deleting a fingerprint cache file means that any unsychronized changes must be scanned again. Depending on your replicas, this may mean scanning gigabytes of file contents.

~/.unison/lk*
Lock files indicating a running Unison process. These files may be deleted if you are careful and know that there is no Unison process currently running. Deleting a lock file is equivalent to using the -ignorelocks option.

EXAMPLES

unison path/to/dir1 /dir2

This command synchronizes two local directories using the default options. Default options are defined by Unison and can be overridden by user in a profile called “default”, which is by default stored in file ~/.unison/default.prf

unison local/dir ssh://user@host//absolute/path

This command synchronizes a local directory (here specified by a relative path) and a remote directory (here specified by an absolute path) using ssh(1) and the default options (see example above).

unison profilename

This command reads all the options from the profile named “profilename” and synchronizes according to those options.

unison profilename /path/to/dir ssh://host/path/on/server

This command reads all options from the profile named “profilename” with only the roots specified on the command line. Roots must not be specified in the profile as the roots from command line will not override roots in the profile, rather append to the list of roots.

unison -batch /path/to/dir ssh://host/path/on/server

This command synchronizes all non-conflicting changes automatically, once.

unison -repeat watch /path/to/dir ssh://host/path/on/server

This command first fully synchronizes the roots and then remains dormant, waiting for any file changes within either root and then automatically synchronizes these changes. This also works in a profile (repeat = watch). If the filesystem monitoring helper program is not available or not desired for other reasons, it is possible to make Unison synchronize repeatedly with a defined time interval:

unison -repeat 60 /path/to/dir ssh://host/path/on/server

This command synchronizes every 60 seconds. Using -repeat implies -batch.

Currently, continuous synchronization is not possible when using the GUI.

DIAGNOSTICS

When running in the textual mode, Unison returns an exit status, which describes whether, and at which level, the synchronization was successful. The exit status could be useful when Unison is invoked from a script. Currently, there are four possible values for the exit status:

0
successful synchronization; everything is up-to-date now.
1
some files were skipped, but all file transfers were successful.
2
non-fatal failures occurred during file transfer.
3
a fatal error occurred, or the execution was interrupted.

The graphical interface does not return any useful information through the exit status.

COMPATIBILITY

If you are using Unison versions ≥ 2.52 on all machines, you do not have to do anything extra for compatibility.

Historically (versions < 2.52), Unison versions had to be matched relatively exactly for them to work together. Additionally, the version of compiler used to build Unison also had significant relevance for compatibility.

As of version 2.52, Unison has a degree of backward and forward compatibility. This means three things. First, it is possible for local and remote machines to run a different version of Unison. Second, it is possible for local and remote machines to run a version (same or different) of Unison built with a different version of compiler. Lastly, it is possible to upgrade Unison on the local machine and keep the existing archive.

For more information on co-existence of versions < 2.52 and ≥ 2.52, see https://github.com/bcpierce00/unison/wiki/2.52-Migration-Guide

SEE ALSO

There is a full user manual (pdf, html and txt) included with Unison and available online. Depending on your operating system, this manual may have been installed at /usr/share/doc/unison/ or a similar location. The manual can also be read in the GUI (look in the Help menu) or on the command line by (you probably want to pipe the output to a pager).

https://github.com/bcpierce00/unison

https://www.cis.upenn.edu/~bcpierce/unison/

March 17, 2022 unison