UNISON(1)

📦
version 2.54.0 · 2 versions
, in alpine 3.24, arch rolling, epel 10, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 UNISON(1) 💖

okay bestie, you've landed on the unison page from the LOCAL manual section, and honestly? you're about to have a great time. grab a snack 🍓

✨ NAME ✨

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

🌸 SYNOPSIS 🌸

unison [options]
unison root1 root2 [options]
unison profilename [options]

🦋 DESCRIPTION 🦋

So unison is a file-synchronization tool, and it runs on POSIX-compliant systems (think *BSD and GNU/Linux, macOS) and also Windows. What it does is take two replicas of a collection of files and directories — stored on different hosts, or on different disks on the same host, whatever — and lets you modify each one separately, and then it brings both of them up to date by propagating the changes in each replica over to the other. it's giving mutual glow-up, fr fr 💅

Unison has been in use for over 25 years and many people use it to synchronize data they care about. like, a quarter century of holding people's precious files together — that's not a phase, that's a legacy 👑

Unison shares a number of features with other tools. Some of the distinguishing features are:

  • Unlike simple mirroring or backup utilities, Unison can deal with updates to both replicas of a distributed directory structure.
  • Unison works across platforms, allowing you to synchronize a Windows laptop with a Unix server, for example.
  • Unlike most distributed filesystems, Unison is a user-level program that simply uses normal systems calls: there is no need to modify the kernel, to have superuser privileges on either host, or to have a FUSE implementation.
  • Unison works between any pair of machines connected to the internet, typically communicating over ssh(1), but also directly over TCP. It is careful with network bandwidth, and runs well over slow links. Transfers of small updates to large files are optimized using a compression protocol similar to rsync(1).
  • Unison is resilient to failure. It is careful to leave the replicas and its own private structures in a sensible state at all times, even in case of abnormal termination or communication failures.

🌈 OPTION SUMMARY 🌈

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
  • -moves-experimental — optimize transfers by detecting renames and moves
  • -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 profile. 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.

