Unison File Synchronizer 文件同步使用

Unison File Synchronizer Github 主页

基于 Unison File Synchronizer User Manual and Reference Guide 翻译、补充

unison-manual.pdf

其他类似软件工具还有 FreeFileSync 及 Syncthing

0. 概览

Unison File Synchronizer 是一款由Benjamin Pierce 领导开发的Unix和Windows上的免费文件同步工具. 它允许在不同的主机上（或同一主机的不同磁盘）存放两份文件或目录的集合的副本, 分别修改然后通过将它们的变化传送到每个其他的副本上来更新。

Unison 拥有与其他工具，如配置管理包 (CVS, PRCS, etc.), 分布式文件系统 (Coda, etc.), 单向镜像工具 (rsync, etc.)及其他同步工具 (Intellisync, Reconcile, etc)类似的功能特性. 但是，它也有它自己的不同之处:

• Unison 可以在 Windows (95, 98, NT, 2k, and XP) 和 Unix (OSX, Solaris, Linux, etc.) 系统上运行. 此外，Unison 可以跨平台工作，例如，允许你将Windows 手提电脑与 Unix 服务器同步.
• 与分布式文件系统不同的是, Unison 是一个用户级别的程序（user-level program）: 不需要修改内核或在每个主机上拥有超级用户权限.
• 不同于普通的镜像或备份工具， Unison 可以处理分布式目录结构副本的同时更新（updates to both replicas）. 不冲突的更新可以自动传输，冲突的更新会被检测到并展示出来.
• Unison 可以在任意一组联网的及其间工作，直接使用socket连接或加密的ssh隧道连接通信。它会注意到网络带宽，即使是如PPP连接这样的低速连接也可以很好地工作。大文件的小更新传输使用类似rsync的压缩协议进行优化。
• Unison 具备失败复原功能（ resilient to failure）. 它会随时将副本和它自己的私有结构保持在敏感状态（sensible state）, 即使是不正常的停止或通信中断.
• Unison 是免费的; 所有的代码在 GNU Public License下公开.

1. 下载 Unison

下载地址: http://www.cis.upenn.edu/~bcpierce/unison.

二进制包：Unison Binaries 或 https://github.com/bcpierce00/unison/releases

如果对于客户端机器架构有预编译的二进制版Unison, 只需要下载然后将它放在你能找到的地方(若你是从命令行来启动)或放在桌面(若你是采用双击方式启动).

图形版本的可执行文件 (名称中有 gtkui或gtk ) 实际提供了两个界面: 默认显示图形界面，文字界面可以通过命令行中加 -ui text 来选择. textui 可执行文件仅仅提供了文字界面. 若没有适合你系统架构的编译好的可执行文件，你需要自己编译。 查看Building Unison部分。也有一些不由官方维护，由其他人提供的其他平台的编译版本，查看Contributed Ports 。

注意，如果没有安装GTK运行环境，会报错：“无法启动此程序，因为计算机中丢失libgdk-win32-2.0-0.dll”等问题。前往Github项目GTK-for-Windows-Runtime-Environment-Installer，下载 gtk2-runtime-2.24.30-2016-04-09-ts-win64.exe 安装. 将其lib目录下的libgobject-2.0-0.dll、libgmodule-2.0-0.dll、libglib-2.0-0.dll、libgdk-win32-2.0-0.dll、libgdk_pixbuf-2.0-0.dll 拷贝到unison-gtk所在目录。

可能报错：应用程序无法正常启动0xc000007b（我的没有解决，只能运行text版本的Unison）。

Unison 可在不同的模式下使用: 单一机器的不同目录，通过socket连接的远程机器, 或使用ssh进行验证与安全传输的远程机器. 最后一种方式需要你安装ssh 。查看 installing Ssh.

2. 安装

Unison 可以在两种界面下使用:

• 简单的文字界面, 适用于终端 (及从脚本运行),
• 图形界面,基于 Gtk2 (Linux/Windows) 或原生界面框架 (OSX).

你需要在每台你想要同步的机器上安装Unison . 但是, 你只需要在你真正需要展示界面的机器上(客户端) 安装图形界面版本(如果你确实需要一个GUI). 其他同步的机器可以只安装文字版本.

Windows

Install Unison client on Windows

需要安装SSH（http://cygwin.com/ ）与GTK+运行环境（ http://sourceforge.net/projects/pidgin/files/GTK%2B%20for%20Windows/）

将安装文件目录，如C:\Unison-Windows-2.48.4添加到环境变量，然后将unison 2.48.4 text.exe （gtk不好用）改名为unison.exe ，以后使用unison [options] 或 unison root1 root2 [options] 或 unison profilename [options] 即可（若改名为unison-text.exe，则需要这样用：unison-text unison [options]）。

检查你下载的文件是否是真正的可执行文件，可以点击启动或在命令行中输入unison -version.

# 未添加环境变量、为改名时
C:\Unison-Windows-2.48.4>"unison 2.48.4 text.exe" unison -version
unison version 2.48.4
# 添加环境变量之后
D:\Program Files\ConsoleZ>unison -version
unison version 2.48.4

Linux

假设下载的是 unison-2.48.4-linux-x86_64-text-static.tar.gz ，先解压 tar zxf unison-2.48.4-linux-x86_64-text-static.tar.gz, 然后剪切到/usr/local/bin并改名 sudo mv unison-2.48.4-linux-x86_64-text-static /usr/local/bin/unison , 然后运行并查看版本

[houzw@localhost bin]$ unison -version
unison version 2.48.4

升级

升级之前，最好使用旧版本最后运行同步一次。

Building Unison from Scratch

如果没有预编译版，你需要自行编译程序。

Unix系统下依赖 OCaml (version 3.11.2 or later)、GNU make （一般默认已安装）

3. 使用教程

若使用命令行启动，输入unison就可以启动默认的界面。如果默认是图形界面，在命令行参数中加-ui text可以启用文字界面。其他命令行参数在两种界面模式下都是一样的。

Unison可以在单机时同步不同目录，或同步网络连接的不同机器（所有机器都需要安装unison，区别是哪一台负责显示用户界面）。单机的称此机器为客户端（client）；两台机器时，一台是客户端，一台是服务端（server）。

3.1. 本地（单机）使用

3.2. 远程使用

服务端（server）的机器安装哪一种界面模式的unison都可以，因为服务端机器不需要显示任何用户界面。

需要注意的是，服务端和客户端安装的unison版本最好是一致的（界面模式，即图形或文字，可以不一样）。

Unison 提供了两种不同的客户端与服务端通讯方法:

• 远程 shell方法（Remote shell method ）: 为了使用此方法，你必须有某种在客户端命令行里面远程启用服务端命令的方法, 例如使用 ssh工具等。此方法非常方便，因为它不需要人工去服务端机器上启动 “unison server”进程。同时也是非常安全的，尤其是你使用 ssh时.
• Socket方法 （Socket method）: 此方法只需要你能在服务端和客户端机器之间发送/接收TCP数据包. 严格的防火墙规则可能阻止它，但一旦允许，将可以在任何地点工作.

Remote Shell Method

Unix 上标准的远程 Shell 工具是 ssh. Ssh可以从 http://www.openssh.org 获取. A.2 部分介绍了 Windows 版本的安装.

Windows下可选择的 SSH 连接程序有 MobaXterm、XShell ( xManager )、PuTTY 等等；Unix/Linux 默认都安装了SSH

首先，测试我们是否可以在服务端机器上启用Unison,输入ssh remotehostname unison -version 将会打印出和在本地客户端使用unison -version 命令相同的版本信息. 如果远程执行失败，有可能是ssh连接失败，或者是服务端执行命令的文件目录下没有 unison 可执行文件(如 “command not found”).

在客户端机器的主目录（默认win下是C:\Users\username\.unison，Unix是$HOME/.unison）下创建一个 a.tmp 目录.

测试本地unison客户端可以启动并且能连接到远程服务器. 输入

