unison

Sync two directories (creates log first time these two directories are synchronized)

$ unison [path/to/directory_1] [path/to/directory_2]

$ unison [path/to/directory_1] [path/to/directory_2] -auto

$ unison [path/to/directory_1] [path/to/directory_2] -ignore [pattern]

$ unison -doc [topics]

unison [options] [root1 [root2]]

root1 and root2 specify the paths to the two replicas to be synchronized. If root2 is omitted, Unison will look for a configured profile.

-batch
    Runs Unison in non-interactive mode, automatically accepting default actions. Useful for scripting.

-auto
    Similar to -batch, but attempts to resolve conflicts automatically without prompting based on configured preferences.

-force [root]
    Forces changes from the specified root (e.g., -force path/to/local or -force ssh://user@host//path/to/remote) to be propagated, even if conflicts occur.

-path [path]
    Synchronizes only the specified relative path within the roots, rather than the entire roots. Can be used multiple times.

-ignore [pattern]
    Specifies patterns for files or directories to be ignored during synchronization (e.g., -ignore "RCS" or -ignore "*~").

-prefer [root]
    In case of conflicts where a file has been modified on both replicas, Unison will prefer the version of the file from the specified root.

-owner
    Preserves file ownership during synchronization.

-group
    Preserves file group during synchronization.

-perms
    Preserves file permissions during synchronization.

-times
    Preserves modification times of files. Highly recommended for accurate synchronization.

-ui [text|gui]
    Specifies the user interface to use; default is text, but a graphical UI is often available if installed.

-server
    Starts Unison in server mode, waiting for a client connection, typically over SSH or a plain socket.

-socket [port]
    Specifies the port for the Unison server or client connection when not using SSH.

Unison is a powerful file synchronization tool that allows users to maintain identical copies of files and directories across two different locations, often referred to as "replicas" or "roots." Unlike simpler tools like rsync which typically perform one-way mirroring, Unison is designed for bidirectional synchronization, meaning it can propagate changes in both directions. It intelligently detects modifications, deletions, and additions on both sides, and proposes actions to bring the replicas into a consistent state.

A key feature of Unison is its ability to handle conflicts gracefully. When a file has been modified independently on both replicas, Unison detects this and prompts the user for a resolution, or can be configured to use a default preference. It operates cross-platform, supporting Unix-like systems (Linux, macOS, BSD) and Windows, allowing synchronization between different operating systems. Unison works by transferring only the changed parts of files, making it efficient over networks. It maintains a persistent state (replicas' past states) to efficiently detect changes and prevent data loss, even if one replica is offline during a sync. It's often used for synchronizing files between a desktop and a laptop, or local and remote servers.

Not a Backup Tool: Unison is designed for synchronization, not backup. While it can recover from some errors, it's not a substitute for a robust backup solution. Accidental deletions or modifications on both sides can lead to data loss if not handled carefully.

Performance with Many Small Files: Synchronizing a very large number of tiny files can be slower than expected due to overhead from metadata processing.

Network Latency: Performance over very high-latency or unstable networks can be poor, as Unison relies on frequent communication between replicas.

Conflict Resolution: While Unison detects conflicts, resolving them in automated modes (-batch, -auto) requires careful configuration to avoid unintended data loss.

Unison works by maintaining a "history" or "archive" of the state of each replica. Before a synchronization, it compares the current state of both replicas with their last-known synchronized states (stored in a local archive file, usually in ~/.unison or _unison directories). By comparing these states, it can efficiently detect which files have been added, deleted, or modified on each side. When changes are detected, it proposes a set of actions (e.g., copy from A to B, copy from B to A, delete, or conflict). Files are transferred efficiently using a secure, compressed protocol, transferring only the differing blocks of data.

Instead of typing long command-line options repeatedly, Unison allows users to create "profiles" (configuration files) typically stored in ~/.unison. These profiles specify the two roots, default options (like -ignore, -prefer, -times), and other synchronization behaviors. A profile named foo.prf can be invoked simply by running unison foo. This makes it easy to manage multiple synchronization tasks with different settings.

Unison was initially developed by Benjamin C. Pierce and his research group at the University of Pennsylvania, with development starting in the early 2000s. It was designed to address the need for a robust, two-way file synchronization tool that could handle concurrent updates and operate reliably across different operating systems. Its strong theoretical foundation, based on the concept of "reconciliation" of replicas, distinguishes it from simpler file mirroring utilities. Over the years, it has gained a reputation as a reliable and flexible tool for users who need to keep multiple copies of data consistent, especially between desktop and laptop computers, or between local and remote file systems.

rsync(1), scp(1), git(1)