okay bestie we're still deep in the option list and it is long — hydrate, stretch, we got this 💖

  • addversionno — set this to true and Unison stops being basic and uses unison-currentmajorversionnumber as the remote server command instead of just plain unison (and yes, the minor version number gets dropped — so like unison-2.51). The ✨point✨ is that you can have a bunch of different unison binaries for different versions all chilling on the same server, and whichever version the client is running, that same version gets picked on the server. no cap, it just works.
  • atomic xxx — this one specifies paths for directories whose contents get treated as a group instead of individually when both sides got modified. Backups also get made atomically in this case. ⚠️ but heads up: the backupcurr option has no effect on atomic directories.
  • auto — when it's true, the UI skips asking you for confirmations on non-conflicting changes. more precisely: when the UI is done setting the propagation direction for one entry and is about to move to the next, it skips over all the non-conflicting entries and goes straight to the next conflict. main character energy tbh, it's not gonna bother you about the easy stuff.
  • backup xxx — include the preference -backup pathspec and Unison keeps backup files for every path that matches pathspec. Note that directories (nor their permissions or any other metadata) do not get backed up. Those backup files live in the directory named by the backuplocation preference, they're named per the backupprefix and backupsuffix preferences, and how many versions get kept is decided by the maxbackups preference. The syntax of pathspec is described in Section "Path Specification" in the manual. 📚
  • backupcurr xxx — include the preference -backupcurr pathspec and Unison keeps a backup of the current version of every file matching pathspec. That file gets saved as a backup with version number 000. these are literally made to be fed into external merging programs, iykyk. see the docs for the merge preference, and for the full tea check Section "Merging Conflicting Versions" in the manual. Syntax of pathspec → Section "Path Specification" in the manual.
  • backupcurrnot xxx — the exceptions to backupcurr, exactly like how the ignorenot preference works. 🎀
  • backupdir xxx — if you set this, Unison uses it as the name of the directory where backup files specified by the backup preference get stored, but only when backuplocation is set to central. Also it gets checked after the UNISONBACKUPDIR environment variable. order matters bestie.
  • backuploc xxx — decides whether backups get kept locally, right next to the original files, or in a central directory specified by the backupdir preference. Set it to local → backups go in the same directory as the original files. Set it to central → backupdir gets used instead. that simple. 💅
  • backupnot xxx — the values here specify paths or individual files or regular expressions that should not be backed up, even if the backup preference selected them — i.e., it selectively overrides backup. it's the "not today" list.
  • backupprefix xxx — when a backup for a file NAME is created, it's stored in the directory specified by backuplocation, in a file called backupprefixNAMEbackupsuffix. So: backupprefix can include a directory name (which makes Unison keep all the backup files for a given directory in a subdirectory with that name), and both backupprefix and backupsuffix can contain the string $VERSION, which gets replaced by the age of the backup (1 for the most recent, 2 for the second most recent, and so on...). That keyword is ignored if it shows up in a directory name in the prefix; and if it doesn't appear anywhere in the prefix or the suffix, it gets 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. fr fr, don't get got by your own backups.
  • 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. that's it, that's the whole vibe.
  • batch — set it to true and the user interface asks no questions at all. Non-conflicting changes get propagated; conflicts get skipped. fully hands-off, no drama. 🦋
  • clientHostName xxx — when you specify this, the host name of the client won't be guessed — the host name you provide is what gets used to find the archive.
  • color xxx — set to true and you get color output in the text mode user interface 🌈. Set to false and all color output is disabled. The default is to enable color if the NO_COLOR environment variable is not set.
  • confirmbigdel — when true, Unison asks for an extra confirmation if it looks like the entire replica has been deleted, before propagating that change. 😭 If the batch flag is also set, synchronization gets aborted. When the path preference is used, the same confirmation gets requested for top-level paths. (At the moment, this flag only affects the text user interface.) See also the mountpoint preference.
  • confirmmerge — setting this makes both the text and graphical interfaces ask you whether the results of a merge command can be committed to the replica or not. Since the merge command works on temporary files, you can then cancel all the effects of applying that merge if it turns out the result isn't satisfactory. 🙈 In batch-mode this preference has no effect. Default is false.
  • contactquietly — if this flag is set, Unison skips displaying the Contacting server message (which some users find annoying) during startup. peace and quiet, periodt. 🤫
  • copymax n — (Deprecated 🚫) a number indicating how many instances of the external copying utility Unison is allowed to run simultaneously (defaults to 1).
  • copyonconflict — when this flag is set, Unison makes 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 is what makes it possible to automatically resolve conflicts in a fairly safe way when you're synchronizing continuously, in combination with the -repeat watch and -prefer newer preferences. the trio of doom, but like, a cute doom. 🔥
  • 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 which should be used to continue the transfer of a large file that's already been partially transferred. Typically copyprogrest is just 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 makes all copies use the external program; a negative number prevents any files from using it. The default is -1.
  • debug xxx — this preference makes Unison print all sorts of info about what it's doing internally, on the standard error stream. You can use it many times, each time with the name of a module you want debugging info for. Possible arguments for debug can be found by looking for calls to Util.debug in the sources (using, e.g., grep). Setting -debug all makes info from all modules print (this is the first mode of usage to try if you're trying to understand something 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). 💀 detective mode activated.
  • diff xxx — this preference controls 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, those get replaced by the names of the files to be diffed. If the value contains the substrings NEWER and OLDER, those get replaced by the names of the files to be diffed, with NEWER being the most recently modified file of the two. Without any of these substrings, the two filenames just get appended to the command. In all cases, the filenames are suitably quoted.
  • doc xxx — the command-line argument -doc secname makes unison 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 get a list of the names of the various sections that can be printed. self-documenting king 👑
  • dontchmod — by default, Unison uses the chmod system call to set the permission bits of files after it's 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 — set this to true and the text mode UI stops trying to touch your terminal settings at all. (Normally Unison throws the terminal into raw mode so it can do cute stuff like overwriting the current line.) Super handy when Unison is running in a shell inside Emacs. When dumbtty is on, every command you send to the UI needs a carriage return after it before Unison actually executes — no instant reactions. (When it's off, Unison recognizes keystrokes the literal second you type them.) 💅 This preference does nothing to the graphical UI, so don't come for it.
  • dumparchives — turn this on and Unison will create a file unison.dump on each host, holding a text summary of the archive, right after it loads it. 📝
  • fastcheck xxx — set to true and Unison uses a file's modification time plus its length as a pseudo inode number when scanning replicas for updates, instead of reading the whole contents of every single file. (This does not apply to the very first run — Unison will always scan all files regardless of this switch.) On Windows this can make Unison miss propagating an update if the modtime and length of a file are both unchanged by that update. BUT — and this is the slay part — Unison will never overwrite such an update with a change from the other replica, because it always does a safe check for updates right before propagating a change. 🛡️ So it's reasonable to use this switch on Windows most of the time and occasionally run Unison once with fastcheck set to false if you're worried Unison 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. 🦋
  • fastercheckUNSAFE — THIS FEATURE IS STILL EXPERIMENTAL AND SHOULD BE USED WITH EXTREME CAUTION. 💀 When this flag is set to true, Unison computes 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 up update detection, but it must be used with care, because it can cause Unison to miss conflicts: if a given path in the filesystem has files on both sides that Unison hasn't seen yet, and those files have the same length but different contents, then Unison will not notice the conflict exists. If one of the files is changed later, the changed file gets propagated, overwriting the other. 😭 And 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 treats this conservatively as a potential change (since it has no record of the earlier contents) and shows 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've previously been synchronized with Unison but Unison's archives need to be rebuilt). In those situations, the recommendation is to set this flag only for the initial run of Unison so new archives can be created quickly, then turn it off for normal use. ✨
  • fat — when this is set to true, Unison uses appropriate options to synchronize efficiently and without error a replica sitting on a FAT filesystem on a non-Windows machine: don't synchronize permissions (perms = 0); never use chmod (dontchmod = true); treat filenames as case insensitive (ignorecase = true); don't attempt to synchronize symbolic links (links = false); ignore inode number changes when detecting updates (ignoreinodenumbers = true). 🍓 Any of these can be overridden by explicitly setting the corresponding preference in the profile.
  • follow xxx — including the preference -follow pathspec makes Unison treat symbolic links matching pathspec as invisible and behave as if the object the link points to had appeared literally at that 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 makes Unison resolve all differences (including 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 has 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 makes Unison 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 info). 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 has 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 get synchronized. 👯 Whether the group names or the group identifiers get synchronized depends on the numerids preference.
  • 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're experiencing 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 the 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 makes Unison completely ignore paths that match pathspec (along with their children). Perfect for avoiding syncing temp files, object files, etc. 🙈 The syntax of pathspec is described in Section “Path Specification” in the manual, and further details on ignoring paths live in Section “Ignoring Paths” in the manual.
  • ignorearchives — when this preference is set, Unison ignores any existing archive files and behaves 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 — set to true, this flag makes Unison 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. Set to false, Unison treats 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 — set to true, this preference makes Unison not take advantage of inode numbers during fast update detection. Use this switch with care, as it's less safe than the standard update detection method, but it can be useful with filesystems that don't support inode numbers. 🧚
  • ignorelocks — when this preference is set, Unison ignores any lock files that may have been left over from a previous run of Unison that got 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 just crashed, or you just killed it). It is probably not a good idea to set this option in a profile: it is intended for command-line use.

