UNISON-2.53-GTK(1)

📦
version 2.53.8 · 3 versions
, in ubuntu resolute, ubuntu stonking

💖 NAME 💖

okay so bestie, this is the UNISON-2.53(1) manual page, and the name is unison — a multi-platform bi-directional file synchronization tool. 💅✨

✨ SYNOPSIS ✨

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

🌸 DESCRIPTION 🌸

okay so Unison is literally a file-synchronization tool for POSIX-compliant systems (e.g. *BSD and GNU/Linux, macOS) and Windows. it lets two replicas of a collection of files and directories 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. no cap. 💖

Unison has been in use for over 20 years and many people use it to synchronize data they care about. iconic behavior fr fr. 👑

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. 📝

  • addversionno — flip this to true and Unison stops calling the remote server command just unison and instead calls unison-currentmajorversionnumber, like unison-2.51. notice bestie: the minor version number gets dropped, okay? The point is you can park a whole lil collection of different Unison binaries on one server and they all just coexist, no drama ✨. Whatever version the client is running, that exact same version gets picked on the server. slay.
  • atomic xxx — this one names paths for directories whose contents get treated as a group instead of one-by-one when they're both modified. The backups get made atomically in this case too 🫶. BUT heads up: the backupcurr option has no effect on atomic directories. so don't count on it there.
  • auto — set it to true and the user interface 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 just skips over all the non-conflicting entries and goes straight to the next conflict 💅. no busywork, we love that.
  • backup xxx — include the preference -backup pathspec and Unison keeps backup files for every path that matches pathspec. note that directories are not backed up — and neither are their permissions or any other metadata, mmkay? These backup files live in the directory named by the backuplocation preference. They're named according to backupprefix and backupsuffix, and how many versions stick around is decided by maxbackups. The syntax of pathspec is described in Section “Path Specification” in the manual 📖.
  • backupcurr xxx — include -backupcurr pathspec and Unison keeps a backup of the current version of every file matching pathspec. This file gets saved as a backup with version number 000. These backups can be used as inputs to external merging programs, for instance. See the documentation for the merge preference, and for more details check Section “Merging Conflicting Versions” in the manual. The syntax of pathspec is described in Section “Path Specification” in the manual ✨.
  • backupcurrnot xxx — exceptions to backupcurr, exactly like the ignorenot preference does its thing. the "not" girlies stay winning.
  • backupdir xxx — set this and 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 💖. It's checked after the UNISONBACKUPDIR environment variable, so that env var has dibs.
  • backuploc xxx — this one decides whether backups stay locally, right next to the original files, or go into a central directory named by the backupdir preference. Set it to local and backups are kept in the same directory as the originals. Set it to central and backupdir is used instead 🎀.
  • backupnot xxx — the values here are paths, or individual files, or regular expressions that should not be backed up, even if the backup preference would've selected them. basically it selectively overrides backup. like an ignore list but for backups, iykyk 🦋.
  • backupprefix xxx — when a backup for a file NAME gets created, it's stored in the directory specified by backuplocation, in a file called backupprefixNAMEbackupsuffix. Wild, right? 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... 🌈).