unison -testServer a.tmp ssh://*remotehostname*/a.tmp 注意a.temp前面是一个/， 而ssh: 后面是两个//.

-testserver 意指连接到服务器之后立即断开 exit immediately after the connection to the server

现在转到你的主目录下，输入:unison a.tmp ssh://remotehostname/a.tmp。 测试结果应该是，你的整个a.tmp目录从你的客户端机器上传输到了服务端机器上。

D:\Program Files\ConsoleZ>unison -testServer a.temp ssh://houzw@centos/a.temp
Contacting server...
Connected [//houzhiwei-PC/D:/Program Files/ConsoleZ/a.temp -> //localhost.localdomain//home/houzw/a.temp]

结束第一次同步之后，修改一少部分文件，然后尝试再次同步。结果应该是类似的。

若你在服务端的用户名与客户端的用户名不一样, 你需要在命令行中指明:unison a.tmp ssh://username@remotehostname/a.tmp
注意 :

• 如果你想将 a.tmp 放在其他地方而不是你在远程主机上的主目录下，你可以在remotehostname和路径开始的地方添加额外的斜杠以给定一个绝对地址： unison a.tmp ssh://remotehostname//absolute/path/to/a.tmp
• 你可以通过使用命令行参数 -servercmd /full/path/name/of/unison 或添加 servercmd=/full/path/name/of/unison 到 profile (Profile ) 来指定Unison可执行文件的明确路径 . 类似的，你可以使用 -sshcmd选项来指明shh程序的路径. 额外的参数可以通过设置 -sshargs 来传给 ssh .

Socket Method

Warning: 此方法不安全。 此方法只提供给专家用户来处理特定需求 ; 其他所有人都应该使用 ssh 方法.

要通过socket 连接来使用Unison, 你必须在服务端启动一个 Unison 后台守护（daemon）进程. 此进程持续运行，等待客户端Unison的socket连接，并处理它们的请求.

要启动一个后台进程，在服务端输入unison -socket NNNN, NNNN 是守护进程需要监听的客户端连接 socket 值。 (NNNN可以是一个不被其他应用使用的很大的数 ; 若 NNNN 已经在使用, Unison 会报错误信息并退出.) 注意，客户端指定的路径会被解析成相对于你启动服务进程所在目录的相对路径。这一点与使用ssh不同, ssh中是相对于服务器主目录的.

在客户端机器的主目录下新建一个测试目录a.tmp. 输入:unison a.tmp socket://*remotehostname*:NNNN/a.tmp 结果应该是客户端上的整个a.tmp目录被传输到服务器上去了 (a.tmp 将会被创建在启动服务的目录下). 其他操作参照ssh连接下操作。

由于 socket 方法使用人数较少, 因此其功能也有限。例如，服务器只能一次处理一个客户端的连接.

3.3. 对所有文件使用Unison | Using Unison for All Your Files

如果你需要经常对使用的文件进行同步，有几种可行的方式:

1. 同步你的整个主目录, 使用忽略机制 (see the Ignore section) 来避免同步临时文件及只属于一个主机的文件。

2. 在每个主机的主目录下创建共享子目录，将需要同步的文件放进去.

3. 在每个主机的主目录下创建共享子目录，将需要同步的文件的链接（links）放入此目录 .查看 Symbolic Links 部分来设置使用 Unison 能够透明的处理这些链接.

4. 使你的主目录成为共享的根目录，但是告诉Unison只同步部分文件和子目录. 可以通过在命令行中切换-path 来完成:

   unison /home/*username* ssh://*remotehost*//home/*username* -path shared

   -path 选项可以按需使用多次来同步文件和文件夹:

   unison /home/username ssh://remotehost//home/username \ -path shared \ -path pub \ -path .netscape/bookmarks.html

   这些-path 参数也可以放入设置文件（ preference file）.查看 Preferences 部分.

多数人会发现他们只需要在他们同步的任何一台主机上维护一个profile (或profiles) , 因为Unison 总会在这个机器上启动. (例如，如果你将你的笔记本与文件服务器同步，你可能会经常在笔记本上同步运行Unison.) 这与其他非对称镜像程序（asymmetric mirroring programs ），如rdist 的使用情景有些不同。那些镜像软件的镜像操作一般需要在最近发生文件变更的机器上使用。 Profile 部分有Unison的profile语法及一些例子。

3.4. 在两台以上机器上使用Unison | Using Unison to Synchronize More Than Two Machines

Unison 被设计用于一组副本之间的同步。但是，他也可以通过执行多个两两同步（ multiple pairwise synchronizations）来实现一大组机器间的同步。.

If you need to do this, the most reliable way to set things up is to organize the machines into a “star topology,” with one machine designated as the “hub” and the rest as “spokes,” and with each spoke machine synchronizing only with the hub. The big advantage of the star topology is that it eliminates the possibility of confusing “spurious conflicts” arising from the fact that a separate archive is maintained by Unison for every pair of hosts that it synchronizes.

群集中，同步在多机之间进行，而unison的同步功能仅支持双机。因此可以设计一个星型的拓扑结构，来实现多机的同步。其设计思想就是利用unison的双向同步功能，指定一台服务器为星型结构的主服务器(server1)，剩余服务器与其进行双向同步。这样，任何一台服务器上的文件变化都可以通过这个结构扩散，从而达到多机同步的目的;这一结构的缺点是一旦server1宕机失效，同步就会失败。因此，有必要的话，可以组成双主服务器的星型结构来弥补。

3.5. 深入 | Going Further

可以在命令行中输入 unison -doc topics或选择图形界面的帮助菜单来获取Unison功能的在线文档.

基本概念 | Basic Concepts

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.

Paths

A path refers to a point within a set of files being synchronized; it is specified relative to the root of the replica.

Caveats and Shortcomings

Here are some things to be careful of when using Unison.

• In the interests of speed, the update detection algorithm may (depending on which OS architecture that you run Unison on) actually use an approximation to the definition given in the What is an Update?section.
  In particular, the Unix implementation does not compare the actual contents of files to their previous contents, but simply looks at each file’s inode number and modtime; if neither of these have changed, then it concludes that the file has not been changed.
  Under normal circumstances, this approximation is safe, in the sense that it may sometimes detect “false updates” but will never miss a real one. However, it is possible to fool it, for example by using retouch to change a file’s modtime back to a time in the past.
• If you synchronize between a single-user filesystem and a shared Unix server, you should pay attention to your permission bits: by default, Unison will synchronize permissions verbatim, which may leave group-writable files on the server that could be written over by a lot of people.
  You can control this by setting your umask on both computers to something like 022, masking out the “world write” and “group write” permission bits.
  Unison does not synchronize the setuid and setgid bits, for security.
• The graphical user interface is single-threaded. This means that if Unison is performing some long-running operation, the display will not be repainted until it finishes. We recommend not trying to do anything with the user interface while Unison is in the middle of detecting changes or propagating files.
• Unison does not understand hard links.
• It is important to be a little careful when renaming directories containing ignored files.
  For example, suppose Unison is synchronizing directory A between the two machines called the “local” and the “remote” machine; suppose directory A contains a subdirectory D; and suppose D on the local machine contains a file or subdirectory P that matches an ignore directive in the profile used to synchronize. Thus path A/D/P exists on the local machine but not on the remote machine.
  If D is renamed to D’ on the remote machine, and this change is propagated to the local machine, all such files or subdirectories P will be deleted. This is because Unison sees the rename as a delete and a separate create: it deletes the old directory (including the ignored files) and creates a new one (not including the ignored files, since they are completely invisible to it).

参考指南 | Reference Guide

运行Unison

多种方法启动 Unison.

• 命令行输入 unison profile . Unison 会查找 .unison 目录下的profile.prf 文件. If this file does not specify a pair of roots, Unison will prompt for them and add them to the information specified by the profile.
• 命令行输入 unison profile root1 root2 . In this case, Unison will use profile, which should not contain any root directives.
• 命令行输入 unison root1 root2 . 与输入 unison default root1 root2具有相同效果
• Typing just “unison” (or invoking Unison by clicking on a desktop icon). In this case, Unison will ask for the profile to use for synchronization (or create a new one, if necessary).

The.unison Directory

Unison 在每个主机的私有目录下存储各种信息. 如果设置了环境变量 UNISON , 那么它的值会被用作目录名. 如果没有定义 UNISON , 那么此目录名称取决于你所使用的操作系统. Unix下, 默认使用 $HOME/.unison. Windows下, 如果设置了环境变量 USERPROFILE , 那么此目录是 $USERPROFILE\.unison; 否则，如果设置了环境变量 HOME , 将会是 $HOME\.unison; 否则, 是 c:\.unison. （应该是C:\Users\username\.unison）

每个副本的存档文件会在每个副本主机的 .unison 目录下. Profiles (下面说明) 一般是从客户端的 .unison目录读取.

Note that Unison maintains a completely different set of archive files for each pair of roots.

不鼓励同步整个 .unison 目录, 因为这会导致经常性的大文件传输。 当然，如果你确实想这么干，也是安全可行的。 Synchronizing just the profile files in the .unisondirectory is definitely OK.

Archive Files

每个副本中的存档文件的名称计算方法：

• the canonical names of all the hosts (短名称如 saul 会被转为完整的地址，如 saul.cis.upenn.edu),
• the paths to the replicas on all the hosts (again, relative pathnames, symbolic links, etc. are converted into full, absolute paths), and
• an internal version number that is changed whenever a new Unison release changes the format of the information stored in the archive.

This method should work well for most users. However, it is occasionally useful to change the way archive names are generated. Unison provides two ways of doing this.

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 gethostnameoperating system call. However, if the environment variable UNISONLOCALHOSTNAMEis 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).

A more powerful way of changing archive names is provided by the rootaliaspreference. The preference file may contain any number of lines of the form:

rootalias = //hostnameA//path-to-replicaA -> //hostnameB/path-to-replicaB

When calculating the name of the archive files for a given pair of roots, Unison replaces any root that matches the left-hand side of any rootalias rule by the corresponding right-hand side.

So, if you need to relocate a root on one of the hosts, you can add a rule of the form: rootalias = //new-hostname//new-path -> //old-hostname/old-path Note that root aliases are case-sensitive, even on case-insensitive file systems.

Warning: The rootalias option is dangerous and should only be used if you are sure you know what you’re doing. In particular, it should only be used if you are positive that either (1) both the original root and the new alias refer to the same set of files, or (2) the files have been relocated so that the original name is now invalid and will never be used again. (If the original root and the alias refer to different sets of files, Unison’s update detector could get confused.) After introducing a new rootalias, it is a good idea to run Unison a few times interactively (with the batch flag off, etc.) and carefully check that things look reasonable—in particular, that update detection is working as expected.

参数选择 | Preferences

Many details of Unison’s behavior are configurable by user-settable “preferences.”

有些选项是布尔值; 这些被称作 flags. 其他数值或字符参数, 用 n 或xxx指明. 大部分是字符型选项可以给多个值，这些参数会在内部转为list.

有两种方式设置选项的值:

临时性的：在某次运行Unison时提供相应的命令行参数,

永久性的：将命令添加到客户端主机的 .unison目录下的 profile .

选项的顺序是无关紧要的. On the command line, preferences and other arguments (the profile name and roots) can be intermixed in any order.

从命令行给选项 p 赋值, 可以在命令行的任何位置添加参数 -p( boolean flag) 或-p n 或 -p xxx (数值或字符型) . 给一个 布尔型标志设置false , 可以使用-p=false.

下面是 Unison 支持的所有选项. 可以通过unison -help来获得.

> Usage: unison [options] > or unison root1 root2 [options] > or unison profilename [options] > > Basic options: > -auto automatically accept default (nonconflicting) actions > -batch batch mode: ask no questions at all , 全自动模式，接受缺省动作并执行。 > -doc xxx show documentation ('-doc topics' lists topics) > -fat use appropriate options for FAT filesystems / FAT文件系统 > -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 / 同步的目录。只同步 -path 参数指定的子目录以及文件，而非整个目录。-path 可以多次出现 > -perms n part of the permissions which is synchronized > -root xxx root of a replica (should be used exactly twice) > -silent print nothing except error messages > -terse suppress status messages > -testserver exit immediately after the connection to the server > -times synchronize modification times > -version print version and exit > > Advanced options: > -addprefsto xxx file to add new prefs to > -addversionno add version number to name of unison on server > -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 keep backup copies of all files (see also 'backup') > -backupsuffix xxx a suffix to be added to names of backup files > -clientHostName xxx set host name of client > -confirmbigdel ask about whole-replica (or path) deletes (default true) > -confirmmerge ask for confirmation before committing results of a merge > -contactquietly suppress the 'contacting server' message during startup > -copymax n maximum number of simultaneous copyprog transfers > -copyonconflict keep copies of conflicting files > -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) > -debug xxx debug module xxx ('all' -> everything, 'verbose' -> more) > -diff xxx set command for showing differences between files > -dontchmod when set, never use the chmod system call > -dumbtty do not change terminal settings in text UI (default true) > -fastcheck xxx do fast update detection (true/false/default) > -fastercheckUNSAFE skip computing fingerprints for new files (experts only!) > -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 > -halfduplex force half-duplex communication with the server > -height n height (in lines) of main window in graphical interface > -host xxx bind the socket to this host name in server socket mode > -ignorearchives ignore existing archive files > -ignorecase xxx identify upper/lowercase filenames (true/false/default) > -ignoreinodenumbers ignore inode number changes when detecting updates > -ignorelocks ignore locks left over from previous run (dangerous!) > -immutable xxx add a pattern to the immutable list > -immutablenot xxx add a pattern to the immutablenot list > -key xxx define a keyboard shortcut for this profile (in some UIs) > -killserver kill server when done (even when using sockets) > -label xxx provide a descriptive string label for this profile > -links xxx allow the synchronization of symbolic links (true/false/default) > -log record actions in logfile (default true) > -logfile xxx logfile name > -maxbackups n number of backed up versions of a file > -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 > -merge xxx add a pattern to the merge list > -mountpoint xxx abort if this path does not exist > -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 > -numericids don't map uid/gid values by user/group names > -prefer xxx choose this replica's version for conflicting changes > -preferpartial xxx add a pattern to the preferpartial list > -repeat xxx synchronize repeatedly (text interface only) > -retry n re-try failed synchronizations N times (text ui only) > -rootalias xxx register alias for canonical root names > -rsrc xxx synchronize resource forks (true/false/default) > -rsync activate the rsync transfer mode (default true) > -selftest run internal tests and exit > -servercmd xxx name of unison executable on remote server > -showarchive show 'true names' (for rootalias) of roots and archive > -socket xxx act as a server on a socket > -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 > -sshargs xxx other arguments (if any) for remote shell command > -sshcmd xxx path to the ssh executable > -stream use a streaming protocol for transferring file contents (default true) > -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 (default true) 使用文件观察进程监测变化 > -xferbycopying optimize transfers using local copies (default true) >

下面是详细说明。 Many are discussed in greater detail in other sections of the manual.

• 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

  When this flag is set to true , Unison will use unison-currentversionnumber instead of just unison as the remote server command. 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.

• auto

  When set to true , this flag causes the user interface to skip asking for confirmations on non-conflicting changes. (More precisely, when the user interface is done setting the propagation direction for one entry and is about to move to the next, it will skip over all non-conflicting entries and go directly to the next conflict.)

• backup xxx

  Including the preference -backup pathspec causes Unison to keep backup files for each path that matches pathspec. 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 maxbackupspreference.The syntax of pathspec is described in the Path Specification section.

• backupcurr xxx

  Including the preference -backupcurr pathspec causes Unison to 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 documentatation for the merge preference. For more details, see theMerging Conflicting Versions section.The syntax of pathspec is described in the Path Specification section.

• backupcurrnot xxx

  Exceptions to backupcurr, like the ignorenot preference.

• 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, whenbackuplocation is set to central. It is checked after the UNISONBACKUPDIR environment variable.

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

• 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. The same caveats apply here as with ignore and ignorenot.

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

• backups

  Setting this flag to true is equivalent to setting backuplocation to localand backup to Name *.

• backupsuffix xxx

  See backupprefix for full documentation.

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

• clientHostName xxx

  When specified, the host name of the client will not be guessedand the provided host name will be used to find the archive.

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

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

• contactquietly

  If this flag is set, Unison will skip displaying the `Contacting server’ message (which some users find annoying) during startup.

• copymax n

  A number indicating how many instances of the external copying utility Unison is allowed to run simultaneously (default to 1).

• 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 overriden. 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.

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

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

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

• copythreshold n

  A number indicating above what filesize (in kilobytes) Unison should use the external copying utility specified by copyprog. Specifying 0 will causeall copies to use the external program; a negative number will prevent any files from using it. The default is -1. See the Making Unison Faster on Large Files section for more information.

• 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 debugcan 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).

• 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 CURRENT2 CURRENT1‘. 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 not, the two filenames will be appended to the command. In both cases, the filenames are suitably quoted.

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

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

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

• dumparchives

  When this preference is set, Unison will create a file unison.dump on each host, containing a text summary of the archive, immediately after loading it.

• fastcheck xxx

  When this preference is set to true, Unison will use the modification time and length of a file as a pseudo inode number when scanning replicas for updates, instead of reading the full contents of every file. (This does not apply to the very first run, when Unison will always scan all files regarless of this switch). Under Windows, this may cause Unison to miss propagating an update if the modification time and length of the file are both unchanged by the update. However, Unison will never overwritesuch an update with a change from the other replica, since it always does a safe check for updates just before propagating a change. Thus, it is reasonable to use this switch under Windows most of the time and occasionally run Unison once with fastcheck set to false, if you are worried that Unison may have overlooked an update. For backward compatibility,yes, no, and default can be used in place of true, false, and auto. See theFast Checking section for more information.

• fastercheckUNSAFE

  THIS FEATURE IS STILL EXPERIMENTAL AND SHOULD BE USED WITH EXTREME CAUTION. When this flag is set to true, Unison will compute a ‘pseudo-fingerprint’ the first time it sees a file (either because the file is new or because Unison is running for the first time). This enormously speeds update detection, but it must be used with care, as it can cause Unison to miss conflicts: If a given path in the filesystem contains files on 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.

  Moreover, even when the files are initially identical, setting this flag can lead to potentially confusing behavior: if a newly created file is later touched without being modified, Unison will treat this conservatively as a potential change (since it has no record of the earlier contents) and show it as needing to be propagated to the other replica.

  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

  When this is set to true, Unison will use appropriate options to synchronize efficiently and without error a replica located on a FAT filesystem on a non-Windows machine: do not synchronize permissions (perms = 0); never use chmod ( t 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 the Symbolic Links section for more details. The syntax of pathspec is described in the Path Specification section.

• 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 -timespreference 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 the Path Specification section for more information). 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

  When this flag is set to true, the group attributes of the files are synchronized. Whether the group names or the group identifiers are synchronized depends on the preference numerids .

• halfduplex

  When this flag is set to true , Unison network communication is forced to be half duplex (the client and the server never simultaneously emit data). If you experience unstabilities with your network link, this may help. The communication is always half-duplex when synchronizing with a Windows machine due to a limitation of Unison current implementation that could result in a deadlock.

• height n

  Used to set the height (in lines) of the main window in the graphical user interface.

• 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 the Path Specification section, and further details on ignoring paths is found in the Ignoring Paths section.

• ignorearchives

  When this preference is set, Unison will ignore any existing archive files and behave as though it were being run for the first time on these replicas. It is not a good idea to set this option in a profile: it is intended for command-line use.

• ignorecase xxx

  When set to true, this flag causes Unison to treat filenames as case insensitive—i.e., files in the two replicas whose names differ in (upper- and lower-case) spelling are treated as the same file. When the flag is set to false, Unison will treat 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

  When set to true, this preference makes Unison not take advantage of inode numbers during fast update detection. This switch should be used with care, as it is less safe than the standard update detection method, but it can be useful with filesystems which do not support inode numbers.

• ignorelocks

  When this preference is set, Unison will ignore any lock files that may have been left over from a previous run of Unison that was interrupted while reading or writing archive files; by default, when Unison sees these lock files it will stop and request manual intervention. This option should be set only if you are 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.

  Note that 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 anignorenot 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.

• key xxx

  Used in a profile to define a numeric key (0-9) that can be used in the graphical user interface to switch immediately to this profile.

• 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 is provided so that socket-mode servers can be killed off after a single run of Unison, rather than waiting to accept future connections. (Some users prefer to start a remote socket server for each run of Unison, rather than leaving one running all the time.)

• 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 result in an error during update detection. Ordinarily, when the flag is set to default, symbolic links are synchronized except when one of the hosts is running Windows. In rare circumstances it may be useful to set the flag manually.

• 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 HOME directory. Set this preference if you prefer another file.

• maxbackups n

  This preference specifies the number of backup versions that will be kept by unison, for each path that matches the predicate backup. The default is 2.

• maxerrors n

  This preference controls after how many errors Unison aborts a directory transfer. Setting it to a large number allows Unison to transfer most of a directory even when some files fail to be copied. The default is 1. If the preference is set too high, Unison may take a long time to abort in case of repeated failures (for instance, when the disk is full).

• maxsizethreshold n

  A number indicating above what filesize (in kilobytes) Unison should flag a conflict instead of transferring the file. This conflict remains even in the presence of force or prefer options. A negative number will allow every transfer independently of the size. The default is -1.

• maxthreads n

  This preference controls how much concurrency is allowed during the transport phase. Normally, it should be set reasonably high to maximize performance, but when Unison is used over a low-bandwidth link it may be helpful to set it lower (e.g. to 1) so that Unison doesn’t soak up all the available bandwidth. The default is the special value 0, which mean 20 threads when file content streaming is 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 the both replicas. Setting the merge preference for a path will also cause this path to be backed up, just like t backup. The syntax of pathspec>cmd is described in the Path Specification section, and further details on Merging functions are present in the Merging files section.

• 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 the Mount Points section.

• 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 thePath Specification section 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 thePath Specification section 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 rootroot (see the Path Specification section 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 pathpreferences 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 intepreted literally—they are not regular expressions.

  可以重复多次，如

  unison /home/username ssh://remotehost//home/username \       -path shared \       -path pub \       -path .netscape/bookmarks.html

• 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 t 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 t dontchmod to t 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. (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 the Path Specification section 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

  Each use of this preference names the root of one of the replicas for Unison to synchronize. Exactly two roots are needed, so normal modes of usage are either to give two values for root in the profile, or to give no values in the profile and provide two on the command line. Details of the syntax of roots can be found in the Roots section.The two roots can be given in either order; Unison will sort them into a canonical order before doing anything else. It also tries to `canonize’ the machine names and paths that appear in the roots, so that, if Unison is invoked later with a slightly different name for the same root, it will be able to locate the correct archives.

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

• rshargs xxx

  The string value of this preference will be passed as additional arguments (besides the host name and the name of the Unison executable on the remote system) to the rsh command used to invoke the remote server.

• rshcmd xxx

  This preference can be used to explicitly set the name of the rsh executable (e.g., giving a full path name), if necessary.

• rsrc xxx

  When set to true, this flag causes Unison to synchronize resource forks and HFS meta-data. On filesystems that do not natively support resource forks, this data is stored in Carbon-compatible ._ AppleDouble files. When the flag is set to false, Unison will not synchronize these data. Ordinarily, the flag is set to default, and these data are automatically synchronized if either host is running OSX. In rare circumstances it is 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 are 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 is provided, no preference file is read: all preferences must be specified on thecommand line. Also, since the self-test procedure involves overwriting the roots and backup directory, the names of the roots and of the backupdir preference must include the string “test” or else the tests will be aborted. (If these are not given on the command line, dummy subdirectories in the current directory will be created automatically.)

• servercmd xxx

  This preference can be used to explicitly set the name of the Unison executable on the remote server (e.g., giving a full path name), if necessary.

• 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 rootaliaspreference.

• silent

  When this preference is set to true, the textual user interface will print nothing at all, except in the case of errors. Setting silent to true automatically sets the batch preference to true.

• sortbysize

  When this flag is set, the user interface will list changed files by size (smallest first) rather than by name. This is useful, for example, for synchronizing over slow links, since it puts very large files at the end of the list where they will not prevent smaller files from being transferred quickly.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 user interface.

• 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 the Path Specificationsection.

• 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 will list newly created files before all others. This is useful, for example, for checking that newly created files are not `junk’, i.e., ones that should be ignored or deleted rather than synchronized.

• sshargs xxx

  The string value of this preference will be passed as additional arguments (besides the host name and the name of the Unison executable on the remote system) to the ssh command used to invoke the remote server.

• sshcmd xxx

  This preference can be used to explicitly set the name of the ssh executable (e.g., giving a full path name), if necessary.

• sshversion xxx

  This preference can be used to control which version of ssh should be used to connect to the server. Legal values are 1 and 2, which will cause unison to try to use ssh1 orssh2 instead of just ssh to invoke ssh. The default value is empty, which will make unison use whatever version of ssh is installed as the default `ssh’ command.

• stream

  When this preference is set, Unison will use an experimental streaming protocol for transferring file contents more efficiently. The default value is true.

• 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.)

• 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, 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, and for continuous synchronization (-repeat watch preference. Setting this flag to false disable the use of this process.

• xferbycopying

  When this preference is set, Unison will try to avoid transferring file contents across the network by recognizing when a file with the required contents already exists in the target replica. This usually allows file moves to be propagated very quickly. The default value istrue.

Profiles

profile 是一个指定 roots, paths, ignore patterns 和其他永久性设置的文本文档, 因此不需要每次运行Unison时都在命令行中指定配置. Profiles 存储在客户端机器的.unison 目录. 如果 Unison 以一个 name 命令行参数启动, Unison会从.unison目录下去找 name.prf 文件. 如果启动时没有参数, 它会扫描 .unison目录中以 .prf 结尾的文件并提供一个菜单 (假设Unison 可执行文件是具有图形界面的). 如果找到一个名称为 default.prf , 那么它的设置会成为默认选择.

永久性地设置选项 p 的值, 可以p = true （布尔型）或p = <value>（其他类型）的形式将其添加到profile文件中.

p 和 xxx 周围的空白会被忽略. 空行以及以 #起始的行都会被忽略。

当 Unison 启动时, 会首先读取profile 然后读取命令行命令，因此命令行命令会覆盖profile中的对应设置.

Profiles 中可以包含 include name 形式的行, 这会读取文件 name (如果此文件不在 .unison目录下时应该是name.prf) , 把文件的内容读取进来作为profile文件的一部分, 而不是 include 行本身. Include 允许将多个profile文件中的公共内容存储到一个文件中.

A profile may include a preference label = desc to provide a description of the options selected in this profile. The string desc is listed along with the profile name in the profile selection dialog, and displayed in the top-right corner of the main Unison window in the graphical user interface.

The graphical user-interface also supports one-key shortcuts for commonly used profiles. If a profile contains a preference of the form key = n, where n is a single digit, then pressing this digit key will cause Unison to immediately switch to this profile and begin synchronization again from scratch. In this case, all actions that have been selected for a set of changes currently being displayed will be discarded.

Sample Profiles

最小 Profile

最简单的一个profile 文件,位于.unison/default.prf:

# Roots of the synchronization
root = /home/bcpierce
root = ssh://saul//home/bcpierce
# Paths to synchronize 
path = current
path = common
path = .netscape/bookmarks.html

基本 Profile

更加复杂的（sophisticated） profile, 列出了其他一些有用的配置.

# Roots of the synchronization
root = /home/bcpierce
root = ssh://saul//home/bcpierce
# Paths to synchronize 
path = current
path = common
path = .netscape/bookmarks.html
# Some regexps specifying names and paths to ignore
ignore = Name temp.*
ignore = Name *~
ignore = Name .*~
ignore = Path */pilot/backup/Archive_*
ignore = Name *.o
ignore = Name *.tmp
# Window height
height = 37
# Keep a backup copy of every file in a central location
backuplocation = central
backupdir = /home/bcpierce/backups
backup = Name *
backupprefix = $VERSION.
backupsuffix = 
# Use this command for displaying diffs
diff = diff -y -W 79 --suppress-common-lines
# Log actions to the terminal
log = true

A Power-User Profile

When Unison is used with large replicas, it is often convenient to be able to synchronize just a part of the replicas on a given run (this saves the time of detecting updates in the other parts). This can be accomplished by splitting up the profile into several parts — a common part containing most of the preference settings, plus one “top-level” file for each set of paths that need to be synchronized. (The include mechanism can also be used to allow the same set of preference settings to be used with different roots.)

The collection of profiles implementing this scheme might look as follows. The file default.prf is empty except for an include directive:

# Include the contents of the file common
include common

Note that the name of the common file is common, not common.prf; this prevents Unison from offering common as one of the list of profiles in the opening dialog (in the graphical UI).

The file common contains the real preferences:

# Roots of the synchronization
root = /home/bcpierce
root = ssh://saul//home/bcpierce
# (... other preferences ...)
# If any new preferences are added by Unison (e.g. 'ignore'
# preferences added via the graphical UI), then store them in the
# file 'common' rathen than in the top-level preference file
addprefsto = common
# Names and paths to ignore:
ignore = Name temp.*
ignore = Name *~
ignore = Name .*~
ignore = Path */pilot/backup/Archive_*
ignore = Name *.o
ignore = Name *.tmp

Note that there are no path preferences in common. This means that, when we invoke Unison with the default profile (e.g., by typing unison defaultor just unison on the command line), the whole replicas will be synchronized. (If we never want to synchronize the whole replicas, then default.prf would instead include settings for all the paths that are usually synchronized.)

To synchronize just part of the replicas, Unison is invoked with an alternate preference file—e.g., doing unison workingset, where the preference fileworkingset.prf contains

path = current/papers
path = Mail/inbox
path = Mail/drafts
include common

causes Unison to synchronize just the listed subdirectories.

The key preference can be used in combination with the graphical UI to quickly switch between different sets of paths. For example, if the file mail.prfcontains

path = Mail
batch = true
key = 2
include common

then pressing 2 will cause Unison to look for updates in the Mail subdirectory and (because the batch flag is set) immediately propagate any that it finds.

Keeping Backups

When Unison overwrites a file or directory by propagating a new version from the other replica, it can keep the old version around as a backup. There are several preferences that control precisely where these backups are stored and how they are named.

To enable backups, you must give one or more backup preferences. Each of these has the form backup = <pathspec>where <pathspec> has the same form as for the ignore preference. For example, backup = Name *causes Unison to keep backups of all files and directories. The backupnotpreference can be used to give a few exceptions: it specifies which files and directories should not be backed up, even if they match the backup pathspec.

It is important to note that the pathspec is matched against the path that is being updated by Unison, not its descendants. For example, if you set backup = Name *.txt and then delete a whole directory named foo containing some text files, these files will not be backed up because Unison will just check that foodoes not match *.txt. Similarly, if the directory itself happened to be calledfoo.txt, then the whole directory and all the files in it will be backed up, regardless of their names.

Backup files can be stored either centrally or locally. This behavior is controlled by the preference backuplocation, whose value must be either centralor local. (The default is central.)

When backups are stored locally, they are kept in the same directory as the original.

When backups are stored centrally, the directory used to hold them is controlled by the preference backupdir and the environment variableUNISONBACKUPDIR. (The environment variable is checked first.) If neither of these are set, then the directory .unison/backup in the user’s home directory is used.

The preference maxbackups controls how many previous versions of each file are kept (including the current version).

By default, backup files are named .bak.VERSION.FILENAME, where FILENAME is the original filename and VERSION is the backup number (1 for the most recent, 2 for the next most recent, etc.). This can be changed by setting the preferences backupprefix and/or backupsuffix. If desired, backupprefix may include a directory prefix; this can be used with backuplocation = local to put all backup files for each directory into a single subdirectory. For example, setting

backuplocation = local
backupprefix = .unison/$VERSION.
backupsuffix =

will put all backups in a local subdirectory named .unison. Also, note that the string $VERSION in either backupprefix or backupsuffix (it must appear in one or the other) is replaced by the version number. This can be used, for example, to ensure that backup files retain the same extension as the originals.

For backward compatibility, the backups preference is also supported. It simply means backup = Name * and backuplocation = local.

Merging Conflicting Versions

Unison can invoke external programs to merge conflicting versions of a file. The preference merge controls this process.

The merge preference may be given once or several times in a preference file (it can also be given on the command line, of course, but this tends to be awkward because of the spaces and special characters involved). Each instance of the preference looks like this:merge = <PATHSPEC> -> <MERGECMD>

The <PATHSPEC> here has exactly the same format as for the ignore preference (see the

Path specification section). For example, using “Name *.txt” as the<PATHSPEC> tells Unison that this command should be used whenever a file with extension .txt needs to be merged.

Many external merging programs require as inputs not just the two files that need to be merged, but also a file containing the last synchronized version. You can ask Unison to keep a copy of the last synchronized version for some files using the backupcurrent preference. This preference is used in exactly the same way as backup and its meaning is similar, except that it causes backups to be kept of the current contents of each file after it has been synchronized by Unison, rather than the previous contents that Unison overwrote. These backups are kept on both replicas in the same place as ordinary backup files—i.e. according to the backuplocation and backupdir preferences. They are named like the original files if backupslocation

is set to ‘central’ and otherwise, Unison uses the backupprefix and backupsuffix preferences and assumes a version number 000 for these backups.

The <MERGECMD> part of the preference specifies what external command should be invoked to merge files at paths matching the <PATHSPEC>. Within this string, several special substrings are recognized; these will be substituted with appropriate values before invoking a sub-shell to execute the command.

• CURRENT1 is replaced by the name of (a temporary copy of) the local variant of the file.
• CURRENT2 is replaced by the name of a temporary file, into which the contents of the remote variant of the file have been transferred by Unison prior to performing the merge.
• CURRENTARCH is replaced by the name of the backed up copy of the original version of the file (i.e., the file saved by Unison if the current filename matches the path specifications for the backupcurrent preference, as explained above), if one exists. If no archive exists and CURRENTARCHappears in the merge command, then an error is signalled.
• CURRENTARCHOPT is replaced by the name of the backed up copy of the original version of the file (i.e., its state at the end of the last successful run of Unison), if one exists, or the empty string if no archive exists.
• NEW is replaced by the name of a temporary file that Unison expects to be written by the merge program when it finishes, giving the desired new contents of the file.
• PATH is replaced by the path (relative to the roots of the replicas) of the file being merged.
• NEW1 and NEW2 are replaced by the names of temporary files that Unison expects to be written by the merge program when it is only able to partially merge the originals; in this case, NEW1 will be written back to the local replica and NEW2 to the remote replica; NEWARCH, if present, will be used as the “last common state” of the replicas. (These three options are provided for later compatibility with the Harmony data synchronizer.)

To accommodate the wide variety of programs that users might want to use for merging, Unison checks for several possible situations when the merge program exits:

• If the merge program exits with a non-zero status, then merge is considered to have failed and the replicas are not changed.
• If the file NEW has been created, it is written back to both replicas (and stored in the backup directory). Similarly, if just the file NEW1 has been created, it is written back to both replicas.
• If neither NEW nor NEW1 have been created, then Unison examines the temporary files CURRENT1 and CURRENT2 that were given as inputs to the merge program. If either has been changed (or both have been changed in identical ways), then its new contents are written back to both replicas. If either CURRENT1 or CURRENT2 has been deleted, then the contents of the other are written back to both replicas.
• If the files NEW1, NEW2, and NEWARCH have all been created, they are written back to the local replica, remote replica, and backup directory, respectively. If the files NEW1, NEW2 have been created, but NEWARCH has not, then these files are written back to the local replica and remote replica, respectively. Also, if NEW1 and NEW2 have identical contents, then the same contents are stored as a backup (if the backupcurrent preference is set for this path) to reflect the fact that the path is currently in sync.
• If NEW1 and NEW2 (resp. CURRENT1 and CURRENT2) are created (resp. overwritten) with different contents but the merge command did not fail (i.e., it exited with status code 0), then we copy NEW1 (resp. CURRENT1) to the other replica and to the archive.
  This behavior is a design choice made to handle the case where a merge command only synchronizes some specific contents between two files, skipping some irrelevant information (order between entries, for instance). We assume that, if the merge command exits normally, then the two resulting files are “as good as equal.” (The reason we copy one on top of the other is to avoid Unison detecting that the files are unequal the next time it is run and trying again to merge them when, in fact, the merge program has already made them as similar as it is able to.)

If the confirmmerge preference is set and Unison is not run in batch mode, then Unison will always ask for confirmation before actually committing the results of the merge to the replicas.

A large number of external merging programs are available. For example, on Unix systems setting the merge preference to

merge = Name *.txt -> diff3 -m CURRENT1 CURRENTARCH CURRENT2
                        > NEW || echo "differences detected"

will tell Unison to use the external diff3 program for merging. Alternatively, users of emacs may find the following settings convenient:

merge = Name *.txt -> emacs -q --eval '(ediff-merge-files-with-ancestor 
                         "CURRENT1" "CURRENT2" "CURRENTARCH" nil "NEW")'