okay bestie, we are deep in the OPTIONS list now, hydrate 💧, we're not even halfway ✨

  • ignorenot xxx — this one overrides the ignore preference, periodt. It hands you a list of patterns (same format as ignore, no cap) for paths that should definitely not be ignored, whether or not they happen to match one of the ignore patterns. ⚠️ now here's the part that's lowkey 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 that case it skips this path and all its descendants. Which means: if some parent of a given path matches an ignore pattern, then it'll be skipped even if the path itself matches an ignorenot pattern. 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 path preference to choose particular paths to synchronize. iykyk.
  • 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. That's it, that's the whole vibe.
  • 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. main character shortcut energy 👑
  • 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's 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.) it's giving ✨organization✨
  • 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. receipts, bestie 🧾
  • 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 check, at the end of update detection, that PATH exists within each root, and abort if not. This can avoid synchronzing when removable media is not mounted. This preference can be given more than once. See Section “Mount Points and Removable Media” in the manual. 🦋
  • moves-experimental — when this preference is set, Unison will try to avoid transferring file contents across the network, or making a local copy, by recognizing when a file or a directory has been renamed or moved to a new location. This usually allows to propagate only the rename, without transferring or copying any data. The default value is false. ⚠️ this feature is currently experimental and may change in incompatible ways in future versions — iconic behavior but don't get too attached 😭.
  • 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. 💀 no deleting, we don't do that here
  • 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. 🧊 frozen, locked, no notes
  • 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. fr fr, no regex magic here 🌈

