UNISON-2.52(1)

📦 version 2.52.1, in debian bookworm

okay bestie, buckle up 💖 this is the manual page for unison, aka UNISON-2.52(1), living in the LOCAL manual section. It's long, it's iconic, and we're doing it in seven parts — this is part one, so grab a snack and let's go. ✨

🦋 NAME 🦋

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

🌸 SYNOPSIS 🌸

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

💅 DESCRIPTION 💅

okay so Unison is a file-synchronization tool for POSIX-compliant systems (think *BSD and GNU/Linux), macOS, and Windows. The whole vibe? You've got two replicas of some collection of files and directories — could be on totally different hosts, could be different disks on the same host — you modify them separately, and then Unison brings them up to date by propagating each replica's changes over to the other. mutual glow-up, no cap. 🫶

Unison has been in use for over 20 years and many people use it to synchronize data they care about. twenty years of service, that's main character energy 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. both sides get a turn, we love equality
  • 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. no root, no kernel surgery, just vibes
  • 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. trauma-informed software 💀

✨ 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:

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

How to sync:

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

How to sync (text interface (CLI) only):

  • -repeat xxx — synchronize repeatedly (text interface only)
  • -retry n — re-try failed synchronizations N times (text ui only)

Text interface (CLI):

  • -color xxx — use color output for text UI (true/false/default)
  • -dumbtty — do not change terminal settings in text UI

Graphical interface (GUI):

  • -height n — height (in lines) of main window in graphical interface

Remote connections:

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

Archive management:

  • -ignorearchives — ignore existing archive files

Other:

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

👑 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. sneaky little dash, we stan

🍓 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. home is wherever the new prefs go 💖

🍓 addversionno

When this flag is set to true, Unison will use unison-currentmajorversionnumber instead of just unison as the remote server command (note that the minor version number is dropped -- e.g., unison-2.51). This allows multiple binaries for different versions of unison to coexist conveniently on the same server: whichever version is run on the client, the same version will be selected on the server. matching outfits on both sides, periodt ✨

🍓 atomic xxx

This preference specifies paths for directories whose contents will be considered as a group rather than individually when they are both modified. The backups are also made atomically in this case. The option backupcurr however has no effect on atomic directories. all-or-nothing, and backupcurr is not invited to this party 🙈

  • auto — set this to true and the user interface will stop pestering 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 will skip over all non-conflicting entries and go directly to the next conflict.) no more clicking through stuff that was never in question 💅
  • backup xxx — including the preference -backup pathspec makes Unison keep backup files for each path that matches pathspec; directories (nor their permissions or any other metadata) are not backed up. These backup files are kept in the directory specified by the backuplocation preference. The backups are named according to the backupprefix and backupsuffix preferences. The number of versions that are kept is determined by the maxbackups preference. The syntax of pathspec is described in Section “Path Specification” in the manual. okay so this is the whole backup ecosystem in one paragraph, iconic ✨
  • backupcurr xxx — including the preference -backupcurr pathspec makes Unison keep a backup of the current version of every file matching pathspec. This file will be saved as a backup with version number 000. Such backups can be used as inputs to external merging programs, for instance. See the documentation for the merge preference. For more details, see Section “Merging Conflicting Versions” in the manual. The syntax of pathspec is described in Section “Path Specification” in the manual. version 000 is giving archive-core fr
  • backupcurrnot xxx — exceptions to backupcurr, like the ignorenot preference. the "actually, not you bestie" list
  • backupdir xxx — if this preference is set, Unison will use it as the name of the directory used to store backup files specified by the backup preference, when backuplocation is set to central. It is checked after the UNISONBACKUPDIR environment variable. env var wins, no cap
  • backuploc xxx — this preference determines whether backups should be kept locally, near the original files, or in a central directory specified by the backupdir preference. If set to local, backups will be kept in the same directory as the original files, and if set to central, backupdir will be used instead. pick your location, main character 💅
  • backupnot xxx — the values of this preference specify paths or individual files or regular expressions that should not be backed up, even if the backup preference selects them—i.e., it selectively overrides backup. it literally overrides, the audacity, we love it
  • backupprefix xxx — when a backup for a file NAME is created, it is stored in a directory specified by backuplocation, in a file called backupprefixNAMEbackupsuffix. backupprefix can include a directory name (causing Unison to keep all backup files for a given directory in a subdirectory with this name), and both backupprefix and backupsuffix can contain the string $VERSION, which will be replaced by the age of the backup (1 for the most recent, 2 for the second most recent, and so on...). This keyword is ignored if it appears in a directory name in the prefix; if it does not appear anywhere in the prefix or the suffix, it will be automatically placed at the beginning of the suffix. One thing to be careful of: If the backuploc preference is set to local, Unison will automatically ignore all files whose prefix and suffix match backupprefix and backupsuffix. So be careful to choose values for these preferences that are sufficiently different from the names of your real files.
