UNTITLED() LOCAL UNTITLED()
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 col-
lection 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 syn-
chronize data they care about.
Unison shares a number of features with other tools. Some of the distin-
guishing 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 com-
pression 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
Basic options:
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
Advanced options:
Fine-tune sync:
-acl synchronize ACLs
-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)
-xattrignore xxx add a pattern to the xattrignore list
-xattrignorenot xxx add a pattern to the xattrignorenot list
-xattrs synchronize extended attributes (xattrs)
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 (deprecated) maximum number of simultaneous copyprog
transfers
-copyprog xxx (deprecated) external program for copying large files
-copyprogrest xxx (deprecated) variant of copyprog for resuming partial
transfers
-copythreshold n (deprecated) 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
Expert options:
-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 pro-
file. On command line, but not in a profile, the options are specified
with a leading dash. Like this: -option.
acl When this flag is set to true, the ACLs of files and directories
are synchronized. The type of ACLs depends on the platform and
filesystem support. On Unix-like platforms it can be NFSv4 ACLs,
for example.
addprefsto xxx
By default, new preferences added by Unison (e.g., new 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.
addversionno
When this flag is set to true, Unison will use
unison-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.
atomic xxx
This preference specifies paths for directories whose contents
will be considered as a group rather than individually when they
are both modified. The backups are also made atomically in this
case. The option backupcurr however has no effect on atomic
directories.
auto When set to 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.)
backup xxx
Including the preference -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.
backupcurr xxx
Including the preference -backupcurr pathspec causes Unison to
keep a backup of the current 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 documentation 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.
backupcurrnot xxx
Exceptions to backupcurr, like the ignorenot preference.
backupdir xxx
If this preference is set, Unison will use it as the name of the
directory used to store backup files specified by the backup
preference, when backuplocation is set to central. It is
checked after the UNISONBACKUPDIR environment variable.
backuploc xxx
This preference determines whether backups should be kept
locally, near the original files, or in a central directory
specified by the 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.
backupnot xxx
The values of this preference specify paths or individual files
or regular expressions that should not be backed up, even if the
backup preference selects them—i.e., it selectively overrides
backup.
backupprefix xxx
When a backup for a file 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 age 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.
backups
(Deprecated) Setting this flag to true is equivalent to setting
backuplocation to local and backup to Name *.
backupsuffix xxx
See backupprefix for full documentation.
batch When this is set to true, the user interface will ask no
questions at all. Non-conflicting changes will be propagated;
conflicts will be skipped.
clientHostName xxx
When specified, the host name of the client will not be guessed
and the provided host name will be used to find the archive.
color xxx
When set to 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.
confirmbigdel
When this is set to 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.
confirmmerge
Setting this preference causes both the text and graphical
interfaces to ask the user if the results of a merge command may
be committed to the replica or not. Since the merge command
works on temporary files, the user can then cancel all the
effects of applying the merge if it turns out that the result is
not satisfactory. In batch-mode, this preference has no effect.
Default is false.
contactquietly
If this flag is set, Unison will skip displaying the `Contacting
server' message (which some users find annoying) during startup.
copymax n
(Deprecated) A number indicating how many instances of the
external copying utility Unison is allowed to run simultaneously
(default to 1).
copyonconflict
When this flag is set, Unison will make a copy of files that
would otherwise be overwritten or deleted in case of conflicting
changes, and more generally whenever the default behavior is
overridden. This makes it possible to automatically resolve
conflicts in a fairly safe way when synchronizing continuously,
in combination with the -repeat watch and -prefer newer
preferences.
copyprog xxx
(Deprecated) A string giving the name of an external program
that can be used to copy large files efficiently (plus
command-line switches telling it to copy files in-place). The
default setting invokes rsync with appropriate options—most
users should not need to change it.
copyprogrest xxx
(Deprecated) A variant of 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.,
--partial, for rsync). The default setting invokes rsync with
appropriate options—most users should not need to change it.
copythreshold n
(Deprecated) A number indicating above what filesize (in
kilobytes) Unison should use the external copying utility
specified by 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.
debug xxx
This preference is used to make Unison print various sorts of
information about what it is doing internally on the standard
error stream. It can be used many times, each time with the name
of a module for which debugging information should be printed.
Possible arguments for 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).
diff xxx
This preference can be used to control the name and command-line
arguments of the system utility used to generate displays of
file differences. The default is `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.
doc xxx
The command-line argument -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.
dontchmod
By default, Unison uses the 'chmod' system call to set the
permission bits of files after it has copied them. But in some
circumstances (and under some operating systems), the chmod call
always fails. Setting this preference completely prevents Unison
from ever calling chmod.
dumbtty
When set to 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.
dumparchives
When this preference is set, Unison will create a file
unison.dump on each host, containing a text summary of the
archive, immediately after loading it.
fastcheck xxx
When this preference is set to 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 overwrite 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.
fastercheckUNSAFE
THIS FEATURE IS STILL EXPERIMENTAL AND SHOULD BE USED WITH
EXTREME CAUTION. 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
both 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.
fat When this is set to 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.
follow xxx
Including the preference -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.
force xxx
Including the preference -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 a unique prefix or
suffix of the path of one of the roots or a unique prefix of the
hostname of a remote root. 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. If modtimes are equal in both replicas when using
newer or older then this preference will have no effect (changes
will be synced as if without this preference or remain unsynced
in case of a conflict). This preference is overridden by the
forcepartial preference. This preference should be used only if
you are sure you know what you are doing!
forcepartial xxx
Including the preference 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 a unique prefix or suffix of the
path of one of the roots or a unique prefix of the hostname of a
remote root. 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. If modtimes are equal in
both replicas when using newer or older then this preference
will have no effect (changes will be synced as if without this
preference or remain unsynced in case of a conflict). This
preference should be used only if you are sure you know what you
are doing!
group When this flag is set to true, the group attributes of the files
are synchronized. Whether the group names or the group
identifiers are synchronized depends on the preference numerids.
halfduplex
(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.
height n
Used to set the height (in lines) of the main window in the
graphical user interface.
i Provide this preference in the command line arguments to enable
interactive profile manager in the text user interface.
Currently only profile listing and interactive selection are
available. Preferences like batch and silent remain applicable
to synchronization functionality.
ignore xxx
Including the preference -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.
ignorearchives
When this preference is set, Unison will ignore any existing
archive files and behave as though it were being run for the
first time on these replicas. It is not a good idea to set this
option in a profile: it is intended for command-line use.
ignorecase xxx
When set to 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.
ignoreinodenumbers
When set to true, this preference makes Unison not take
advantage of inode numbers during fast update detection. This
switch should be used with care, as it is less safe than the
standard update detection method, but it can be useful with
filesystems which do not support inode numbers.
ignorelocks
When this preference is set, Unison will ignore any lock files
that may have been left over from a previous run of Unison that
was interrupted while reading or writing archive files; by
default, when Unison sees these lock files it will stop and
request manual intervention. This option should be set only if
you are positive 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.
ignorenot xxx
This preference overrides the preference 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
and all its descendants. 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.
immutable xxx
This preference specifies paths for directories whose immediate
children are all immutable files — i.e., once a file has been
created, its contents never changes. When scanning for updates,
Unison does not check whether these files have been modified;
this can speed update detection significantly (in particular,
for mail directories).
immutablenot xxx
This preference overrides immutable.
include xxx
Include preferences from a profile. 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.
key xxx
Used in a profile to define a numeric key (0-9) that can be used
in the user interface to switch immediately to this profile.
killserver
When set to 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.)
label xxx
Used in a profile to provide a descriptive string documenting
its settings. (This is useful for users that switch between
several profiles, especially using the `fast switch' feature of
the graphical user interface.)
links xxx
When set to true, this flag causes Unison to synchronize
symbolic links. When the flag is set to false, symbolic links
will be ignored 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. When the flag is
set to default and symbolic links can't be synchronized then an
error is produced during update detection.
listen xxx
When acting as a server on a TCP socket, Unison will by default
listen on "any" address (0.0.0.0 and [::]). This command-line
argument allows to specify a different listening address and can
be repeated to listen on multiple addresses. Listening address
can be specified as a host name or an IP address.
log When this flag is set, Unison will log all changes to the
filesystems on a file.
logfile xxx
By default, logging messages will be appended to the file
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.
maxbackups n
This preference specifies the number of backup versions that
will be kept by unison, for each path that matches the predicate
backup. The default is 2.
maxerrors n
This preference controls after how many errors Unison aborts a
directory transfer. Setting it to a large number allows Unison
to transfer most of a directory even when some files fail to be
copied. The default is 1. If the preference is set too high,
Unison may take a long time to abort in case of repeated
failures (for instance, when the disk is full).
maxsizethreshold n
A number indicating above what filesize (in kilobytes) Unison
should flag a conflict instead of transferring the file. This
conflict remains even in the presence of force or prefer
options. A negative number will allow every transfer
independently of the size. The default is -1.
maxthreads n
This preference controls how much concurrency is allowed during
the transport phase. Normally, it should be set reasonably high
to maximize performance, but when Unison is used over a
low-bandwidth link it may be helpful to set it lower (e.g. to 1)
so that Unison doesn't soak up all the available bandwidth. The
default is the special value 0, which mean 20 threads when file
content streaming is deactivated and 1000 threads when it is
activated.
merge xxx
This preference can be used to run a merge program which will
create a new version for each of the files and the backup, with
the last backup and both replicas. The syntax of 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.
mountpoint xxx
Including the preference -mountpoint PATH causes Unison to
double-check, at the end of update detection, that PATH 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.
nocreation xxx
Including the preference -nocreation root prevents Unison from
performing any file creation on root root. You can also specify
a unique prefix or suffix of the path of one of the roots or a
unique prefix of the hostname of a remote root. This preference
can be included twice, once for each root, if you want to
prevent any creation.
nocreationpartial xxx
Including the preference 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.
nodeletion xxx
Including the preference -nodeletion root prevents Unison from
performing any file deletion on root root. You can also specify
a unique prefix or suffix of the path of one of the roots or a
unique prefix of the hostname of a remote root. This preference
can be included twice, once for each root, if you want to
prevent any deletion.
nodeletionpartial xxx
Including the preference 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.
noupdate xxx
Including the preference -noupdate root prevents Unison from
performing any file update or deletion on root root. You can
also specify a unique prefix or suffix of the path of one of the
roots or a unique prefix of the hostname of a remote root. This
preference can be included twice, once for each root, if you
want to prevent any update.
noupdatepartial xxx
Including the preference 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.
numericids
When this flag is set to 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.
owner When this flag is set to true, the owner attributes of the files
are synchronized. Whether the owner names or the owner
identifiers are synchronizeddepends on the preference numerids.
path xxx
When no 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.
perms n
The integer value of this preference is a mask indicating which
permission bits should be synchronized. It is set by default to
$0o1777$: all bits but the set-uid and set-gid bits are
synchronised (synchronizing these latter bits can be a security
hazard). If you want to synchronize all bits, you can set the
value of this preference to $-1$. If one of the replica is on a
FAT [Windows] filesystem, you should consider using the 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.
prefer xxx
Including the preference -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.) You
can also specify a unique prefix or suffix of the path of one of
the roots or a unique prefix of the hostname of a remote root.
This preference is overridden by the preferpartial preference.
This preference should be used only if you are sure you know
what you are doing!
preferpartial xxx
Including the preference 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.) You can
also specify a unique prefix or suffix of the path of one of the
roots or a unique prefix of the hostname of a remote root. This
preference should be used only if you are sure you know what you
are doing!
repeat xxx
Setting this preference causes the text-mode interface to
synchronize repeatedly, rather than doing it just once and
stopping. If the argument is a number, Unison will pause for
that many seconds before beginning again. When the argument is
watch, Unison relies on an external file monitoring process to
synchronize whenever a change happens. You can combine the two
with a + character to use file monitoring and also do a full
scan every specified number of seconds. For example, watch+3600
will react to changes immediately and additionally do a full
scan every hour.
retry n
Setting this preference causes the text-mode interface to try
again to synchronize updated paths where synchronization fails.
Each such path will be tried N times.
root xxx
Each use of this preference names the root of one of the
replicas for Unison to synchronize. Exactly two roots are
needed, so normal modes of usage are either to give two values
for 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.
rootalias xxx
When calculating the name of the archive files for a given pair
of roots, Unison replaces any roots matching the left-hand side
of any rootalias rule by the corresponding right-hand side.
rsrc xxx
When set to 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.
rsync Unison uses the 'rsync algorithm' for 'diffs-only' transfer of
updates to large files. Setting this flag to false makes Unison
use whole-file transfers instead. Under normal circumstances,
there is no reason to do this, but if you are having trouble
with repeated 'rsync failure' errors, setting it to false should
permit you to synchronize the offending files.
selftest
Run internal tests and exit. This option is mostly for
developers and must be used carefully: in particular, it will
delete the contents of both roots, so that it can install its
own files for testing. This flag only makes sense on the command
line. When it is provided, no preference file is read: all
preferences must be specified on thecommand line. Also, since
the self-test procedure involves overwriting the roots and
backup directory, the names of the roots and of the backupdir
preference must include the string "test" or else the tests will
be aborted. (If these are not given on the command line, dummy
subdirectories in the current directory will be created
automatically.)
servercmd xxx
This preference can be used to explicitly set the name of the
Unison executable on the remote server (e.g., giving a full path
name), if necessary.
showarchive
When this preference is set, Unison will print out the 'true
names'of the roots, in the same form as is expected by the
rootalias preference.
silent When this preference is set to 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.
socket xxx
Start unison as a server listening on a TCP socket (with TCP
port number as argument) or a local socket (aka Unix domain
socket) (with socket path as argument).
sortbysize
When this flag is set, the user interface will list changed
files by size (smallest first) rather than by name. This is
useful, for example, for synchronizing over slow links, since it
puts very large files at the end of the list where they will not
prevent smaller files from being transferred quickly. 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.
sortfirst xxx
Each argument to 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.
sortlast xxx
Similar to sortfirst, except that files matching one of these
patterns will be listed at the very end.
sortnewfirst
When this flag is set, the user interface will list newly
created files before all others. This is useful, for example,
for checking that newly created files are not `junk', i.e., ones
that should be ignored or deleted rather than synchronized.
source xxx
Include preferences from a file. 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.
sshargs xxx
The string value of this preference will be passed as additional
arguments (besides the host name and the name of the Unison
executable on the remote system) to the ssh command used to
invoke the remote server. The backslash is an escape character.
sshcmd xxx
This preference can be used to explicitly set the name of the
ssh executable (e.g., giving a full path name), if necessary.
stream (Deprecated) When this preference is set, Unison will use an
experimental streaming protocol for transferring file contents
more efficiently. The default value is true.
terse When this preference is set to true, the user interface will not
print status messages.
testserver
Setting this flag on the command line causes Unison to attempt
to connect to the remote server and, if successful, print a
message and immediately exit. Useful for debugging installation
problems. Should not be set in preference files.
times When this flag is set to true, file modification times (but not
directory modtimes) are propagated.
ui xxx This preference selects either the graphical or the textual user
interface. Legal values are graphic or text. Because this
option is processed specially during Unison's start-up sequence,
it can only 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.)
unicode xxx
When set to 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, Latin 1 encoding is
assumed (this means that all bytes that are not letters in Latin
1 encoding will be compared byte-for-byte, even if they may be
valid characters in some other encoding). When Unison runs in
case sensitive mode, this flag only makes a difference if one
host is running Mac OS X. Under Mac OS X, it selects whether
comparing the filenames up to decomposition, or byte-for-byte.
version
Print the current version number and exit. (This option only
makes sense on the command line.)
watch Unison uses a file watcher process, when available, to detect
filesystem changes; this is used to speed up update detection.
Setting this flag to false disables the use of this process.
xattrignore xxx
Preference -xattrignore namespec causes Unison to ignore
extended attributes with names that match namespec. This can be
used to exclude extended attributes that would fail
synchronization due to lack of permissions or technical
differences at replicas. The syntax of namespec is the same as
used for path specification (described in Section “Path
Specification” in the manual); prefer the Path and Regex forms
over the Name form. The pattern is applied to the name of
extended attribute, not to path. On Linux, attributes in the
security and trusted namespaces are ignored by default (this is
achieved by pattern Regex !(security|trusted)[.].*); also
attributes used to store POSIX ACL are ignored by default (this
is achieved by pattern Path !system.posix_acl_*). To sync
attributes in one or both of these namespaces, see the
xattrignorenot preference. Note that the namespace name must be
prefixed with a "!" (applies on Linux only). All names not
prefixed with a "!" are taken as strictly belonging to the user
namespace and therefore the "!user." prefix is never used.
xattrignorenot xxx
This preference overrides the preference xattrignore. It gives
a list of patterns (in the same format as xattrignore) for
extended attributes that should not be ignored, whether or not
they happen to match one of the xattrignore patterns. It is
possible to synchronize only desired attributes by ignoring all
attributes (for example, by setting xattrignore to Path * and
then adding xattrignorenot for extended attributes that should
be synchronized. On Linux, attributes in the security and
trusted namespaces are ignored by default. To sync attributes in
one or both of these namespaces, you may add an xattrignorenot
pattern like Path !security.* to sync all attributes in the
security namespace, or Path !security.selinux to sync a specific
attribute in an otherwise ignored namespace. A pattern like Path
!system.posix_acl_* can be used to sync POSIX ACLs on Linux.
Note that the namespace name must be prefixed with a "!"
(applies on Linux only). All names not prefixed with a "!" are
taken as strictly belonging to the user namespace and therefore
the "!user." prefix is never used.
xattrs When this flag is set to true, the extended attributes of files
and directories are synchronized. System extended attributes are
not synchronized.
xferbycopying
When this preference is set, Unison will try to avoid
transferring file contents across the network by recognizing
when a file with the required contents already exists in the
target replica. This usually allows file moves to be propagated
very quickly. The default value is true.
ROOTS
A replica’s root tells Unison where to find a set of files to be syn-
chronized, 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, indepen-
dent 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 Neighbor-
hood. For example,
unison foo //host/drive/bar
synchronizes the local directory foo with the directory drive:\bar on
the machine host, provided that host is accessible via Network Neighbor-
hood. 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 Uni-
son 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 de-
tect 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 char-
acter is always a forward slash, no matter what operating system Unison
is running on. The empty path (i.e., the empty sequence of names) de-
notes the whole replica.
PATH SPECIFICATION
Several Unison preferences (e.g., ignore/ignorenot, follow,
sortfirst/sortlast, 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 Regex. (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, stan-
dard “globbing” conventions can be used in name and path:
- a * matches any sequence of characters not including / (and not be-
ginning with ., when used at the beginning of a name)
- a ? matches any single character except / (and leading .)
- [xyz] matches any character from the set {x, y, z}
- {a,bb,ccc} 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 charac-
ter “/” — 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 sys-
tems.
A path specification may be followed by the separator “ -> ” itself fol-
lowed 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 path-
spec 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 de-
limiter. 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 name.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 prefer-
ences.
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.
TERMINATION
When not synchronizing continuously, the text interface terminates when
synchronization is finished normally or due to a fatal error occurring.
In the text interface, to interrupt synchronization before it is fin-
ished, press Ctrl-C (or send signal SIGINT or SIGTERM). This will in-
terrupt update propagation as quickly as possible but still complete
proper cleanup. If the process does not stop even after pressing Ctrl-C
then keep doing it repeatedly. This will bypass cleanup procedures and
terminates the process forcibly (similar to SIGKILL). Doing so may
leave the archives or replicas in an inconsistent state or locked.
When synchronizing continuously (time interval repeat or with filesystem
monitoring), interrupting with Ctrl-C or with signal SIGINT or SIGTERM
works the same way as described above and will additionally stop the
continuous process. To stop only the continuous process and let the last
synchronization complete normally, send signal SIGUSR2 instead.
ENVIRONMENT
UNISON 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 USERPROFILE 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.
UNISONLOCALHOSTNAME
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 synchro-
nized) normally uses the gethostname operating system call. How-
ever, if the environment variable UNISONLOCALHOSTNAME is set,
its value will be used instead. This makes it easier to use Uni-
son in situations where a machine’s name changes frequently
(e.g., because it is a laptop and gets moved around a lot).
UNISONBACKUPDIR
When backups are stored centrally, the directory used to hold
them is controlled by the preference backupdir and the environ-
ment 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).
PAGER Used by the text interface as the pager when displaying the dif-
ferences between changed files.
NO_COLOR
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
profilename.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 equiva-
lent 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
unsynchronized 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
Synchronize two local directories
unison path/to/dir1 /dir2
This command synchronizes two local directories using the default op-
tions. 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
Synchronize a local and a remote directory
unison local/dir ssh://user@host//absolute/path
This command synchronizes a local directory (here specified by a rela-
tive path) and a remote directory (here specified by an absolute path)
using ssh(1) and the default options (see example above).
Synchronize with all options specified in a profile
unison profilename
This command reads all the options from the profile named
“profilename” and synchronizes according to those options.
Synchronize with options specified in a profile and roots on command
line
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 over-
ride roots in the profile, rather append to the list of roots.
Synchronize automatically
unison -batch /path/to/dir ssh://host/path/on/server
This command synchronizes all non-conflicting changes automatically,
once.
Synchronize continuously
unison -repeat watch /path/to/dir ssh://host/path/on/server
This command first fully synchronizes the roots and then remains dor-
mant, waiting for any file changes within either root and then auto-
matically 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 success-
ful. 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 rela-
tively exactly for them to work together. Additionally, the version of
compiler used to build Unison also had significant relevance for compat-
ibility.
As of version 2.52, Unison has a degree of backward and forward compati-
bility. This means three things. First, it is possible for local and
remote machines to run a different version of Unison. Second, it is pos-
sible for local and remote machines to run a version (same or different)
of Unison built with a different version of compiler. Lastly, it is pos-
sible 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 unison -doc all (you probably want to pipe the output to
a pager).
https://github.com/bcpierce00/unison
unison March 17, 2022 UNISON(1)
Generated by dwww version 1.16 on Tue Dec 16 06:23:19 CET 2025.