This keyword is ignored if it appears in a directory name in the prefix. 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, bestie: 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 pick values for these preferences that are sufficiently different from the names of your real files 😭. do not name your backup prefix the same as your actual folder, i'm begging.
  • backupsuffix xxx — see backupprefix for the full documentation. that's it, that's the whole bullet 💀.
  • backups — (Deprecated) setting this flag to true is the same as setting backuplocation to local and backup to Name *. old faithful but like, retired.
  • batch — set this to true and the user interface asks you no questions at all. Non-conflicting changes get propagated; conflicts get skipped. it's giving "i trust the process, no notes" 👑.
  • clientHostName xxx — when you specify this, the host name of the client will not be guessed — the host name you provided gets used to find the archive. no guessing games 🧚.
  • color xxx — true enables color output in the text mode user interface 💅✨. false disables all color output entirely. The default is to enable color if the NO_COLOR environment variable is not set. (so if you've got NO_COLOR set, you asked for the monochrome life, and you shall receive it.)
  • confirmbigdel — when true, Unison requests an extra confirmation if it looks like the entire replica has been deleted, before propagating the change 😭. If the batch flag is also set, synchronization will be aborted instead. 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. this one is your seatbelt, keep it on 🫶.
  • confirmmerge — setting this preference makes both the text and graphical interfaces ask you whether the results of a merge command may be committed to the replica or not. Since the merge command works on temporary files, you can then cancel all the effects of applying the merge if it turns out the result is not satisfactory. In batch-mode, this preference has no effect. Default is false. so like, a lil "u sure bestie?" before anything gets locked in 💖.
  • contactquietly — if this flag is set, Unison skips displaying the `Contacting server' message (which some users find annoying) during startup 🙈. valid, honestly.
  • copymax n — (Deprecated) a number saying 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 makes it possible to automatically resolve conflicts in a fairly safe way when synchronizing continuously, in combination with the -repeat watch and -prefer newer preferences. iconic combo, no cap.
  • 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 to be used to continue the transfer of a large file that's already been partially transferred. Typically copyprogrest will just be copyprog with one extra option (e.g., --partial, for rsync). The default setting invokes rsync with appropriate options — most users should not need to change it 🦋.
  • copythreshold n — (Deprecated) a number indicating above what filesize (in kilobytes) Unison should use the external copying utility specified by copyprog. Specifying 0 will cause all copies to use the external program; a negative number will prevent any files from using it. The default is -1. See Section “Making Unison Faster on Large Files” in the manual for more information ⭐.
  • debug xxx — this preference 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 causes info from all modules to be printed — this mode of usage is the first one to try if you're trying to understand something Unison seems to be doing wrong. And -debug verbose turns on some additional debugging output from some modules (e.g., it'll show exactly what bytes are being sent across the network). it's giving detective mode 🔎, obsessed.
  • 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 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 📚. reading the manual? we love a main character who reads the manual, periodt.
  • dontchmod — by default, Unison uses the chmod system call to set the permission bits of files after it has copied them. But in some circumstances (and under some operating systems), the chmod call always fails 😭. Setting this preference completely prevents Unison from ever calling chmod. if chmod is being a hater on your OS, this is the fix.
  • dumbtty — set this to true and the text-mode UI stops trying to mess with your terminal settings, periodt. Normally Unison flips your terminal into raw mode so it can do cute stuff like overwriting the current line, but sometimes that's just not the vibe — like when you're running Unison in a shell inside Emacs, bestie. 😭 With dumbtty on, every command you type to the UI needs a carriage return after it before Unison will actually do the thing. (With it off, Unison catches your keystrokes the instant they happen, no enter needed, slay.) Heads up: this preference does literally nothing to the graphical user interface. 💅
  • dumparchives — turn this on and Unison creates a file called unison.dump on each host, stuffed with a text summary of the archive, right after loading it. ✨
  • fastcheck xxx — when this is set to true, Unison uses a file's modification time and length as a pseudo inode number while scanning replicas for updates, instead of reading the whole entire contents of every single file. (Not applicable to the very first run, though — Unison always scans everything that first time no matter what this switch says.) 🫶 On Windows this can make Unison miss propagating an update if the modification time and length of the file are both unchanged by that update. BUT — and this is the important 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 genuinely reasonable to use this switch on Windows most of the time and every once in a while run Unison once with fastcheck set to false, if you're worried it overlooked something. 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 very 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 there's a conflict at all. 💀 And if later one of those files gets changed, the changed file gets propagated, overwriting the other one. On top of that, 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, fr fr. That said, it can be super useful for power users with huge replicas that are known to already be synchronized (like when one replica is a newly created duplicate of the other, or when they've been synced with Unison before but Unison's archives need rebuilding). In those situations it's recommended to set this flag only for the initial run, so new archives can be created quickly, and then turn it off for normal use. 👑
  • fat — set this to true and Unison uses appropriate options to synchronize efficiently and without error a replica living on a FAT filesystem on a non-Windows machine. Here's the whole lineup, no gatekeeping:
    • do not synchronize permissions (perms = 0)
    • never use chmod (dontchmod = true)
    • treat filenames as case insensitive (ignorecase = true)
    • do not attempt to synchronize symbolic links (links = false)
    • ignore inode number changes when detecting updates (ignoreinodenumbers = true)

Any of these 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 this position in the replica. 🦋 See Section “Symbolic Links” in the manual for more details. The syntax of pathspec is described in Section “Path Specification” in the manual.
  • force xxx — including the preference -force root makes Unison resolve all differences (even non-conflicting changes) in favor of root. This effectively changes Unison from a synchronizer into a mirroring utility. 😳 You can also specify a unique prefix or suffix of the path of one of the roots, or a unique prefix of the hostname of a remote root. You can also specify -force newer (or -force older) to force Unison to choose the file with the later (earlier) modtime — in which case the -times preference must also be enabled. If the modtimes are equal in both replicas when using newer or older, then this preference has no effect (changes get 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 which case the -times preference must also be enabled. If the modtimes are equal in both replicas when using newer or older, then this preference has no effect (changes get 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 — set this flag to true and 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) set this flag to true and Unison's network communication is forced to be half duplex (meaning 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 — drop this preference into 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 (plus all their children, obviously). This is super useful for avoiding synchronizing temporary files, object files, etc. The syntax of pathspec is described in Section “Path Specification” in the manual, and further details on ignoring paths live in Section “Ignoring Paths” in the manual. ✨
  • ignorearchives — set this preference and Unison ignores any existing archive files and behaves as though it were being run for the very first time on these replicas. ⚠️ Not a good idea to set this one in a profile: it's intended for command-line use.
  • ignorecase xxx — set to true and 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 it to false and 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 and this preference makes Unison not take advantage of inode numbers during fast update detection. ⚠️ Use this switch with care, because it's less safe than the standard update detection method — but it can be useful with filesystems that don't support inode numbers.
  • ignorelocks — set this preference and Unison ignores any lock files left over from a previous run of Unison that got interrupted while reading or writing archive files; by default, when Unison sees those lock files it stops and requests 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's probably not a good idea to set this option in a profile: it's intended for command-line use.
  • ignorenot xxx — bestie, this one is the override to ignore. It hands you a list of patterns (same format as ignore) for paths that should definitely not be ignored, whether or not they happen to match one of the ignore patterns. But here's the tea: the semantics of ignore and ignorenot are a lil counter-intuitive, ngl. When Unison is detecting updates, it walks paths in depth-first order, starting from the roots of the replicas and working downwards. Before it even looks at each path, it checks whether that path matches ignore and does not match ignorenot — and if so, it skips that path and all its descendants. Which means: if some parent of a given path matches an ignore pattern, it's getting skipped even if the path itself matches an ignorenot pattern. In particular, putting ignore = Path * in your profile and then using ignorenot to pick out particular paths to sync will not work. 😭 Instead, use the path preference to choose particular paths to synchronize. periodt.
  • 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 change. When scanning for updates, Unison does not check whether these files have been modified; this can speed update detection up significantly ✨ (in particular, for mail directories). iconic efficiency behavior.
  • immutablenot xxx — this preference overrides immutable.
  • include xxx — include preferences from a profile. include name reads the profile “name” (or file “name” in the .unison directory if profile “name” does not exist) and includes its contents as if it was part of a profile or given directly on command line. modular queen behavior.
  • key xxx — used in a profile to define a numeric key (0-9) that you can use in the user interface to switch immediately to this profile. fast switch, iykyk.
  • 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.) 🎀
  • 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. heads up!
  • 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 you to specify a different listening address and can be repeated to listen on multiple addresses. Listening address can be specified as a host name or an IP address. 🌐
  • log — when this flag is set, Unison will log all changes to the filesystems on a file.
  • logfile xxx — by default, logging messages will be appended to the file unison.log in your .unison directory. Set this preference if you prefer another file. It can be a path relative to your .unison directory. Sending SIGUSR1 will close the logfile; the logfile will be re-opened (and created, if needed) automatically, to allow for log rotation. 🔄
  • maxbackups n — this preference specifies the number of backup versions that will be kept by unison, for each path that matches the predicate backup. The default is 2.
  • maxerrors n — this preference controls after how many errors Unison aborts a directory transfer. Setting it to a large number allows Unison to transfer most of a directory even when some files fail to be copied. The default is 1. If the preference is set too high, Unison may take a long time to abort in case of repeated failures (for instance, when the disk is full). choose wisely bestie.
  • 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. ✨ concurrency slay ✨
  • 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 it 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. 🧪
  • nocreation xxx — including the preference -nocreation root prevents Unison from performing any file creation on root root. You can also specify a unique prefix or suffix of the path of one of the roots or a unique prefix of the hostname of a remote root. This preference can be included twice, once for each root, if you want to prevent any creation. 🚫
  • nocreationpartial xxx — including the preference nocreationpartial = PATHSPEC -> root prevents Unison from performing any file creation in PATHSPEC on root root (see Section “Path Specification” in the manual for more information). It is recommended to use BelowPath patterns when selecting a directory and all its contents.
  • nodeletion xxx — including the preference -nodeletion root prevents Unison from performing any file deletion on root root. You can also specify a unique prefix or suffix of the path of one of the roots or a unique prefix of the hostname of a remote root. This preference can be included twice, once for each root, if you want to prevent any deletion. 🙈
  • nodeletionpartial xxx — including the preference nodeletionpartial = PATHSPEC -> root prevents Unison from performing any file deletion in PATHSPEC on root root (see Section “Path Specification” in the manual for more information). It is recommended to use BelowPath patterns when selecting a directory and all its contents.
  • noupdate xxx — including the preference -noupdate root prevents Unison from performing any file update or deletion on root root. You can also specify a unique prefix or suffix of the path of one of the roots or a unique prefix of the hostname of a remote root. This preference can be included twice, once for each root, if you want to prevent any update. 🔒
  • noupdatepartial xxx — including the preference noupdatepartial = PATHSPEC -> root prevents Unison from performing any file update or deletion in PATHSPEC on root root (see Section “Path Specification” in the manual for more information). It is recommended to use BelowPath patterns when selecting a directory and all its contents.
  • numericids — when this flag is set to true, groups and users are synchronized numerically, rather than by name. The special uid 0 and the special group 0 are never mapped via user/group names even if this preference is not set. 🔢
  • owner — when this flag is set to true, the owner attributes of the files are synchronized. Whether the owner names or the owner identifiers are synchronized depends on the preference numericids. 👑
  • 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. no regex magic here, fr fr.
  • perms n — okay so this one is a whole integer that works as a mask, telling Unison which permission bits it's allowed to sync. Default vibe is 0o1777 — meaning literally every bit gets synced except set-uid and set-gid. (And bestie, that exception is on purpose: syncing those two bits is a genuine security hazard, no cap. 🚨) Wanna sync absolutely all the bits anyway? Set this preference to -1. If one of your replicas lives on a FAT [Windows] filesystem, you should lowkey consider using the fat preference instead of this one. And if you need Unison to not set permissions at all, set this to 0 and set the dontchmod preference to true. 💅
  • prefer xxx — including -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 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. Heads up: this preference gets overridden by the preferpartial preference. And babe, this one should be used only if you are sure you know what you are doing! ⚠️
  • preferpartial xxx — including 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 more info). (Again, the syntax of root is the same as for the root preference, plus the special values newer and older.) You can also specify a unique prefix or suffix of the path of one of the roots, or a unique prefix of the hostname of a remote root. Also only if you're sure you know what you're doing! 🙈
  • repeat xxx — setting this makes the text-mode interface synchronize over and over instead of doing it once and stopping. If the argument is a number, Unison pauses for that many seconds before beginning again. When the argument is watch, Unison relies on an external file monitoring process to sync whenever a change happens. You can combine the two with a + character to use file monitoring and also do a full scan every specified number of seconds. For example, watch+3600 will react to changes immediately and additionally do a full scan every hour. ✨
  • retry n — setting this makes the text-mode interface try again to synchronize updated paths where synchronization fails. Each such path will be tried N times. 🔁
  • root xxx — every use of this preference names the root of one of the replicas for Unison to synchronize. Exactly two roots are needed, so the normal modes of usage are either giving two values for root in the profile, or giving none in the profile and providing two on the command line. The deets on root syntax live in Section “Roots” in the manual. The two roots can be given in either order — Unison will sort them into a canonical order before doing anything else. It also tries to canonize the machine names and paths that appear in the roots, so that if Unison is invoked later with a slightly different name for the same root, it'll still be able to locate the correct archives. 🗂️
  • rootalias xxx — when calculating the name of the archive files for a given pair of roots, Unison replaces any roots matching the left-hand side of any rootalias rule by the corresponding right-hand side. 🎀
  • rsrc xxx — set this to true and Unison synchronizes resource forks and HFS meta-data. On filesystems that don't natively support resource forks, this data is stored in Carbon-compatible ._AppleDouble files. Set it to false and Unison won't sync these data. Ordinarily it's set to default, and these data get automatically synchronized if either host is running OSX. In rare circumstances it's useful to set the flag manually. 🍎
  • rsync — Unison uses the 'rsync algorithm' for 'diffs-only' transfer of updates to large files. Setting this flag to false makes Unison use whole-file transfers instead. Under normal circumstances there's no reason to do this, but if you're having trouble with repeated 'rsync failure' errors, setting it to false should permit you to synchronize the offending files. 💀➡️🫶
  • selftest — run internal tests and exit. This option is mostly for developers and must be used carefully: in particular, it will delete the contents of both roots, so that it can install its own files for testing. This flag only makes sense on the command line. When it'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 will be aborted. (If these are not given on the command line, dummy subdirectories in the current directory will be created automatically.) 😭 yes it really deletes everything
  • servercmd xxx — you can use this preference to explicitly set the name of the Unison executable on the remote server (e.g., giving a full path name), if necessary. 🖥️
  • showarchive — when this preference is set, Unison will print out the 'true names' of the roots, in the same form as is expected by the rootalias preference. 👀
  • silent — when set to true, the textual user interface will print nothing at all, except in the case of errors. And setting silent to true automatically sets the batch preference to true. 🤫
  • socket xxx — start unison as a server listening on a TCP socket (with TCP port number as argument) or a local socket (aka Unix domain socket) (with socket path as argument). 🔌
  • sortbysize — when this flag is set, the user interface lists 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 won't prevent smaller files from being transferred quickly. This preference (as well as the other sorting flags, but not the sorting preferences that require patterns as arguments) can be set interactively and temporarily using the 'Sort' menu in the graphical and text user interfaces. 🐜➡️🐘
  • sortfirst xxx — each argument to sortfirst is a pattern pathspec, which describes a set of paths. Files matching any of these patterns will be listed first in the user interface. The syntax of pathspec is described in Section “Path Specification” in the manual. 🥇
  • sortlast xxx — similar to sortfirst, except that files matching one of these patterns will be listed at the very end. 🐌
  • sortnewfirst — when this flag is set, the user interface lists newly created files before all others. This is useful, for example, for checking that newly created files are not 'junk', i.e., ones that should be ignored or deleted rather than synchronized. ✨🆕
  • source xxx — include preferences from a file. source name reads the file “name” in the .unison directory and includes its contents as if it was part of a profile or given directly on command line. 📂
  • sshargs xxx — the string value of this preference 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 — you can use this preference to explicitly set the name of the ssh executable (e.g., giving a full path name), if necessary. 🛰️
  • stream — (Deprecated) when this preference is set, Unison uses an experimental streaming protocol for transferring file contents more efficiently. The default value is true. ⚠️ deprecated, bestie
  • terse — when this preference is set to true, the user interface will not print status messages. 🤐
  • testserver — setting this flag on the command line causes Unison to attempt to connect to the remote server and, if successful, print a message and immediately exit. Useful for debugging installation problems. Should not be set in preference files. 🧪
  • times — when this flag is set to true, file modification times (but not directory modtimes) are propagated. ⏰
  • ui xxx — this preference selects either the graphical or the textual user interface. Legal values are graphic or text. Because this option is processed specially during Unison's start-up sequence, it can only be used on the command line. In preference files it has no effect. If the Unison executable was compiled with only a textual interface, this option has no effect. (The pre-compiled binaries are all compiled with both interfaces available.) 🖼️ vs 📝
  • unicode xxx — when set to true, this flag causes Unison to perform case insensitive file comparisons assuming Unicode encoding. This is the default. When the flag is set to false, Latin 1 encoding is assumed (this means that all bytes that are not letters in Latin 1 encoding will be compared byte-for-byte, even if they may be valid characters in some other encoding). When Unison runs in case sensitive mode, this flag only makes a difference if one host is running Mac OS X. Under Mac OS X, it selects whether comparing the filenames up to decomposition, or byte-for-byte. 🌍
  • version — print the current version number and exit. (This option only makes sense on the command line.) 📌
  • watch — Unison uses a file watcher process, when available, to detect filesystem changes; this is used to speed up update detection. Setting this flag to false disables the use of this process. 👁️
  • -xattrignore namespec — bestie, this one tells Unison to straight-up ignore extended attributes whose names match namespec. Why would you want that? Because some xattrs would ✨fail✨ to sync — no permissions, or the replicas just have technical differences, and honestly? not the vibe. The syntax of namespec is exactly the same as path specification (that's the Section “Path Specification” in the manual, iykyk). Pro tip: prefer the Path and Regex forms over the Name form. Also!! 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)[.].*), and attributes used to store POSIX ACL are also ignored by default (achieved by the pattern Path !system.posix_acl_*). Wanna sync attributes in one or both of those namespaces? Go see the xattrignorenot preference 💅. 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. periodt.
  • -xattrignorenot xxx — the glow-up that overrides xattrignore 🫶. It hands you a list of patterns (same format as xattrignore, no cap) 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 you actually want? Iconic move: ignore everything (like, 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 those namespaces, you may add an xattrignorenot pattern like Path !security.* to sync all attributes in the security namespace, or Path !security.selinux to sync one specific attribute in an otherwise ignored namespace. And a pattern like Path !system.posix_acl_* can be used to sync POSIX ACLs on Linux ✨. Note that the namespace name must be prefixed with a "!" (applies on Linux only). All names not prefixed with a "!" are taken as strictly belonging to the user namespace, and therefore the "!user." prefix is never used.
  • -xattrs — when this flag is set to true, the extended attributes of files and directories get synchronized 🔥. But heads up: system extended attributes are not synchronized. That's just how it is, bestie.
  • -xferbycopying — when this preference is set, Unison tries to avoid transferring file contents across the network by recognizing when a file with the required contents already exists in the target replica 👑. The result? File moves usually get propagated very quickly. The default value is true. slay.

🌈 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. So basically it's the "where are we even doing this" of it all.

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. No matter where you launch it from, that path hits the same place 💅.

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 socket mode, iykyk), then this 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 this syntax

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

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

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

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

protocol ::= file
          |  socket
          |  ssh

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

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

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

port ::= [0-9]+

When path is given without any protocol prefix, the protocol is assumed to be file:. Under Windows, it is possible to synchronize with a remote directory using the file: protocol over the Windows Network Neighborhood. For example,

unison foo //host/drive/bar

synchronizes the local directory foo with the directory drive:\bar on the machine host, provided that host is accessible via Network Neighborhood. When the file: protocol is used this way, there is no need for a Unison server to be running on the remote host ✨. BUT — and this is the catch bestie — 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 😭. So like. gigabit ethernet? yes. coffee shop wifi? absolutely not.

🦋 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 /.

Note that the path separator character is always a forward slash, no matter what operating system Unison is running on. periodt.

The empty path (i.e., the empty sequence of names) denotes the whole replica 🌈.

💖 PATH SPECIFICATION 💖

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

Each pattern can have one of three forms. The most general form is a Posix extended regular expression introduced by the keyword Regex. (The collating sequences and character classes of full Posix regexps are not currently supported — so don't come for me about those.)

Regex regexp

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

Name name

matches any path in which the last component matches name,

Path path

matches exactly the path path, and

BelowPath path

matches the path path and any path below.

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

  • a * matches any sequence of characters not including / (and not beginning with ., when used at the beginning of a name)
  • a ? matches any single character except / (and leading .)
  • [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 ✨.

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. So to allow a path specification to contain the separator string, append an associated string to it — even if it's not used. The associated string cannot contain the separator string. iykyk.

🎀 PROFILES 🎀

A profile is a text file that specifies permanent settings for roots, paths, ignore patterns, and other preferences — so you don't have to type them at the command line every single time Unison is run 🙈. Profiles should reside in the .unison directory on the client machine.

If Unison is started with just one argument name on the command line, it looks for a profile called name.prf in the .unison directory. If it is started with no arguments, it scans the .unison directory for files whose names end in .prf and offers a menu (when using the graphical user interface; for the text interface, you have to use the -i option). And 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. No cap.

💅 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 😭. So like, only if you have to, bestie.

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 so Unison keeps a whole lil private directory of info on each host, right? 💖 And if the environment variable UNISON is defined, its value gets used as the path for that directory — could just be a name, could be a full path, whatever you vibe with.

If UNISON is not defined, then the directory depends on which OS you're on:

  • On Unix, the default is $HOME/.unison.
  • On Windows, if the environment variable USERPROFILE is defined, the directory is $USERPROFILE\.unison; otherwise, it's c:\.unison.
  • On macOS, $HOME/.unison gets used if it's already there, but $HOME/Library/Application Support/Unison will be created and used by default. 🍓
  • UNISONLOCALHOSTNAME — so the function that finds the canonical hostname of the local host (you know, the one used to calculate the name of the archive file that remembers which files have been synchronized 👀) normally uses the gethostname operating system call. BUT if this env var is set, its value gets used instead. Why do we care? Because it makes Unison way easier to live with in situations where a machine's name changes all the time (e.g., because it's a laptop and gets moved around a lot 🧳). Iconic, honestly.
  • UNISONBACKUPDIR — when backups are stored centrally, the directory holding them is controlled by the preference backupdir and by this environment variable. If both are specified, the environment variable overrides the preference. If neither is set, then $UNISON/backup is used (peep the UNISON environment variable above for what $UNISON means 💅).
  • PAGER — used by the text interface as the pager when it's displaying the differences between changed files.
  • NO_COLOR — if this is set, Unison's text interface will not produce any color output by default. The color preference overrides this environment variable, so like… it can still be cute if you insist. 🌈

🎀 FILES 🎀

  • ~/.unison — Unison stores a variety of information in a private directory on each host, and this is the default path of that private directory. This path may be changed by the UNISON environment variable.
  • ~/.unison/*.prf — profile files, bestie! 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 can be safely deleted, no stress 🫶. But keep in mind that deleting a fingerprint cache file means any unsynchronized changes must be scanned again. Depending on your replicas, that may mean scanning gigabytes of file contents. 💀
  • ~/.unison/lk* — lock files indicating a running Unison process. These may be deleted if you are careful and you know there's no Unison process currently running. Deleting a lock file is equivalent to using the -ignorelocks option.
ngl, those archive and lock files are giving "do not touch unless you're the main character" energy. Read the caveats. Twice. ✨

✨ EXAMPLES ✨

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 the command line will not override roots in the profile — rather, they 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 💀

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

  1. 0 — successful synchronization; everything is up-to-date now. 🎉
  2. 1 — some files were skipped, but all file transfers were successful.
  3. 2 — non-fatal failures occurred during file transfer.
  4. 3 — a fatal error occurred, or the execution was interrupted.
The graphical interface does not return any useful information through the exit status. She's mysterious like that. 🙈

🌈 COMPATIBILITY 🌈

If you're running Unison versions ≥ 2.52 on all machines, you do not have to do anything extra for compatibility. Slay.

Historically (versions < 2.52), Unison versions had to be matched relatively exactly for them to work together. On top of that, the version of compiler used to build Unison also had significant relevance for compatibility. It was a whole thing. 😭

As of version 2.52, Unison has a degree of backward and forward compatibility. This means three things:

  1. It is possible for local and remote machines to run a different version of Unison.
  2. It is possible for local and remote machines to run a version (same or different) of Unison built with a different version of compiler.
  3. Lastly, it is possible to upgrade Unison on the local machine and keep the existing archive. 👑

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

🦋 SEE ALSO 🦋

There's 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. You can also read the manual in the GUI (look in the Help menu), or on the command line with unison -doc all — and bestie, you probably want to pipe that output to a pager. 😅

https://github.com/bcpierce00/unison

and that's the whole page, bestie!! 🫶 this was unison, from the UNISON(1) manual, dated March 17, 2022. go forth and synchronize responsibly. periodt. 💅✨

📦 where this page comes from