bestie we still have more options to go, keep scrolling, you're doing amazing 💖

  • perms n — bestie, this one's an integer that works like a mask ✨ telling Unison which permission bits get synced. Default is 0o1777: literally every bit except the set-uid and set-gid bits, because syncing those two is a genuine security hazard 💀. Wanna sync every single bit anyway? Set it to -1. If one of your replicas lives on a FAT [Windows] filesystem, lowkey you should be looking at the fat preference instead of this one. And if you need Unison to not set permissions at all, set this to 0 and flip dontchmod to true. periodt. 💅
  • prefer xxx — including the preference -prefer root makes Unison always resolve conflicts in favor of root instead of asking you for guidance, except for paths marked by the merge preference. (The syntax of root is the same as for the root preference, plus the special values newer and older.) You can also drop in a unique prefix or suffix of the path of one of the roots, or a unique prefix of the hostname of a remote root. Heads up: this gets overridden by preferpartial. 🫶 And fr fr — only use this if you are sure you know what you're doing!
  • preferpartial xxx — including the preference preferpartial = PATHSPEC -> root makes Unison always resolve conflicts in favor of root instead of asking you, but only for the files in PATHSPEC (peep Section “Path Specification” in the manual for the deets). (The syntax of root is the same as for the root preference, plus the special values newer and older.) You can also give a unique prefix or suffix of the path of one of the roots, or a unique prefix of the hostname of a remote root. Same energy as above: only use this if you are sure you know what you're doing! 🙈
  • repeat xxx — setting this makes the text-mode interface sync over and over instead of doing it once and calling it a day 🔁. If the argument is a number, Unison pauses that many seconds before going again. If the argument is watch, Unison leans on an external file monitoring process and syncs whenever a change happens. You can combine both with a + character to get file monitoring and a full scan every however-many seconds. For example, watch+3600 reacts to changes immediately and also does a full scan every hour. iconic.
  • retry n — this makes the text-mode interface try again to sync updated paths where synchronization failed. Each such path gets tried N times. 🎀
  • root xxx — every time you use this preference you're naming the root of one of the replicas Unison should sync. You need exactly two roots, so the normal ways to play are either giving two values for root in the profile, or giving none in the profile and providing two on the command line. The syntax deets live in Section “Roots” in the manual 📖. The two roots can come in either order — Unison sorts them into a canonical order before doing literally anything else. It also tries to canonize the machine names and paths in the roots, so if you invoke Unison later with a slightly different name for the same root, it can still locate the correct archives. 💖
  • rootalias xxx — when it's working out the names of the archive files for a given pair of roots, Unison swaps any roots matching the left-hand side of any rootalias rule for the corresponding right-hand side.
  • rsrc xxx — set to true, this flag makes Unison sync resource forks and HFS meta-data. On filesystems that don't natively support resource forks, that data gets stored in Carbon-compatible ._AppleDouble files. Set it to false and Unison won't sync this data at all. Normally the flag sits at default, and the data is automatically synchronized if either host is running OSX. In rare circumstances it's actually useful to set the flag by hand. 🦋
  • rsync — Unison uses the 'rsync algorithm' for 'diffs-only' transfer of updates to large files. Setting this flag to false makes Unison do whole-file transfers instead. Under normal circumstances there's zero reason to do this, but if you're getting hit with repeated 'rsync failure' errors, setting it to false should let you synchronize the offending files. 😭
  • selftest — runs internal tests and exits. This one's mostly for developers and it must be used carefully: in particular, it will delete the contents of both roots so it can install its own files for testing 💀. This flag only makes sense on the command line. When it's provided, no preference file is read: all preferences must be specified on the command 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 get aborted. (If these aren't given on the command line, dummy subdirectories in the current directory get created automatically.)
  • servercmd xxx — this preference lets you explicitly set the name of the Unison executable on the remote server (e.g. by giving a full path name), if that's what you need.
  • showarchive — when this is set, Unison prints out the 'true names' of the roots, in the same form as expected by the rootalias preference. 👑
  • silent — set to true, the textual user interface prints nothing at all, except when there are errors. Setting silent to true automatically sets the batch preference to true too. 🤫
  • socket xxx — start unison as a server listening on a TCP socket (with TCP port number as the argument) or a local socket (aka Unix domain socket) (with socket path as the argument).
  • sortbysize — with this flag set, the user interface lists changed files by size (smallest first) instead of by name. Super useful, like, for syncing over slow links, since it puts the very large files at the end of the list where they won't stop smaller files from transferring quickly 🌸. This preference (and the other sorting flags too, but not the sorting preferences that need 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 describing a set of paths. Files matching any of these patterns get listed first in the user interface. The syntax of pathspec is described in Section “Path Specification” in the manual. ✨
  • sortlast xxx — just like sortfirst, except files matching one of these patterns get listed at the very end.
  • sortnewfirst — with this flag set, the user interface lists newly created files before all others. Handy, for example, for checking that newly created files aren't junk — y'know, 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 the command line.
  • sshargs xxx — the string value of this preference gets 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 lets you explicitly set the name of the ssh executable (e.g. by giving a full path name), if necessary.
  • stream — (Deprecated) when this preference is set, Unison uses an experimental streaming protocol for transferring file contents more efficiently. The default value is true. 🧚
  • terse — set to true, the user interface won't print status messages.
  • testserver — setting this flag on the command line makes Unison 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 picks 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 — set to true, this flag makes Unison do case insensitive file comparisons assuming Unicode encoding. That's the default 💜. Set to false, Latin 1 encoding is assumed (which means all bytes that aren't letters in Latin 1 encoding get compared byte-for-byte, even if they might 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 goes 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 — bestie, this is the "pls pretend u never saw these" list 💅 Setting -xattrignore to a namespec makes Unison straight-up ignore extended attributes whose names match it. Why would u do that? Because some xattrs will just fail to sync — no permissions, or the replicas are built different — and honestly, we don't have the energy. The syntax of namespec is exactly the same as for path specification (it's described in Section "Path Specification" in the manual), and pls pls prefer the Path and Regex forms over the Name form 🙏. Important: the pattern gets applied to the name of the extended attribute, not to the path. On Linux, attributes in the security and trusted namespaces are ignored by default (this is achieved by the pattern Regex !(security|trusted)[.].*); also the attributes used to store POSIX ACLs are ignored by default (achieved by the pattern Path !system.posix_acl_*). Wanna sync stuff in one or both of those namespaces anyway? Go see the xattrignorenot preference, she's right below 👇. Note that the namespace name must be prefixed with a "!" (applies on Linux only). And all names not prefixed with a "!" are taken as strictly belonging to the user namespace — which is why the "!user." prefix is never used. iykyk 🧚
  • xattrignorenot xxx — the actually no, keep that one override, she overrides xattrignore 👑. It gives u a list of patterns (same format as xattrignore) for extended attributes that should not be ignored, whether or not they happen to match one of the xattrignore patterns. Wanna sync only the attributes u actually desire? Iconic move: ignore all of them (for example, set xattrignore to Path *) and then add xattrignorenot for the 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, u 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. no cap 🫶
  • xattrs — set this flag to true and boom, the extended attributes of files and directories are synchronized. System extended attributes are not synchronized. periodt 💅
  • 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 is literally just Unison's "girl where do I find ur files" GPS 📍 — it tells Unison where to find a set of files to be synchronized, either on the local machine or on a remote host.