fr fr, be careful with this one 😭 if your real files happen to look like your backup naming scheme, Unison will just ignore them. choose something distinctive bestie.
  • backups — (Deprecated) Setting this flag to true is equivalent to setting backuplocation to local and backup to Name *. deprecated alert 🚨 she's retired but still showing up to the party
  • backupsuffix xxx — see backupprefix for full documentation. it's the sibling, same docs, no notes
  • batch — when this is set to true, the user interface will ask no questions at all. Non-conflicting changes will be propagated; conflicts will be skipped. zero questions, zero small talk, just vibes ✨
  • clientHostName xxx — when specified, the host name of the client will not be guessed and the provided host name will be used to find the archive. no guessing games, we tell it directly
  • color xxx — when set to true, this flag enables color output in text mode user interface. When set to false, all color output is disabled. Default is to enable color if the NO_COLOR environment variable is not set. rainbow terminal era unlocked 🌈
  • confirmbigdel — when this is set to true, Unison will request an extra confirmation if it appears that the entire replica has been deleted, before propagating the change. If the batch flag is also set, synchronization will be aborted. When the path preference is used, the same confirmation will be requested for top-level paths. (At the moment, this flag only affects the text user interface.) See also the mountpoint preference.
this is the "did you MEAN to delete literally everything" safety net 💀 do not turn it off casually.
  • confirmmerge — setting this preference causes both the text and graphical interfaces to ask the user if the results of a merge command may be committed to the replica or not. Since the merge command works on temporary files, the user can then cancel all the effects of applying the merge if it turns out that the result is not satisfactory. In batch-mode, this preference has no effect. Default is false. a little "u sure?" before committing, we love a second chance 🫶
  • contactquietly — if this flag is set, Unison will skip displaying the `Contacting server' message (which some users find annoying) during startup. bye bye annoying startup message 👋
  • copymax n — a number indicating how many instances of the external copying utility Unison is allowed to run simultaneously (default to 1). one at a time by default, keep it chill
  • copyonconflict — when this flag is set, Unison will make a copy of files that would otherwise be overwritten or deleted in case of conflicting changes, and more generally whenever the default behavior is overridden. This makes it possible to automatically resolve conflicts in a fairly safe way when synchronizing continuously, in combination with the -repeat watch and -prefer newer preferences. auto-resolve but make it safe, bestie combo move 🔥
  • copyprog xxx — 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. default is already eating, leave it alone ✨
  • copyprogrest xxx — a variant of copyprog that names an external program that should be used to continue the transfer of a large file that has already been partially transferred. Typically, copyprogrest will just be copyprog with one extra option (e.g., --partial, for rsync). The default setting invokes rsync with appropriate options—most users should not need to change it. picking up where it left off, we love a comeback story
  • copyquoterem xxx — when set to true, this flag causes Unison to add an extra layer of quotes to the remote path passed to the external copy program. This is needed by rsync, for example, which internally uses an ssh connection requiring an extra level of quoting for paths containing spaces. When this flag is set to default, extra quotes are added if the value of copyprog contains the string rsync. quote-ception, but make it necessary
  • copythreshold n — 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. big files get the fancy treatment, small ones don't 💅
  • debug xxx — this preference is used to make Unison print various sorts of information about what it is doing internally on the standard error stream. It can be used many times, each time with the name of a module for which debugging information should be printed. Possible arguments for debug can be found by looking for calls to Util.debug in the sources (using, e.g., grep). Setting -debug all causes information from all modules to be printed (this mode of usage is the first one to try, if you are trying to understand something that Unison seems to be doing wrong); -debug verbose turns on some additional debugging output from some modules (e.g., it will show exactly what bytes are being sent across the network). detective mode activated 🔍
  • diff xxx — this preference can be used to control the name and command-line arguments of the system utility used to generate displays of file differences. The default is diff -u OLDER NEWER. If the value of this preference contains the substrings CURRENT1 and CURRENT2, these will be replaced by the names of the files to be diffed. If the value of this preference contains the substrings NEWER and OLDER, these will be replaced by the names of files to be diffed, NEWER being the most recently modified file of the two. Without any of these substrings, the two filenames will be appended to the command. In all cases, the filenames are suitably quoted. spot the difference, but your tool, your rules
  • doc xxx — the command-line argument -doc secname causes unison to display section secname of the manual on the standard output and then exit. Use -doc all to display the whole manual, which includes exactly the same information as the printed and HTML manuals, modulo formatting. Use -doc topics to obtain a list of the names of the various sections that can be printed. the manual reads the manual, self-love honestly 💖
  • 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 keeps failing on you, this is your escape hatch 🚪
  • dumbtty — when set to true, this flag makes the text mode user interface avoid trying to change any of the terminal settings. (Normally, Unison puts the terminal in raw mode', so that it can do things like overwriting the current line.) This is useful, for example, when Unison runs in a shell inside of Emacs. When dumbtty` is set, commands to the user interface need to be followed by a carriage return before Unison will execute them. (When it is off, Unison recognizes keystrokes as soon as they are typed.) This preference has no effect on the graphical user interface. for when your terminal is being weird, no shame 🫶
  • dumparchives — set this and Unison literally makes a file called unison.dump on each host, holding a text summary of the archive, and it drops it immediately after loading the archive. receipts on deck ✨
  • fastcheck xxx — set it to true and Unison stops reading the whole entire contents of every file to scan for updates; instead it uses the file's modification time and length as a pseudo inode number 👑. Bestie, important: this does not apply to the very first run — on that first run Unison always scans all files no matter what this switch says.