(These commands are displayed here on two lines to avoid running off the edge of the page. In your preference file, each command should be written on a single line.)

Users running emacs under windows may find something like this useful:

merge = Name * -> C:\Progra~1\Emacs\emacs\bin\emacs.exe -q --eval
                         "(ediff-files """CURRENT1""" """CURRENT2""")"

Users running Mac OS X (you may need the Developer Tools installed to get the opendiff utility) may prefer merge = Name *.txt -> opendiff CURRENT1 CURRENT2 -ancestor CURRENTARCH -merge NEW

Here is a slightly more involved hack. The opendiff program can operate either with or without an archive file. A merge command of this form

merge = Name *.txt -> 
          if [ CURRENTARCHOPTx = x ]; 
          then opendiff CURRENT1 CURRENT2 -merge NEW; 
          else opendiff CURRENT1 CURRENT2 -ancestor CURRENTARCHOPT -merge NEW; 
          fi

(still all on one line in the preference file!) will test whether an archive file exists and use the appropriate variant of the arguments to opendiff.

Linux users may enjoy this variant:

merge = Name * -> kdiff3 -o NEW CURRENTARCHOPT CURRENT1 CURRENT2

Ordinarily, external merge programs are only invoked when Unison is notrunning in batch mode. To specify an external merge program that should be used no matter the setting of the batch flag, use the mergebatch preference instead of merge.

Please post suggestions for other useful values of the merge preference to the unison-users mailing list—we’d like to give several examples here.

The User Interface

Both the textual and the graphical user interfaces are intended to be mostly self-explanatory. Here are just a few tricks:

• By default, when running on Unix the textual user interface will try to put the terminal into the “raw mode” so that it reads the input a character at a time rather than a line at a time. (This means you can type just the single keystroke “>” to tell Unison to propagate a file from left to right, rather than “> Enter.”)
  There are some situations, though, where this will not work — for example, when Unison is running in a shell window inside Emacs. Setting the dumbtty preference will force Unison to leave the terminal alone and process input a line at a time.

Exit code

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

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

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

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.

• Pattern preferences can be given on the command line, or, more often, stored in profiles, using the same syntax as other preferences. For example, a profile line of the formignore = patternaddspatternto the list of patterns to be ignored.
• 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).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, andBelowPath *path*matches the path path and any path below. The name and patharguments 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.

Some examples of path patterns appear in the Ignoring Paths section.

Ignoring Paths

Most users of Unison will find that their replicas contain lots of files that they don’t ever want to synchronize — temporary files, very large files, old stuff, architecture-specific binaries, etc. They can instruct Unison to ignore these paths using patterns introduced in the Path Patterns section.

For example, the following pattern will make Unison ignore any path containing the name CVS or a name ending in .cmo:ignore = Name {CVS,*.cmo}

The next pattern makes Unison ignore the path a/b: ignore = Path a/b

Path patterns do not skip filesnames beginning with . (as Name patterns do). For example,ignore = Path */tmpwill include .foo/tmp in the set of ignore directories, as it is a path, not a name, that is ignored.

The following pattern makes Unison ignore any path beginning with a/b and ending with a name ending by .ml.ignore = Regex a/b/.*\.ml

Note that regular expression patterns are “anchored”: they must match the whole path, not just a substring of the path.

Here are a few extra points regarding the ignore preference.

• If a directory is ignored, all its descendents will be too.
• The user interface provides some convenient commands for adding new patterns to be ignored. To ignore a particular file, select it and press “i”. To ignore all files with the same extension, select it and press “E” (with the shift key). To ignore all files with the same name, no matter what directory they appear in, select it and press “N”. These new patterns become permanent: they are immediately added to the current profile on disk.
• If you use the include directive to include a common collection of preferences in several top-level preference files, you will probably also want to set the addprefsto preference to the name of this file. This will cause any new ignore patterns that you add from inside Unison to be appended to this file, instead of whichever top-level preference file you started Unison with.
• Ignore patterns can also be specified on the command line, if you like (this is probably not very useful), using an option like -ignore 'Name temp.txt'.
• Be careful about renaming directories containing ignored files. Because Unison understands the rename as a delete plus a create, any ignored files in the directory will be lost (since they are invisible to Unison and therefore they do not get recreated in the new version of the directory).
• There is also an ignorenot preference, which specifies a set of patterns for paths that should not be ignored, even if they match an ignorepattern. However, the interaction of these two sets of patterns can be a little tricky. Here is exactly how it works:Unison starts detecting updates from the root of the replicas—i.e., from the empty path. If the empty path matches an ignorepattern and does not match an ignorenot pattern, then the whole replica will be ignored. (For this reason, it is not a good idea to include Name * as an ignore pattern. If you want to ignore everything except a certain set of files, use Name ?*.)If the root is a directory, Unison continues looking for updates in all the immediate children of the root. Again, if the name of some child matches an ignore pattern and does not match anignorenot pattern, then this whole path including everything below it will be ignored.If any of the non-ignored children are directories, then the process continues recursively.

Symbolic Links

Ordinarily, Unison treats symbolic links in Unix replicas as “opaque”: it considers the contents of the link to be just the string specifying where the link points, and it will propagate changes in this string to the other replica.

It is sometimes useful to treat a symbolic link “transparently,” acting as though whatever it points to were physically in the replica at the point where the symbolic link appears. To tell Unison to treat a link in this manner, add a line of the formfollow = pathspecto the profile, where pathspec is a path pattern as described in the Path Patterns section.

Windows file systems do not support symbolic links; Unison will refuse to propagate an opaque symbolic link from Unix to Windows and flag the path as erroneous. When a Unix replica is to be synchronized with a Windows system, all symbolic links should match either an ignore pattern or a followpattern.

Permissions

Synchronizing the permission bits of files is slightly tricky when two different filesytems are involved (e.g., when synchronizing a Windows client and a Unix server). In detail, here’s how it works:

• When the permission bits of an existing file or directory are changed, the values of those bits that make sense on both operating systems will be propagated to the other replica. The other bits will not be changed.
• When a newly created file is propagated to a remote replica, the permission bits that make sense in both operating systems are also propagated. The values of the other bits are set to default values (they are taken from the current umask, if the receiving host is a Unix system).
• For security reasons, the Unix setuid and setgid bits are not propagated.
• The Unix owner and group ids are not propagated. (What would this mean, in general?) All files are created with the owner and group of the server process.

Cross-Platform Synchronization

If you use Unison to synchronize files between Windows and Unix systems, there are a few special issues to be aware of.

Case conflicts. In Unix, filenames are case sensitive: foo and FOO can refer to different files. In Windows, on the other hand, filenames are not case sensitive: foo and FOO can only refer to the same file. This means that a Unixfoo and FOO cannot be synchronized onto a Windows system — Windows won’t allow two different files to have the “same” name. Unison detects this situation for you, and reports that it cannot synchronize the files.

You can deal with a case conflict in a couple of ways. If you need to have both files on the Windows system, your only choice is to rename one of the Unix files to avoid the case conflict, and re-synchronize. If you don’t need the files on the Windows system, you can simply disregard Unison’s warning message, and go ahead with the synchronization; Unison won’t touch those files. If you don’t want to see the warning on each synchronization, you can tell Unison to ignore the files (see the Ignore section).

Illegal filenames. Unix allows some filenames that are illegal in Windows. For example, colons (:) are not allowed in Windows filenames, but they are legal in Unix filenames. This means that a Unix file foo:bar can’t be synchronized to a Windows system. As with case conflicts, Unison detects this situation for you, and you have the same options: you can either rename the Unix file and re-synchronize, or you can ignore it.

Slow Links

Unison is built to run well even over relatively slow links such as modems and DSL connections.

Unison uses the rsync protocol designed by Andrew Tridgell and Paul Mackerras to greatly speed up transfers of large files in which only small changes have been made. More information about the rsync protocol can be found at the rsync web site (http://samba.anu.edu.au/rsync/).

If you are using Unison with ssh, you may get some speed improvement by enabling ssh‘s compression feature. Do this by adding the option “-sshargs -C” to the command line or “sshargs = -C” to your profile.

Making Unison Faster on Large Files

Unison’s built-in implementation of the rsync algorithm makes transferring updates to existing files pretty fast. However, for whole-file copies of newly created files, the built-in transfer method is not highly optimized. Also, if Unison is interrupted in the middle of transferring a large file, it will attempt to retransfer the whole thing on the next run.

These shortcomings can be addressed with a little extra work by telling Unison to use an external file copying utility for whole-file transfers. The recommended one is the standalone rsync tool, which is available by default on most Unix systems and can easily be installed on Windows systems using Cygwin.

If you have rsync installed on both hosts, you can make Unison use it simply by setting the copythreshold flag to something non-negative. If you set it to 0, Unison will use the external copy utility for all whole-file transfers. (This is probably slower than letting Unison copy small files by itself, but can be useful for testing.) If you set it to a larger value, Unison will use the external utility for all files larger than this size (which is given in kilobytes, so setting it to 1000 will cause the external tool to be used for all transfers larger than a megabyte).

If you want to use a different external copy utility, set both the copyprog andcopyprogpartial preferences—the former is used for the first transfer of a file, while the latter is used when Unison sees a partially transferred temp file on the receiving host. Be careful here: Your external tool needs to be instructed to copy files in place (otherwise if the transfer is interrupted Unison will not notice that some of the data has already been transferred, the next time it tries). The default values are:

copyprog      =   rsync --inplace --compress
copyprogrest  =   rsync --partial --inplace --compress

You may also need to set the copyquoterem preference. When it is set to true, this causes Unison to add an extra layer of quotes to the remote path passed to the external copy program. This is 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. The default value is default, naturally.

If a directory transfer is interrupted, the next run of Unison will automatically skip any files that were completely transferred before the interruption. (This behavior is always on: it does not depend on the setting of the copythreshold preference.) Note, though, that the new directory will not appear in the destination filesystem until everything has been transferred—partially transferred directories are kept in a temporary location (with names like.unison.DIRNAME....) until the transfer is complete.

Fast Update Detection

If your replicas are large and at least one of them is on a Windows system, you may find that Unison’s default method for detecting changes (which involves scanning the full contents of every file on every sync—the only completely safe way to do it under Windows) is too slow. Unison provides a preference fastcheck that, when set to true, causes it to use file creation times as ‘pseudo inode numbers’ when scanning replicas for updates, instead of reading the full contents of every file.

When fastcheck is set to no, Unison will perform slow checking—re-scanning the contents of each file on each synchronization—on all replicas. When fastcheckis set to default (which, naturally, is the default), Unison will use fast checks on Unix replicas and slow checks on Windows replicas.

This strategy may cause Unison to miss propagating an update if the modification time and length of the file are both unchanged by the update. However, Unison will never overwrite such an update with a change from the other replica, since it always does a safe check for updates just before propagating a change. Thus, it is reasonable to use this switch most of the time and occasionally run Unison once with fastcheck set to no, if you are worried that Unison may have overlooked an update.

Fastcheck is (always) automatically disabled for files with extension .xls or.mpp, to prevent Unison from being confused by the habits of certain programs (Excel, in particular) of updating files without changing their modification times.

Mount Points and Removable Media

Using Unison removable media such as USB drives can be dangerous unless you are careful. If you synchronize a directory that is stored on removable media when the media is not present, it will look to Unison as though the whole directory has been deleted, and it will proceed to delete the directory from the other replica—probably not what you want!

To prevent accidents, Unison provides a preference called mountpoint. Including a line likemountpoint = fooin your preference file will cause Unison to check, after it finishes detecting updates, that something actually exists at the path foo on both replicas; if it does not, the Unison run will abort.

Click-starting Unison

On Windows NT/2k/XP systems, the graphical version of Unison can be invoked directly by clicking on its icon. On Windows 95/98 systems, click-starting also works, as long as you are not using ssh. Due to an incompatibility with ocaml and Windows 95/98 that is not under our control, you must start Unison from a DOS window in Windows 95/98 if you want to use ssh.

When you click on the Unison icon, two windows will be created: Unison’s regular window, plus a console window, which is used only for giving your password to ssh (if you do not use ssh to connect, you can ignore this window). When your password is requested, you’ll need to activate the console window (e.g., by clicking in it) before typing. If you start Unison from a DOS window, Unison’s regular window will appear and you will type your password in the DOS window you were using.

To use Unison in this mode, you must first create a profile (see the Profile section). Use your favorite editor for this.

安装Ssh

你的本地主机只需要一个ssh客户端; 远程主机需要一个ssh服务端（或一个守护进程daemon）, 这在 Unix 系统上是可用的. Unison 可以工作的 ssh 版本是 1.2.27 (Unix) 和1.2.14 (Windows); 其他版本可能不能用.

如果安装了git，在安装目录的/usr/bin目录下已经包含了ssh程序

Unix

现代的 Unix一般预装了 ssh .

Windows

很多ssh的 Windows 实现都只有图形界面，但是 Unison 需要一个 能在命令行下运行的ssh 客户端. 可按照下列步骤安装一个合适版本的ssh.

1. 下载一个 ssh 可执行文件
   Warning: Windows下现在有许多的 ssh 实现, 并不是所有的都能够 配合Unison使用. 我们使用了Cygwin’s 的 openssh（Cygwin’s port of openssh）和 Unison 一起工作 , 我们建议你首先尝试使用它。下面是安装方法:

   • 首先,创建 一个临时目录来存放安装文件 ，假设此目录名称为 Foo.

   • 访问 www.cygwin.com, 点击 “Install now!” 链接， 此操作将会下载一个安装文件, setup-x86.exe（或 setup-x86_64.exe）; 保存到 Foo. 安装文件 setup-x86_64.exe 是一个小程序，当你运行它时，会从互联网下载真正的安装文件.

   • 双击setup.exe，会出现一系列的对话框. 选择 “Install from Internet.” 。“Local Package Directory” 选择 Foo. 对于 “Select install root directory” 我们建议你使用默认的 C:\cygwin. 随后会需要选择连接类型，根据你的网络情况选择。下一步选择一个软件镜像，选择离你最近的一个(如 http://mirrors.ustc.edu.cn) .

     接下来会需要你选择需要安装的包. 默认的设置会下载很多对于Unison使用ssh不必要的包. 若你不想安装某个包, 点击使其出现 “skip” . 对于最小化的安装，你只需要选择 “cygwin” 和“openssh,” 大概 1900KB; 而整个安装的话包会大很多.

     • Note that you are plan to build unison using the free CygWin GNU C compiler, you need to install essential development packages such as “gcc”, “make”, “fileutil”, etc; we refer to the file “INSTALL.win32-cygwin-gnuc” in the source distribution for further details.

所有包下载和安装完成之后,你可以删除 `Foo` 目录了.有些人报告了使用Cygwin's ssh 和Unison的一些问题. 如果你遇到麻烦你可以使用另外一个ssh: `  http://linuxmafia.com/ssh/win32.html`

1. 你必须设置 HOME 和 PATH 环境变量 . Ssh 会在给定的HOME目录下创建一个 .ssh 目录, 从而有地方存放数据，如你的公共和私有密钥. PATH 必须被设置到 Cygwin的 bin 目录, 从而使 Unison 可以找到 ssh 的可执行文件.

   安装完成后以管理员身份运行cygwin终端，输入ssh-host-config对ssh进行配置

   配置时可以一路选择yes（privilege separation -> no）

   如果出现 Enter the value of CYGWIN for the daemon: []

   输入ntsec

   出现Info: Host configuration finished. Have fun!之后，输入net start sshd启动ssh服务

   关于HOME环境变量：最好不设置！

   Cygwin确定用户主目录有几个原则，依照顺序确定主目录。首先查看系统的HOME环境变量，其次查看/etc/passwd中为用户设置的主目录。有的软件遵照这个原则，而有些Cygwin应用，如ssh，却没有使用HOME环境变量而直接使用/etc/passwd中的的设置（这会导致ssh-keygen 生成的密钥对文件不会存放到设置的HOME目录(如D:\Programs\SSH，即 /cygdrive/d/Programs/SSH)下，而是其默认目录下，如/home/houzw/.ssh/id_rsa）。要想避免在同一个Cygwin环境下有两个不同的用户主目录设置，可以采用下面两种方法。

   • 方法1：修改Cygwin启动的批处理文件（如：C:\cygwin\Cygwin.bat），在批处理的开头添加如下的一行，就可以清除其他软件为Windows引入的HOME环境变量。set HOME=

     此方法时，ssh-keygen还是默认使用的/etc/passwd中的的设置

   • 方法2：如果希望使用HOME环境变量指向的主目录，则通过手工编辑/etc/passwd文件，将其中用户主目录修改成HOME环境变量所指向的目录。（ssh-keygen不再使用默认的/etc/passwd中的的设置，但是ssh localhost登录之后仍是其中的路径，没办法免密码登录localhost ？）

     若没有passwd文件，则创建一个：mkpasswd -l > /etc/passwd ，内容会自动生成。

     passwd文件每一行内容： 用户名:口令:用户标识号:组标识号:注释性描述:主目录:登录Shell

     将 houzw:*:197608:197121:U-houzw-PC\houzw,S-1-5-21-1228681770-2473699563-3202222160-1000:/home/houzw:/bin/bash中的/home/houzw 修改为/cygdrive/d/Programs/SSH

2. DOS环境下的命令行测试 ssh ，输入 ssh <remote host> -l <login name>

   你会得到一个让你输入远程主机密码的提示.

3. 注意， ssh-keygen 在某些系统上可能会失败 (报错“gethostname: no such file or directory” ) . 没有关系: 你可以使用ssh 利用密码来连接远程系统.

4. 此时应该可以使用ssh连接来使用 Unison. 如果你本地和远程主机的登录用户名不一样, 连接时需要提供远程主机的用户名 (//username@host/path...).