.\" Unison file synchronizer: man/unison.1
.\" Copyright 1999-2022, Unison authors
.\"
.\" This program is free software: you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation, either version 3 of the License, or
.\" (at your option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see .
.\"
.Dd March 17, 2022
.Os unison
.Dt UNISON 1 URM
.Sh NAME
.Nm unison
.Nd a multi-platform bi-directional file synchronization tool
.Sh SYNOPSIS
.Nm
.Op Ar options
.Nm
.Ar root1 root2
.Op Ar options
.Nm
.Ar profilename
.Op Ar options
.Sh DESCRIPTION
.Nm 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.
.Pp
Unison has been in use for over 20 years and many people use it to synchronize
data they care about.
.Pp
Unison shares a number of features with other tools. Some of the distinguishing
features are:
.Bl -bullet -compact
.It
Unlike simple mirroring or backup utilities, Unison can deal with updates to
both replicas of a distributed directory structure.
.It
Unison works across platforms, allowing you to synchronize a Windows laptop
with a Unix server, for example.
.It
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.
.It
Unison works between any pair of machines connected to the internet, typically
communicating over
.Xr 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
.Xr rsync 1 .
.It
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.
.El
.Sh OPTION SUMMARY
.Bd -literal
.Sy "Basic options:"
.Sy " General:"
-doc xxx show documentation ('-doc topics' lists topics)
-version print version and exit
.Sy " 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
.Sy " How to sync:"
-batch batch mode: ask no questions at all
.Sy " How to sync (text interface (CLI) only):"
-auto automatically accept default (nonconflicting) actions
-silent print nothing except error messages
-terse suppress status messages
.Sy " Text interface (CLI):"
-i interactive profile mode (text UI); command-line only
.Sy "Advanced options:"
.Sy " 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)
.Sy " 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
.Sy " 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)
.Sy " Text interface (CLI):"
-color xxx use color output for text UI (true/false/default)
-dumbtty do not change terminal settings in text UI
.Sy " Graphical interface (GUI):"
-height n height (in lines) of main window in graphical interface
.Sy " 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)
.Sy " Archive management:"
-ignorearchives ignore existing archive files
.Sy " 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
.Sy "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
.Ed
.Sh 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:
.Fl option .
.Bl -tag
.It Ic addprefsto Ar xxx
.No By default, new preferences added by Unison (e.g., new
.Ic ignore
.No clauses) will be appended to whatever preference file Unison was told to load at the beginning of the run. \&Setting the preference
.Sy addprefsto
.Ar filename
.No makes Unison add new preferences to the file named
.Ar filename
.No instead.
.It Ic addversionno
.No When this flag is set to
.Sy true Ns ,
.No Unison will use
.Sy unison- Ns Ar currentmajorversionnumber
.No instead of just
.Ic unison
.No 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.
.It Ic atomic Ar xxx
.No 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
.Sy backupcurr
.No however has no effect on atomic directories.
.It Ic auto
.No When set to
.Sy true Ns ,
.No 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.)
.It Ic backup Ar xxx
.No Including the preference
.Sy -backup
.Ar pathspec
.No causes Unison to keep backup files for each path that matches
.Ar pathspec Ns ;
.No directories (nor their permissions or any other metadata) are not backed up. \&These backup files are kept in the directory specified by the
.Ic backuplocation
.No preference. \&The backups are named according to the
.Ic backupprefix
.No and
.Ic backupsuffix
.No preferences. \&The number of versions that are kept is determined by the
.Ic maxbackups
.No preference.
.No \&The syntax of
.Ar pathspec
.No is described in Section
.Dq Path Specification
.No in the manual.
.It Ic backupcurr Ar xxx
.No Including the preference
.Sy -backupcurr
.Ar pathspec
.No causes Unison to keep a backup of the
.Em current
.No version of every file matching
.Ar pathspec Ns .
.No \&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
.Ic merge
.No preference. \&For more details, see Section
.Dq Merging Conflicting Versions
.No in the manual.
.No \&The syntax of
.Ar pathspec
.No is described in Section
.Dq Path Specification
.No in the manual.
.It Ic backupcurrnot Ar xxx
.No Exceptions to
.Ic backupcurr Ns ,
.No like the
.Ic ignorenot
.No preference.
.It Ic backupdir Ar xxx
.No If this preference is set, Unison will use it as the name of the directory used to store backup files specified by the
.Sy backup
.No preference, when
.Sy backuplocation
.No is set to
.Ic central Ns .
.No \&It is checked
.Em after
.No the
.Sy UNISONBACKUPDIR
.No environment variable.
.It Ic backuploc Ar xxx
.No This preference determines whether backups should be kept locally, near the original files, or in a central directory specified by the
.Sy backupdir
.No preference. \&If set to
.Ic local Ns ,
.No backups will be kept in the same directory as the original files, and if set to
.Ic central Ns ,
.Sy backupdir
.No will be used instead.
.It Ic backupnot Ar xxx
.No The values of this preference specify paths or individual files or regular expressions that should
.Em not
.No be backed up, even if the
.Sy backup
.No preference selects them—i.e., it selectively overrides
.Sy backup Ns .
.It Ic backupprefix Ar xxx
.No When a backup for a file
.Ic NAME
.No is created, it is stored in a directory specified by
.Sy backuplocation Ns ,
.No in a file called
.Sy backupprefix Ns Ic NAME Ns
.Sy backupsuffix Ns .
.Sy backupprefix
.No can include a directory name (causing Unison to keep all backup files for a given directory in a subdirectory with this name), and both
.Sy backupprefix
.No and
.Sy backupsuffix
.No can contain the string
.Ar $VERSION Ns ,
.No which will be replaced by the
.Em age
.No 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.
.No \&One thing to be careful of: If the
.Sy backuploc
.No preference is set to
.Sy local Ns ,
.No Unison will automatically ignore
.Em all
.No files whose prefix and suffix match
.Sy backupprefix
.No and
.Sy backupsuffix Ns .
.No \&So be careful to choose values for these preferences that are sufficiently different from the names of your real files.
.It Ic backups
.Em ( Deprecated )
.No Setting this flag to true is equivalent to setting
.Sy backuplocation
.No to
.Sy local
.No and
.Sy backup
.No to
.Ic Name * Ns .
.It Ic backupsuffix Ar xxx
.No See
.Sy backupprefix
.No for full documentation.
.It Ic batch
.No When this is set to
.Sy true Ns ,
.No the user interface will ask no questions at all. \&Non-conflicting changes will be propagated; conflicts will be skipped.
.It Ic clientHostName Ar xxx
.No When specified, the host name of the client will not be guessed and the provided host name will be used to find the archive.
.It Ic color Ar xxx
.No When set to
.Sy true Ns ,
.No this flag enables color output in text mode user interface. \&When set to
.Sy false Ns ,
.No all color output is disabled. \&Default is to enable color if the
.Sy NO_COLOR
.No environment variable is not set.
.It Ic confirmbigdel
.No When this is set to
.Sy true Ns ,
.No Unison will request an extra confirmation if it appears that the entire replica has been deleted, before propagating the change. \&If the
.Sy batch
.No flag is also set, synchronization will be aborted. \&When the
.Sy path
.No 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
.Sy mountpoint
.No preference.
.It Ic confirmmerge
.No 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.
.It Ic contactquietly
.No If this flag is set, Unison will skip displaying the `Contacting server' message (which some users find annoying) during startup.
.It Ic copymax Ar n
.No A number indicating how many instances of the external copying utility Unison is allowed to run simultaneously (default to 1).
.It Ic copyonconflict
.No 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
.Ic -repeat watch
.No and
.Ic -prefer newer
.No preferences.
.It Ic copyprog Ar xxx
.No 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
.Sy rsync
.No with appropriate options—most users should not need to change it.
.It Ic copyprogrest Ar xxx
.No A variant of
.Sy copyprog
.No that names an external program that should be used to continue the transfer of a large file that has already been partially transferred. \&Typically,
.Sy copyprogrest
.No will just be
.Sy copyprog
.No with one extra option (e.g.,
.Sy --partial Ns ,
.No for rsync). \&The default setting invokes
.Sy rsync
.No with appropriate options—most users should not need to change it.
.It Ic copyquoterem Ar xxx
.No When set to
.Sy true Ns ,
.No 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
.Sy default Ns ,
.No extra quotes are added if the value of
.Sy copyprog
.No contains the string
.Sy rsync Ns .
.It Ic copythreshold Ar n
.No A number indicating above what filesize (in kilobytes) Unison should use the external copying utility specified by
.Sy copyprog Ns .
.No \&Specifying 0 will cause
.Em all
.No copies to use the external program; a negative number will prevent any files from using it. \&The default is -1. \&See Section
.Dq Making Unison Faster on Large Files
.No in the manual for more information.
.It Ic debug Ar xxx
.No 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
.Ic debug
.No can be found by looking for calls to
.Ic Util.debug
.No in the sources (using, e.g.,
.Ic grep Ns ).
.No \&Setting
.Ic -debug all
.No causes information from
.Em all
.No 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);
.Ic -debug verbose
.No turns on some additional debugging output from some modules (e.g., it will show exactly what bytes are being sent across the network).
.It Ic diff Ar xxx
.No 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 ` Ns Ic diff -u OLDER NEWER Ns '.
.No \&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.
.It Ic doc Ar xxx
.No The command-line argument
.Sy -doc
.Ar secname
.No causes unison to display section
.Ar secname
.No of the manual on the standard output and then exit. \&Use
.Ic -doc all
.No to display the whole manual, which includes exactly the same information as the printed and HTML manuals, modulo formatting. \&Use
.Ic -doc topics
.No to obtain a list of the names of the various sections that can be printed.
.It Ic dontchmod
.No 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.
.It Ic dumbtty
.No When set to
.Ic true Ns ,
.No 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.
.No \&When
.Ic dumbtty
.No 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.)
.No This preference has no effect on the graphical user interface.
.It Ic dumparchives
.No 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.
.It Ic fastcheck Ar xxx
.No When this preference is set to
.Ic true Ns ,
.No Unison will use the modification time and length of a file as a
.No `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
.Em overwrite
.No 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
.Sy fastcheck
.No set to
.Ic false Ns ,
.No if you are worried that Unison may have overlooked an update. \&For backward compatibility,
.Ic yes Ns ,
.Ic no Ns ,
.No and
.Ic default
.No can be used in place of
.Ic true Ns ,
.Ic false Ns ,
.No and
.Ic auto Ns .
.No \&See Section
.Dq Fast Update Detection
.No in the manual for more information.
.It Ic fastercheckUNSAFE
.No THIS FEATURE IS STILL EXPERIMENTAL AND SHOULD BE USED WITH EXTREME CAUTION.
.No \&When this flag is set to
.Sy true Ns ,
.No 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
.Em both
.No 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.
.No \&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.
.No \&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.
.It Ic fat
.No When this is set to
.Sy true Ns ,
.No 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 ( Ns Sy perms = 0 Ns );
.No never use chmod ( Ns Sy dontchmod = true Ns );
.No treat filenames as case insensitive ( Ns Sy ignorecase = true Ns );
.No do not attempt to synchronize symbolic links ( Ns Sy links = false Ns );
.No ignore inode number changes when detecting updates ( Ns Sy ignoreinodenumbers = true Ns ).
.No \&Any of these change can be overridden by explicitly setting the corresponding preference in the profile.
.It Ic follow Ar xxx
.No Including the preference
.Sy -follow
.Ar pathspec
.No causes Unison to treat symbolic links matching
.Ar pathspec
.No as `invisible' and behave as if the object pointed to by the link had appeared literally at this position in the replica. \&See Section
.Dq Symbolic Links
.No in the manual for more details. \&The syntax of
.Ar pathspec
.No is described in Section
.Dq Path Specification
.No in the manual.
.It Ic force Ar xxx
.No Including the preference
.Sy -force
.Ar root
.No causes Unison to resolve all differences (even non-conflicting changes) in favor of
.Ar root Ns .
.No \&This effectively changes Unison from a synchronizer into a mirroring utility.
.No \&You can also specify
.Ic -force newer
.No (or
.Ic -force older Ns )
.No to force Unison to choose the file with the later (earlier) modtime. \&In this case, the
.Ic -times
.No preference must also be enabled.
.No \&This preference is overridden by the
.Ic forcepartial
.No preference.
.No \&This preference should be used only if you are
.Em sure
.No you know what you are doing!
.It Ic forcepartial Ar xxx
.No Including the preference
.Sy forcepartial =
.Ar PATHSPEC
.No ->
.Ar root
.No causes Unison to resolve all differences (even non-conflicting changes) in favor of
.Ar root
.No for the files in
.Ar PATHSPEC
.No (see Section
.Dq Path Specification
.No in the manual for more information). \&This effectively changes Unison from a synchronizer into a mirroring utility.
.No \&You can also specify
.Ic forcepartial PATHSPEC -> newer
.No (or
.Ic forcepartial PATHSPEC older Ns )
.No to force Unison to choose the file with the later (earlier) modtime. \&In this case, the
.Ic -times
.No preference must also be enabled.
.No \&This preference should be used only if you are
.Em sure
.No you know what you are doing!
.It Ic group
.No When this flag is set to
.Ic true Ns ,
.No the group attributes of the files are synchronized. \&Whether the group names or the group identifiers are synchronized depends on the preference
.Sy numerids Ns .
.It Ic halfduplex
.Em ( Deprecated )
.No When this flag is set to
.Sy true Ns ,
.No 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.
.It Ic height Ar n
.No Used to set the height (in lines) of the main window in the graphical user interface.
.It Ic i
.No 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
.Sy batch
.No and
.Sy silent
.No remain applicable to synchronization functionality.
.It Ic ignore Ar xxx
.No Including the preference
.Sy -ignore
.Ar pathspec
.No causes Unison to completely ignore paths that match
.Ar pathspec
.No (as well as their children). \&This is useful for avoiding synchronizing temporary files, object files, etc. \&The syntax of
.Ar pathspec
.No is described in Section
.Dq Path Specification
.No in the manual, and further details on ignoring paths is found in Section
.Dq Ignoring Paths
.No in the manual.
.It Ic ignorearchives
.No 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.
.It Ic ignorecase Ar xxx
.No When set to
.Sy true Ns ,
.No 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
.Sy false Ns ,
.No Unison will treat all filenames as case sensitive. \&Ordinarily, when the flag is set to
.Sy default Ns ,
.No 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.
.It Ic ignoreinodenumbers
.No 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.
.It Ic ignorelocks
.No 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
.Em positive
.No 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.
.It Ic ignorenot Ar xxx
.No This preference overrides the preference
.Sy ignore Ns .
.No \&It gives a list of patterns
.No (in the same format as
.Ic ignore Ns )
.No for paths that should definitely
.Em not
.No be ignored,
.No whether or not they happen to match one of the
.Ic ignore
.No patterns.
.No Note that the semantics of
.Sy ignore
.No and
.Sy ignorenot
.No is a
.No little counter-intuitive. \&When detecting updates, Unison examines
.No paths in depth-first order, starting from the roots of the replicas
.No and working downwards. \&Before examining each path, it checks whether
.No it matches
.Sy ignore
.No and does not match
.Sy ignorenot Ns ;
.No in this case
.No it skips this path
.Em and all its descendants Ns .
.No \&This means that,
.No if some parent of a given path matches an
.Sy ignore
.No pattern, then
.No it will be skipped even if the path itself matches an
.Sy ignorenot Ns
.No pattern. \&In particular, putting
.Sy ignore = Path *
.No in your profile
.No and then using
.Sy ignorenot
.No to select particular paths to be
.No synchronized will not work. \&Instead, you should use the
.Sy path Ns
.No preference to choose particular paths to synchronize.
.It Ic immutable Ar xxx
.No 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).
.It Ic immutablenot Ar xxx
.No This preference overrides
.Sy immutable Ns .
.It Ic include Ar xxx
.No Include preferences from a profile.
.Sy include
.Ar name
.No reads the profile
.Dq name
.No (or file
.Dq name
.No in the
.Sy .unison
.No directory if profile
.Dq name
.No does not exist) and includes its contents as if it was part of a profile or given directly on command line.
.It Ic key Ar xxx
.No 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.
.It Ic killserver
.No When set to
.Ic true Ns ,
.No this flag causes Unison to kill the remote server process when the synchronization is finished. \&This behavior is the default for
.Ic ssh
.No connections, so this preference is not normally needed when running over
.Ic ssh Ns ;
.No 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.)
.It Ic label Ar xxx
.No 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.)
.It Ic links Ar xxx
.No When set to
.Sy true Ns ,
.No this flag causes Unison to synchronize symbolic links. \&When the flag is set to
.Sy false Ns ,
.No symbolic links will result in an error during update detection. \&Ordinarily, when the flag is set to
.Sy default Ns ,
.No 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.
.It Ic listen Ar xxx
.No 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.
.It Ic log
.No When this flag is set, Unison will log all changes to the filesystems
.No on a file.
.It Ic logfile Ar xxx
.No By default, logging messages will be appended to the file
.Ic unison.log
.No in your .unison directory. \&Set this preference if
.No you prefer another file. \&It can be a path relative to your .unison directory.
.No \&Sending SIGUSR1 will close the logfile; the logfile will be re-opened (and
.No created, if needed) automatically, to allow for log rotation.
.It Ic maxbackups Ar n
.No This preference specifies the number of backup versions that will be kept by unison, for each path that matches the predicate
.Ic backup Ns .
.No \&The default is 2.
.It Ic maxerrors Ar n
.No 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).
.It Ic maxsizethreshold Ar n
.No 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.
.It Ic maxthreads Ar n
.No 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 desactivated and 1000 threads when it is activated.
.It Ic merge Ar xxx
.No 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
.Ar pathspec -> cmd
.No is described in Section
.Dq Path Specification
.No in the manual, and further details on Merging functions are present in Section
.Dq Merging Conflicting Versions
.No in the manual.
.It Ic mountpoint Ar xxx
.No Including the preference
.Sy -mountpoint PATH
.No causes Unison to double-check, at the end of update detection, that
.Sy PATH
.No 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
.Dq Mount Points and Removable Media
.No in the manual.
.It Ic nocreation Ar xxx
.No Including the preference
.Sy -nocreation
.Ar root
.No prevents Unison from performing any file creation on root
.Ar root Ns .
.No \&This
.No preference can be included twice, once for each root, if you want to prevent any creation.
.It Ic nocreationpartial Ar xxx
.No Including the preference
.Sy nocreationpartial =
.Ar PATHSPEC
.No ->
.Ar root
.No prevents Unison from performing any file creation in
.Ar PATHSPEC
.No on root
.Ar root
.No (see Section
.Dq Path Specification
.No in the manual for more information). \&It is recommended to use
.Sy BelowPath
.No patterns when selecting a directory and all its contents.
.It Ic nodeletion Ar xxx
.No Including the preference
.Sy -nodeletion
.Ar root
.No prevents Unison from performing any file deletion on root
.Ar root Ns .
.No \&This
.No preference can be included twice, once for each root, if you want to prevent any deletion.
.It Ic nodeletionpartial Ar xxx
.No Including the preference
.Sy nodeletionpartial =
.Ar PATHSPEC
.No ->
.Ar root
.No prevents Unison from performing any file deletion in
.Ar PATHSPEC
.No on root
.Ar root
.No (see Section
.Dq Path Specification
.No in the manual for more information). \&It is recommended to use
.Sy BelowPath
.No patterns when selecting a directory and all its contents.
.It Ic noupdate Ar xxx
.No Including the preference
.Sy -noupdate
.Ar root
.No prevents Unison from performing any file update or deletion on root
.Ar root Ns .
.No \&This
.No preference can be included twice, once for each root, if you want to prevent any update.
.It Ic noupdatepartial Ar xxx
.No Including the preference
.Sy noupdatepartial =
.Ar PATHSPEC
.No ->
.Ar root
.No prevents Unison from performing any file update or deletion in
.Ar PATHSPEC
.No on root
.Ar root
.No (see Section
.Dq Path Specification
.No in the manual for more information). \&It is recommended to use
.Sy BelowPath
.No patterns when selecting a directory and all its contents.
.It Ic numericids
.No When this flag is set to
.Ic true Ns ,
.No groups and users are synchronized numerically, rather than by name.
.No \&The special uid 0 and the special group 0 are never mapped via user/group names even if this preference is not set.
.It Ic owner
.No When this flag is set to
.Ic true Ns ,
.No the owner attributes of the files are synchronized. \&Whether the owner names or the owner identifiers are synchronizeddepends on the preference
.Sy numerids Ns .
.It Ic path Ar xxx
.No When no
.Ic path
.No preference is given, Unison will simply synchronize the two entire replicas, beginning from the given pair of roots. \&If one or more
.Ic path
.No 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
.Sy path
.No preferences are interpreted literally—they are not regular expressions.
.It Ic perms Ar n
.No 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 theses 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
.Sy fat
.No 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
.Sy dontchmod
.No to
.Sy true Ns .
.It Ic prefer Ar xxx
.No Including the preference
.Sy -prefer
.Ar root
.No causes Unison always to resolve conflicts in favor of
.Ar root Ns ,
.No rather than asking for guidance from the user, except for paths marked by the preference
.Sy merge Ns .
.No (The syntax of
.Ar root
.No is the same as for the
.Ic root
.No preference, plus the special values
.Ic newer
.No and
.Ic older Ns .)
.No This preference is overridden by the
.Ic preferpartial
.No preference.
.No \&This preference should be used only if you are
.Em sure
.No you know what you are doing!
.It Ic preferpartial Ar xxx
.No Including the preference
.Sy preferpartial =
.Ar PATHSPEC
.No ->
.Ar root
.No causes Unison always to resolve conflicts in favor of
.Ar root Ns ,
.No rather than asking for guidance from the user, for the files in
.Ar PATHSPEC
.No (see Section
.Dq Path Specification
.No in the manual for more information). (The syntax of
.Ar root
.No is the same as for the
.Ic root
.No preference, plus the special values
.Ic newer
.No and
.Ic older Ns .)
.No This preference should be used only if you are
.Em sure
.No you know what you are doing!
.It Ic repeat Ar xxx
.No 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
.Ic watch Ns ,
.No Unison relies on an external file monitoring process to synchronize whenever a change happens.
.It Ic retry Ar n
.No 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.
.It Ic root Ar xxx
.No 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
.Ic root
.No 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
.Dq Roots
.No in the manual.
.No \&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.
.It Ic rootalias Ar xxx
.No 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.
.It Ic rsrc Ar xxx
.No When set to
.Sy true Ns ,
.No 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
.Sy false Ns ,
.No Unison will not synchronize these data. \&Ordinarily, the flag is set to
.Sy default Ns ,
.No and these data are
.No automatically synchronized if either host is running OSX. \&In rare circumstances it is useful to set the flag manually.
.It Ic rsync
.No 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.
.It Ic selftest
.No 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.)
.It Ic servercmd Ar xxx
.No 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.
.It Ic showarchive
.No When this preference is set, Unison will print out the 'true names'of the roots, in the same form as is expected by the
.Sy rootalias
.No preference.
.It Ic silent
.No When this preference is set to
.Sy true Ns ,
.No the textual user interface will print nothing at all, except in the case of errors. \&Setting
.Sy silent
.No to true automatically sets the
.Sy batch
.No preference to
.Sy true Ns .
.It Ic socket Ar xxx
.No 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).
.It Ic sortbysize
.No 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.
.No \&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.
.It Ic sortfirst Ar xxx
.No Each argument to
.Sy sortfirst
.No is a pattern
.Ar pathspec Ns ,
.No which describes a set of paths. \&Files matching any of these patterns will be listed first in the user interface. \&The syntax of
.Ar pathspec
.No is described in Section
.Dq Path Specification
.No in the manual.
.It Ic sortlast Ar xxx
.No Similar to
.Ic sortfirst Ns ,
.No except that files matching one of these patterns will be listed at the very end.
.It Ic sortnewfirst
.No 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.
.It Ic source Ar xxx
.No Include preferences from a file.
.Sy source
.Ar name
.No reads the file
.Dq name
.No in the
.Sy .unison
.No directory and includes its contents as if it was part of a profile or given directly on command line.
.It Ic sshargs Ar xxx
.No 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
.Ic ssh
.No command used to invoke the remote server. \&The backslash is an escape character.
.It Ic sshcmd Ar xxx
.No This preference can be used to explicitly set the name of the ssh executable (e.g., giving a full path name), if necessary.
.It Ic stream
.Em ( Deprecated )
.No When this preference is set, Unison will use an experimental streaming protocol for transferring file contents more efficiently. \&The default value is
.Sy true Ns .
.It Ic terse
.No When this preference is set to
.Sy true Ns ,
.No the user interface will not print status messages.
.It Ic testserver
.No 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.
.It Ic times
.No When this flag is set to
.Ic true Ns ,
.No file modification times (but not directory modtimes) are propagated.
.It Ic ui Ar xxx
.No This preference selects either the graphical or the textual user interface. \&Legal values are
.Ic graphic
.No or
.Ic text Ns .
.No \&Because this option is processed specially during Unison's start-up sequence, it can
.Em only
.No be used on the command line. \&In preference files it has no effect.
.No \&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.)
.It Ic unicode Ar xxx
.No When set to
.Sy true Ns ,
.No this flag causes Unison to perform case insensitive file comparisons assuming Unicode encoding. \&This is the default. \&When the flag is set to
.Sy false Ns ,
.No 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.
.It Ic version
.No Print the current version number and exit. (This option only makes sense on the command line.)
.It Ic watch
.No 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.
.It Ic xferbycopying
.No 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
.Sy true Ns .
.El
.Sh 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,
.Pp
.Dl relative/path/of/root
.Pp
specifies a local root relative to the directory where Unison is started, while
.Pp
.Dl /absolute/path/of/root
.Pp
specifies a root relative to the top of the local filesystem, independent of
where Unison is running. Remote roots can begin with
.Sy ssh://
to indicate that the remote server should be started with
.Xr ssh 1 :
.Pp
.Dl ssh://remotehost//absolute/path/of/root
.Dl ssh://user@remotehost/relative/path/of/root
.Pp
If the remote server is already running (in the socket mode), then the syntax
.Pp
.Dl socket://remotehost:portnum//absolute/path/of/root
.Dl socket://remotehost:portnum/relative/path/of/root
.Dl socket://[IPv6literal]:portnum/path
.Pp
is used to specify the hostname and the port that the client Unison should use
to contact it. Syntax
.Pp
.Dl socket://{path/of/socket}//absolute/path/of/root
.Dl socket://{path/of/socket}/relative/path/of/root
.Pp
is used to specify the Unix domain socket the client Unison should use to
contact the server.
.Pp
The syntax for roots is based on that of URIs (described in RFC 2396). The full
grammar is:
.Bd -literal
replica ::= [protocol:]//[user@][host][:port][/path]
| path
protocol ::= file
| socket
| ssh
user ::= [-_a-zA-Z0-9]+
host ::= [-_a-zA-Z0-9.]+
| \e[ [a-f0-9:.]+ zone? \e] IPv6 literals (no future format).
| { [^}]+ } For Unix domain sockets only.
zone ::= %[-_a-zA-Z0-9~%.]+
port ::= [0-9]+
.Ed
When path is given without any protocol prefix, the protocol is assumed to be
.Sy file: .
Under Windows, it is possible to synchronize with a remote directory using the
.Sy file:
protocol over the Windows Network Neighborhood. For example,
.Pp
.Dl unison foo //host/drive/bar
.Pp
synchronizes the local directory
.Pa foo
with the directory
.Pa drive:\ebar
on the machine
.Sy host ,
provided that host is accessible via Network Neighborhood. When the
.Sy 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.
.Sh 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.
.Sh PATH SPECIFICATION
Several Unison preferences (e.g.,
.Sy 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.
.Pp
Each pattern can have one of three forms. The most general form is a Posix
extended regular expression introduced by the keyword
.Sy Regex .
(The collating sequences and character classes of full Posix regexps are not
currently supported.)
.Pp
.Dl Cm Regex Ar regexp
.Pp
For convenience, three other styles of pattern are also recognized:
.Pp
.Dl Cm Name Ar name
.Pp
matches any path in which the last component matches
.Ar name ,
.Pp
.Dl Cm Path Ar path
.Pp
matches exactly the path
.Ar path ,
and
.Pp
.Dl Cm BelowPath Ar path
.Pp
matches the path
.Ar path
and any path below. The
.Ar name
and
.Ar path
arguments of the latter forms of patterns are
.Em not
regular expressions. Instead, standard
.Dq globbing
conventions can be used in
.Ar name
and
.Ar path :
.Bl -dash
.It
a
.Sy "*"
matches any sequence of characters not including / (and not beginning with .,
when used at the beginning of a
.Ar name )
.It
a
.Sy \&?
matches any single character except / (and leading .)
.It
.Sy [xyz]
matches any character from the set {x, y, z}
.It
.Sy {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!)
.El
.Pp
The path separator in path patterns is always the forward-slash character
.Dq /
— 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.
.Pp
A path specification may be followed by the separator
.Dq " -> "
itself followed by a string which will be associated to the matching paths:
.Pp
.Dl Cm Path Ar path No -> Ar "associated string"
.Pp
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.
.Sh 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
.Pa .unison
directory on the client machine. If Unison is started with just one argument
.Ar name
on the
command line, it looks for a profile called
.Em name Ns Sy .prf
in the
.Pa .unison
directory. If it is started with no arguments, it scans the
.Pa .unison
directory for files whose names end in
.Sy .prf
and offers a menu (when using the graphical user interface; for the text
interface, you have to use the
.Fl i
option). If a file named
.Pa default.prf
is found, its settings will be used as the default preferences.
.Pp
To set the value of a preference
.Sy p
permanently, add to the appropriate profile a line of the form
.Pp
.Dl p = true
.Pp
for a boolean flag or
.Pp
.Dl p =
.Pp
for a preference of any other type.
Whitespaces around
.Sy p
and the value are ignored. A profile may also include blank lines and lines
beginning with #; both are ignored.
.Pp
When Unison starts, it first reads the profile and then the command line, so
command-line options will override settings from the profile.
.Sh ENVIRONMENT
.Bl -tag
.It Ev UNISON
Unison stores a variety of information in a private directory on each host. If
the environment variable
.Sy 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
.Sy UNISON
is not defined, then the directory depends on which operating system you are
using. In Unix, the default is to use
.Pa $HOME/.unison .
In Windows, if the environment variable
.Sy USERPROFILE
is defined, then the directory will be
.Pa $USERPROFILE\e.unison ;
otherwise, it will be
.Pa c:\e.unison .
On macOS,
.Pa $HOME/.unison
will be used if it is present, but
.Pa "$HOME/Library/Application Support/Unison"
will be created and used by default.
.It Ev 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 synchronized) normally uses the
.Sy gethostname
operating system call. However, if the environment variable
.Sy 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).
.It Ev UNISONBACKUPDIR
When backups are stored centrally, the directory used to hold them is
controlled by the preference
.Sy backupdir
and the environment variable
.Sy UNISONBACKUPDIR .
If both are specified then the environment variable overrides the preference.
If neither of these are set, then the directory
.Pa $UNISON/backup
is used (see environment variable
.Sy UNISON
above).
.It Ev PAGER
Used by the text interface as the pager when displaying the differences between
changed files.
.It Ev NO_COLOR
If the environment variable
.Sy NO_COLOR
is set then Unison's text interface will not produce any color output by
default. The
.Sy color
preference overrides this environment variable.
.El
.Sh FILES
.Bl -tag -compact
.It Pa ~/.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
.Sy UNISON
environment variable.
.Pp
.It Pa ~/.unison/*.prf
Profile files. Each profile is stored in a file named
.Em profilename Ns Sy .prf .
.Pp
.It Pa ~/.unison/ar*
.It Pa ~/.unison/tm*
.It Pa ~/.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
.Fl ignorearchives
option.
.Pp
.It Pa ~/.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.
.Pp
.It Pa ~/.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
.Fl ignorelocks
option.
.El
.Sh EXAMPLES
.Bl -tag -width ""
.It Sy Synchronize two local directories
.Pp
.Dl unison path/to/dir1 /dir2
.Pp
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
.Dq default ,
which is by default stored in file
.Pa ~/.unison/default.prf
.It Sy Synchronize a local and a remote directory
.Pp
.Dl unison local/dir ssh://user@host//absolute/path
.Pp
This command synchronizes a local directory (here specified by a relative path)
and a remote directory (here specified by an absolute path) using
.Xr ssh 1
and the default options (see example above).
.It Sy Synchronize with all options specified in a profile
.Pp
.Dl unison profilename
.Pp
This command reads all the options from the profile named
.Dq profilename
and synchronizes according to those options.
.It Sy Synchronize with options specified in a profile and roots on command line
.Pp
.Dl unison profilename /path/to/dir ssh://host/path/on/server
.Pp
This command reads all options from the profile named
.Dq 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.
.It Sy Synchronize automatically
.Pp
.Dl unison -batch /path/to/dir ssh://host/path/on/server
.Pp
This command synchronizes all non-conflicting changes automatically, once.
.It Sy Synchronize continuously
.Pp
.Dl unison -repeat watch /path/to/dir ssh://host/path/on/server
.Pp
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
.No ( Ns Sy "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:
.Pp
.Dl unison -repeat 60 /path/to/dir ssh://host/path/on/server
.Pp
This command synchronizes every 60 seconds. Using
.Fl repeat
implies
.Fl batch .
.Pp
Currently, continuous synchronization is not possible when using the GUI.
.El
.Sh 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:
.Bl -tag -width 1m
.It 0
successful synchronization; everything is up-to-date now.
.It 1
some files were skipped, but all file transfers were successful.
.It 2
non-fatal failures occurred during file transfer.
.It 3
a fatal error occurred, or the execution was interrupted.
.El
.Pp
The graphical interface does not return any useful information through the exit
status.
.Sh COMPATIBILITY
If you are using Unison versions \*(>= 2.52 on all machines, you do not have to
do anything extra for compatibility.
.Pp
Historically (versions \*(Lt 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.
.Pp
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.
.Pp
For more information on co-existence of versions \*(Lt 2.52 and \*(>= 2.52, see
.Lk https://github.com/bcpierce00/unison/wiki/2.52-Migration-Guide
.Sh 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
.Pa /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
.Sy unison -doc all
(you probably want to pipe the output to a pager).
.Pp
.Lk https://github.com/bcpierce00/unison
.Pp
.Lk https://www.cis.upenn.edu/~bcpierce/unison/
.\" .Sh STANDARDS
.\" .Sh HISTORY
.\" .Sh BUGS