For example,

relative/path/of/root

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

/absolute/path/of/root

specifies a root relative to the top of the local filesystem, independent of where Unison is running. ✨

Remote roots can begin with ssh:// to indicate that the remote server should be started with ssh(1):

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

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

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

is used to specify the hostname and the port that the client Unison should use to contact it. And the 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's possible to synchronize with a remote directory using the file: protocol over the Windows Network Neighborhood. For example,

unison foo //host/drive/bar

synchronizes the local directory foo with the directory drive:\bar on the machine host, provided that host is accessible via Network Neighborhood. When the file: protocol is used in this way, there is no need for a Unison server to be running on the remote host 🎉.

However — and bestie I need u to hear me on this — 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. 💀 That's not a vibe, that's a bandwidth crime.

🛤️ PATHS 🛤️

A path refers to a point within a set of files being synchronized; it's specified relative to the root of the replica. Formally, a path is just a sequence of names, separated by /. And here's the plot twist 👀 — 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. she contains multitudes ✨

🔍 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 patterns. 🎯

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 — sad, I know 😭.)

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 it. The name and path arguments of the latter forms of patterns are not regular expressions. Instead, standard "globbing" conventions can be used in name and path:

  • a * matches any sequence of characters not including / (and not beginning with ., when used at the beginning of a name)
  • a ? matches any single character except / (and leading .)
  • [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 character / — even when the client or server is running under Windows, where the normal separator character is a backslash. This makes it possible to use the same set of path patterns for both Unix and Windows file systems. slay 🌈

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

Path path -> associated string

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

📁 PROFILES 📁

A profile is a text file that specifies permanent settings for roots, paths, ignore patterns, and other preferences, so that they don't need to be typed at the command line every time Unison is run. She's the set it and forget it queen 👑 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 preferences.

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

p = true

for a boolean flag or

p = <value>

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

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

🛑 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 finished, press Ctrl-C (or send signal SIGINT or SIGTERM). This will interrupt 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 terminate the process forcibly (similar to SIGKILL). 😱

Doing so may leave the archives or replicas in an inconsistent state or locked. not the vibe. pls don't.

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 🌿

Okay bestie, this is where Unison spills where it keeps its lil private-dir secrets. Every env var matters, no cap.

  • 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 synchronized) normally uses the gethostname operating system call. However, if the environment variable UNISONLOCALHOSTNAME is set, its value will be used instead. This makes it easier to use Unison in situations where a machine’s name changes frequently (e.g., because it is a laptop and gets moved around a lot).
  • UNISONBACKUPDIR — When backups are stored centrally, the directory used to hold them is controlled by the preference backupdir and the environment variable UNISONBACKUPDIR. If both are specified then the environment variable overrides the preference. If neither of these are set, then the directory $UNISON/backup is used (see environment variable UNISON above).
  • PAGER — Used by the text interface as the pager when displaying the differences 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 🎀

Here’s the file drama, bestie. Know before you delete.

  • ~/.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 equivalent to using the -ignorearchives option.
  • ~/.unison/fp* — Fingerprint cache files. These files may be safely deleted. Keep in mind that deleting a fingerprint cache file means that any 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 🌈

Iconic command moments. Let’s go.

💖 Synchronize two local directories

unison path/to/dir1 /dir2

This command synchronizes two local directories using the default options. Default options are defined by Unison and can be overridden by the 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 relative 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 override 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 dormant, waiting for any file changes within either root and then automatically synchronizes these changes. This also works in a profile (repeat = watch). If the filesystem monitoring helper program is not available or not desired for other reasons, it is possible to make Unison synchronize repeatedly with a defined time interval:

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

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

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

🦋 DIAGNOSTICS 🦋

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

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

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

👑 COMPATIBILITY 👑

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

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

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

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

🌟 SEE ALSO 🌟

More lore, because of course there is. 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

💖 And that’s a wrap, bestie! This page came from the unison manual, page UNISON(1), dated March 17, 2022. Keep your replicas cute and your archives cuter. 💅✨

📦 where this page comes from