Under Windows, this can make Unison miss propagating an update if the modification time and the length of the 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 under Windows most of the time, and occasionally run Unison once with fastcheck set to false if you're worried Unison might have overlooked an update. For backward compatibility, yes, no, and default can be used in place of true, false, and auto. See Section “Fast Update Detection” in the manual for more info 💅.

  • fastercheckUNSAFE — okay so. THIS FEATURE IS STILL EXPERIMENTAL AND SHOULD BE USED WITH EXTREME CAUTION. 😭 Set this flag to true and 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.

It 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 contains files on both sides that Unison has not yet seen, and if those files have the same length but different contents, then Unison will not notice the presence of a conflict 🫠. If, later, one of the files is changed, the changed file will be propagated, overwriting the other. 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 will treat this conservatively as a potential change (since it has no record of the earlier contents) and show it as needing to be propagated to the other replica.

Most users should leave this flag off — the small time savings of not fingerprinting new files is not worth the cost in terms of safety.

However, it can be very useful for power users with huge replicas that are known to be already synchronized (e.g., because one replica is a newly created duplicate of the other, or because they have previously been synchronized with Unison but Unison's archives need to be rebuilt). In such situations, it is recommended that this flag be set only for the initial run of Unison, so that new archives can be created quickly, and then turned off for normal use ⭐.

  • fat — set to true and Unison pulls up with the appropriate options to synchronize efficiently and without error a replica located on a FAT filesystem on a non-Windows machine 🌸. That means:
    • do not synchronize permissions (perms = 0);
    • never use chmod (dontchmod = true);
    • treat filenames as case insensitive (ignorecase = true);
    • do not attempt to synchronize symbolic links (links = false);
    • ignore inode number changes when detecting updates (ignoreinodenumbers = true).

Any of these change can be overridden by explicitly setting the corresponding preference in the profile 💖.

  • follow xxx — including the preference -follow pathspec causes Unison to treat symbolic links matching pathspec as invisible and behave as if the object pointed to by the link had appeared literally at this position in the replica 🦋. See Section “Symbolic Links” in the manual for more details. The syntax of pathspec is described in Section “Path Specification” in the manual.
  • force xxx — including the preference -force root causes Unison to resolve all differences (even non-conflicting changes) in favor of root. This effectively changes Unison from a synchronizer into a mirroring utility 😳. You can also specify -force newer (or -force older) to force Unison to choose the file with the later (earlier) modtime — in this case, the -times preference must also be enabled. This preference is overridden by the forcepartial preference.
This preference should be used only if you are sure you know what you are doing!
  • forcepartial xxx — including the preference forcepartial = PATHSPEC -> root causes Unison to resolve all differences (even non-conflicting changes) in favor of root for the files in PATHSPEC (see Section “Path Specification” in the manual for more info) 🔥. This effectively changes Unison from a synchronizer into a mirroring utility. You can also specify forcepartial PATHSPEC -> newer (or forcepartial PATHSPEC older) to force Unison to choose the file with the later (earlier) modtime — in this case, the -times preference must also be enabled.
This preference should be used only if you are sure you know what you are doing!
  • group — set this flag to true and the group attributes of the files are synchronized 💜. Whether the group names or the group identifiers get synchronized depends on the preference numerids.
  • 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 experience unstabilities with your network link, this may help.
  • height n — used to set the height (in lines) of the main window in the graphical user interface ✨.
  • i — provide this preference in the command line arguments to enable 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 causes Unison to completely ignore paths that match pathspec (as well as their children) 🚫. This is useful for avoiding synchronizing temporary files, object files, etc. The syntax of pathspec is described in Section “Path Specification” in the manual, and further details on ignoring paths is found in Section “Ignoring Paths” in the manual.
  • ignorearchives — set this preference and 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 and this flag causes Unison to treat filenames as case insensitive — i.e., files in the two replicas whose names differ in (upper- and lower-case) spelling' are treated as the **same file** 💅. Set to falseand Unison treats all filenames as case sensitive. Ordinarily, when the flag is set todefault`, 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 😭.
This switch should be used with care, as it is less safe than the standard update detection method, but it can be useful with filesystems which do not support inode numbers.
  • ignorelocks — set this preference and Unison ignores any lock files that may have been left over from a previous run of Unison that was interrupted while reading or writing archive files 🔒. By default, when Unison sees these lock files it will stop and request manual intervention.
This option should be set only if you are positive that no other instance of Unison might be concurrently accessing the same archive files (e.g., because there was only one instance of unison running and it has just crashed or you have just killed it). It is probably not a good idea to set this option in a profile: it is intended for command-line use.
  • ignorenot xxx — this preference overrides the preference ignore 🦋. It gives a list of patterns (in the same format as ignore) for paths that should definitely not be ignored, whether or not they happen to match one of the ignore patterns.

Ngl, the semantics of ignore and ignorenot is a little counter-intuitive 😭. When detecting updates, Unison examines paths in depth-first order, starting from the roots of the replicas and working downwards. Before examining each path, it checks whether it matches ignore and does not match ignorenot; in this case it skips this path and all its descendants. This means that, if some parent of a given path matches an ignore pattern, then it will be skipped even if the path itself matches an 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.

  • immutable xxx — this preference specifies paths for directories whose immediate children are all immutable files — i.e., once a file has been created, its contents never changes 🎀. When scanning for updates, Unison does not check whether these files have been modified; this can speed update detection significantly (in particular, for mail directories) ⚡.
  • immutablenot xxx — this preference overrides immutable 🌸.
  • include xxx — this one pulls in preferences from a profile, bestie. include name reads the profile “name” — or, if profile “name” doesn't exist, the file “name” in the .unison directory — and drops its contents in like they were part of a profile or typed straight onto the command line. it's giving copy-paste but make it config 💅
  • key xxx — used in a profile to define a numeric key (0-9) that you can press in the user interface to switch immediately to this profile. instant teleportation, no cap. ✨
  • killserver — set this to true and Unison will kill the remote server process when the synchronization is finished. This behavior is the default for ssh connections, so you normally don't need this preference when running over ssh; it's here so socket-mode servers can be killed off after a single run of Unison instead of hanging around waiting to accept future connections. (Some users lowkey prefer to start a fresh 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. (Super useful for people who switch between several profiles, especially using the fast switch feature of the graphical user interface.) 🎀
  • links xxx — set it to true and Unison synchronizes symbolic links. Set it to false and symbolic links will result in an error during update detection. When it's 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. 👑
  • listen xxx — when acting as a server on a TCP socket, Unison by default listens on any address (0.0.0.0 and [::]). This command-line argument lets you specify a different listening address, and it can be repeated to listen on multiple addresses. The 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 get appended to the file unison.log in your .unison directory. Set this preference if you'd rather use 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, which lets you do 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 lets Unison 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 desactivated and 1000 threads when it is activated. 🔥
  • merge xxx — this preference can be used to run a merge program which will create a new version for each of the files and the backup, with the last backup and both replicas. The syntax of pathspec -> cmd is described in Section “Path Specification” in the manual, and further details on Merging functions are present in Section “Merging Conflicting Versions” in the manual. 🧚
  • mountpoint xxx — including the preference -mountpoint PATH causes Unison to double-check, at the end of update detection, that PATH exists and abort if it does not. This is useful when Unison is used to synchronize removable media. This preference can be given more than once. See Section “Mount Points and Removable Media” in the manual. 💾
  • nocreation xxx — including the preference -nocreation root prevents Unison from performing any file creation on root root. 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. 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. This preference can be included twice, once for each root, if you want to prevent any update. 🛡️
  • noupdatepartial xxx — including the preference noupdatepartial = PATHSPEC -> root prevents Unison from performing any file update or deletion in PATHSPEC on root root (see Section “Path Specification” in the manual for more information). It is recommended to use BelowPath patterns when selecting a directory and all its contents. 🌸
  • numericids — when this flag is set to true, groups and users are synchronized numerically, rather than by name. The special uid 0 and the special group 0 are never mapped via user/group names even if this preference is not set. 🔢
  • owner — when this flag is set to true, the owner attributes of the files are synchronized. Whether the owner names or the owner identifiers are synchronizeddepends on the preference numerids. 👤
  • path xxx — when no path preference is given, Unison will simply synchronize the two entire replicas, beginning from the given pair of roots. If one or more path preferences are given, then Unison will synchronize only these paths and their children. (This is useful for doing a fast sync of just one directory, for example.) Note that path preferences are interpreted literally — they are not regular expressions. ⚡
  • perms n — the integer value of this preference is a mask indicating which permission bits should be synchronized. It is set by default to $0o1777$: all bits but the set-uid and set-gid bits are synchronised (synchronizing theses latter bits can be a security hazard). If you want to synchronize all bits, you can set the value of this preference to $-1$. If one of the replica is on a FAT [Windows] filesystem, you should consider using the fat preference instead of this preference. If you need Unison not to set permissions at all, set the value of this preference to $0$ and set the preference dontchmod to true. 🔐
  • prefer xxx — including the preference -prefer root causes Unison always to resolve conflicts in favor of root, rather than asking for guidance from the user, except for paths marked by the preference merge. (The syntax of root is the same as for the root preference, plus the special values newer and older.) This preference is overridden by the preferpartial preference. This preference should be used only if you are sure you know what you are doing! 👑
  • preferpartial xxx — including the preference preferpartial = PATHSPEC -> root causes Unison always to resolve conflicts in favor of root, rather than asking for guidance from the user, for the files in PATHSPEC (see Section “Path Specification” in the manual for more information). (The syntax of root is the same as for the root preference, plus the special values newer and older.) This preference should be used only if you are sure you know what you are doing! 👑
  • repeat xxx — setting this preference causes the text-mode interface to synchronize repeatedly, rather than doing it just once and stopping. If the argument is a number, Unison will pause for that many seconds before beginning again. When the argument is watch, Unison relies on an external file monitoring process to synchronize whenever a change happens. 🔁
  • retry n — setting this preference causes the text-mode interface to try again to synchronize updated paths where synchronization fails. Each such path will be tried N times. 💪
  • root xxx — bestie, this one is THE one. every time you use this preference you're naming the root of one of the replicas Unison is gonna synchronize. you need exactly two roots, so the normal ways to do it are either: give two values for root in the profile, or give none in the profile and hand over two on the command line. the deets on root syntax live in Section “Roots” in the manual. the two roots can go in either order — Unison sorts them into a canonical order before it does 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 find the correct archives. 💅
  • rootalias xxx — when Unison is working out the name of the archive files for a given pair of roots, it replaces any roots matching the left-hand side of any rootalias rule with 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 gets stored in Carbon-compatible ._AppleDouble files. set it to false and Unison will not synchronize that data. normally it's set to default, and the data is 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 is no reason to do this, but if you're getting repeated 'rsync failure' errors, setting it to false should let you synchronize the offending files. 🛠️
  • selftest — runs internal tests and exits. this one is 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 will be aborted. (if these aren't given on the command line, dummy subdirectories in the current directory will be created automatically.)
  • servercmd xxx — use this to explicitly set the name of the Unison executable on the remote server (e.g. giving a full path name), if you need to.
  • showarchive — when this is set, Unison prints out the 'true names' of the roots, in the same form that the rootalias preference expects. 🎀
  • silent — set to true and the textual user interface prints nothing at all, except in the case of errors. setting silent to true automatically sets the batch preference to true. 🤫
  • socket xxx — start unison as a server listening on a TCP socket (with the TCP port number as the argument) or a local socket (aka Unix domain socket) (with the socket path as the argument).
  • sortbysize — when this flag is set, the user interface lists changed files by size (smallest first) rather than by name. super useful, for example, when synchronizing over slow links, because it shoves the very large files to the end of the list where they won't stop smaller files from getting transferred quickly. this preference (along with the other sorting flags — 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, which describes 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 — same vibe as sortfirst, except files matching one of these patterns get listed at the very end. 🦋
  • sortnewfirst — set this flag and the user interface lists newly created files before all others. useful, for example, for checking that newly created files aren't 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 were 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 — use this to explicitly set the name of the ssh executable (e.g. giving a full path name), if you need to.
  • stream — (Deprecated) when this is set, Unison uses an experimental streaming protocol for transferring file contents more efficiently. the default value is true.
  • terse — set to true and 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 — set to true and 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 it to false and a Latin 1 encoding is assumed. when Unison runs in case sensitive mode, this flag only makes a difference if one host is running Windows or Mac OS X. under Windows, the flag selects between using the Unicode or 8bit Windows API for accessing the filesystem. under Mac OS X, it selects whether comparing the filenames up to decomposition, or byte-for-byte.
  • 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. 👀
  • xferbycopying — when this 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. this usually lets file moves get propagated very quickly. the default value is true. 🔥

🌱 ROOTS 🌱

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

relative/path/of/root

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

/absolute/path/of/root

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

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

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

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

is used to specify the hostname and the port that the client Unison should use to contact it. 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 this way, there's no need for a Unison server to be running on the remote host. however, running Unison this way is only a good idea if the remote host is reached by a very fast network connection, since the full contents of every file in the remote replica will have to be transferred to the local machine to detect updates. 🫶

🌸 PATHS 🌸

Okay so a path is just a lil pointer to a spot inside the set of files you're syncing — and it's always measured relative to the root of the replica, not from anywhere else. Formally? A path is literally just a sequence of names, glued together with /. And bestie, hear me on this: the separator is always a forward slash, no matter what operating system Unison is running on. Every time. No exceptions. 🫶

And the empty path (yes, the empty sequence of names, zero names, nothing) denotes the whole replica. Iconic, honestly.

✨ PATH SPECIFICATION ✨

So a bunch of Unison preferences — like ignore/ignorenot, follow, sortfirst/sortlast, backup, merge, etc. — let you name individual paths or whole sets of paths. They all share one common syntax, and that syntax is built on regular expressions. Each preference gets associated with a list of path patterns, and the paths it specifies are the ones that match <em>any one</em> of those patterns. Vibe check passed ✅

Every pattern can take one of three forms. The most general one is a Posix extended regular expression, and you introduce it with the keyword Regex. (Fair warning: the collating sequences and character classes of full Posix regexps are not currently supported. 😭)

Regex regexp

But for convenience, there are also three other styles of pattern 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.

Now — the name and path arguments of those latter forms are not regular expressions. Nope! 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. That's the whole point, actually: it 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. So if you need a path specification that contains the separator string, just append an associated string to it, even if it's not used. The associated string cannot contain the separator string. Periodt.

🎀 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 retype them at the command line every single time you run Unison. Because who has the energy for that. 🙈

Profiles should live in the .unison directory on the client machine. Here's how the lookup goes:

  • If Unison is started with just <em>one argument</em> name on the command line, it looks for a profile called name.prf in the .unison directory.
  • If it's started with <em>no arguments</em>, it scans the .unison directory for files whose names end in .prf and offers you a menu — but only when you're 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 a line of this form to the appropriate profile:

p = true

for a boolean flag, or

p = <value>

for a preference of any other type.

Whitespace around p and the value are ignored. A profile may also include blank lines and lines beginning with # — both are ignored, no notes taken. 💅

And here's the order of operations, bestie, write this down: when Unison starts, it first reads the profile and then the command line. So command-line options will override settings from the profile. The CLI is the main character here, lowkey. 👑

🌈 ENVIRONMENT 🌈

  • UNISON — Unison stores a whole 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're 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). Laptop girlies, this one's for you 🧚
  • UNISONBACKUPDIR — When backups are stored centrally, the directory used to hold them is controlled by the preference backupdir and the environment variable UNISONBACKUPDIR. If <em>both</em> 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. (Not me turning off the color though 😭 the aesthetic!)

🦋 FILES 🦋

  • ~/.unison — Unison stores a variety of information in a private directory on each host. This is the default path of this private directory. This path may be changed by the UNISON environment variable.
  • ~/.unison/*.prf — Profile files. Each profile is stored in a file named profilename.prf.
  • ~/.unison/ar*
  • ~/.unison/tm*
  • ~/.unison/sc*

Main and temporary archive files. These files may be deleted if you know what you are doing. Deleting an archive file is 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.
⚠️ Okay genuinely though — deleting archives and locks is powerful-girl behaviour but it's also <em>dangerous</em> behaviour. Read the caveats. Know what you're doing. Don't come for me. 💀

⭐ 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 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. Sneaky!! Watch out for that one.

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. Just so you know before you go looking for the button, bestie. 🙈

💖 DIAGNOSTICS 💖

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

  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. It's giving "we don't do that here."

💖 COMPATIBILITY 💖

okay bestie, here's the tea on mixing versions, and it's actually good news for once 🫶

If you're running Unison versions ≥ 2.52 on all your machines, you literally don't have to do anything extra for compatibility. nothing. zero. go touch grass. ✨

Historically tho (versions < 2.52), Unison versions had to be matched relatively exactly for them to work together — like, bestie, they had to be twins 👯. And on top of that, the version of compiler used to build Unison also had significant relevance for compatibility. yeah. the compiler. wild, i know. 💀

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. the archive survives, she's thriving, she's iconic 👑

For more information on co-existence of versions < 2.52 and ≥ 2.52, see:

https://github.com/bcpierce00/unison/wiki/2.52-Migration-Guide
go read the migration guide if you're mixing old and new, fr fr. it's giving "required reading". 📚

🌈 SEE ALSO 🌈

There is a full user manual (pdf, html and txt) included with Unison and available online. Depending on your operating system, this manual may have been installed at /usr/share/doc/unison/ or a similar location. 👀

You can also read the manual:

  • in the GUI — look in the Help menu 🎀
  • on the command line by running unison -doc all — and bestie, you probably want to pipe the output to a pager, trust me on this one 😭

And here are the links, saved in your notes app forever 💅:

https://github.com/bcpierce00/unison

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

and that's the whole page, bestie!! you made it to the end, i'm so proud of you 🥹💖

this little legend lives at the bottom of the manpage: it's unison, dated March 17, 2022, and it answers to the name UNISON(1). go sync something slay, and remember: read the docs, back up your stuff, and hydrate. periodt. 💅✨🦋👑

📦 where this page comes from