[unison240] Add documentation
brummbq
brummbq at fedoraproject.org
Sun Jan 22 11:44:04 UTC 2012
commit cd214dd4727e3bd128ed14d51a7c94637024c586
Author: Gregor Tätzner <gregor at freenet.de>
Date: Sun Jan 22 12:43:50 2012 +0100
Add documentation
unison-2.40.63-manual.html | 4709 +++++++++++++++++++++++++++++++++
unison240-missing-documentation.patch | 4474 +++++++++++++++++++++++++++++++
unison240.spec | 43 +-
3 files changed, 9215 insertions(+), 11 deletions(-)
---
diff --git a/unison-2.40.63-manual.html b/unison-2.40.63-manual.html
new file mode 100644
index 0000000..0ec37b0
--- /dev/null
+++ b/unison-2.40.63-manual.html
@@ -0,0 +1,4709 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
+ "http://www.w3.org/TR/REC-html40/loose.dtd">
+<HTML>
+
+<HEAD>
+
+
+<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<META name="GENERATOR" content="hevea 1.08">
+<STYLE type="text/css">
+.toc{list-style:none;}
+.title{margin:auto;text-align:center}
+.center{text-align:center;margin-left:auto;margin-right:auto;}
+.flushleft{text-align:left;margin-left:0ex;margin-right:auto;}
+.flushright{text-align:right;margin-left:auto;margin-right:0ex;}
+DIV TABLE{margin-left:inherit;margin-right:inherit;}
+PRE{text-align:left;margin-left:0ex;margin-right:auto;}
+BLOCKQUOTE{margin-left:4ex;margin-right:4ex;text-align:left;}
+.part{margin:auto;text-align:center}
+</STYLE>
+
+ <META name="Author" content="Benjamin C. Pierce">
+ <link rel="stylesheet" href="http://www.cis.upenn.edu/~bcpierce/unison/unison.css">
+ </HEAD>
+
+<BODY >
+<!--HEVEA command line is: hevea unison-manual.tex -->
+<!--HTMLHEAD-->
+<!--ENDHTML-->
+<!--PREFIX <ARG ></ARG>-->
+<!--CUT DEF section 1 -->
+
+<BR>
+<BR>
+<div id="manualbody"><BR>
+<BR>
+<div id="manualheader"><DIV CLASS="center"><FONT SIZE=7><FONT COLOR=black>Unison File Synchronizer</FONT><BR>
+<FONT SIZE=6><FONT COLOR=black>User Manual and Reference Guide</FONT><BR>
+<FONT SIZE=5>Version 2.40.61<BR>
+<FONT SIZE=4>Copyright 1998-2009, Benjamin C. Pierce
+ </FONT></FONT></FONT></FONT></DIV></div><BR>
+<BR>
+<!--TOC section Contents-->
+
+<H2 CLASS="section">Contents</H2><!--SEC END -->
+
+ <BLOCKQUOTE CLASS="quote">
+ <A HREF="#overview"><FONT SIZE=4><B>Overview</B></FONT></A><BR>
+<A HREF="#intro"><FONT SIZE=4><B>Preface</B></FONT></A><BR>
+ •<A HREF="#people">People</A><BR>
+ •<A HREF="#lists">Mailing Lists and Bug Reporting</A><BR>
+ •<A HREF="#status">Development Status</A><BR>
+ •<A HREF="#copying">Copying</A><BR>
+ •<A HREF="#ack">Acknowledgements</A><BR>
+<A HREF="#install"><FONT SIZE=4><B>Installation</B></FONT></A><BR>
+ •<A HREF="#download">Downloading Unison</A><BR>
+ •<A HREF="#afterinstall">Running Unison</A><BR>
+ •<A HREF="#upgrading">Upgrading</A><BR>
+ •<A HREF="#building">Building Unison from Scratch</A><BR>
+ <A HREF="#build-unix">Unix</A><BR>
+ <A HREF="#build-osx">Mac OS X</A><BR>
+ <A HREF="#build-win">Windows</A><BR>
+ <A HREF="#build-opts">Installation Options</A><BR>
+<A HREF="#tutorial"><FONT SIZE=4><B>Tutorial</B></FONT></A><BR>
+ •<A HREF="#prelim">Preliminaries</A><BR>
+ •<A HREF="#local">Local Usage</A><BR>
+ •<A HREF="#remote">Remote Usage</A><BR>
+ •<A HREF="#rshmeth">Remote Shell Method</A><BR>
+ •<A HREF="#socketmeth">Socket Method</A><BR>
+ •<A HREF="#usingit">Using Unison for All Your Files</A><BR>
+ •<A HREF="#usingmultiple">Using Unison to Synchronize More Than Two Machines</A><BR>
+ •<A HREF="#further">Going Further</A><BR>
+<A HREF="#basics"><FONT SIZE=4><B>Basic Concepts</B></FONT></A><BR>
+ •<A HREF="#roots">Roots</A><BR>
+ •<A HREF="#paths">Paths</A><BR>
+ •<A HREF="#updates">What is an Update?</A><BR>
+ •<A HREF="#conflicts">What is a Conflict?</A><BR>
+ •<A HREF="#recon">Reconciliation</A><BR>
+ •<A HREF="#failures">Invariants</A><BR>
+ •<A HREF="#caveats">Caveats and Shortcomings</A><BR>
+<A HREF="#reference"><FONT SIZE=4><B>Reference Guide</B></FONT></A><BR>
+ •<A HREF="#running">Running Unison</A><BR>
+ •<A HREF="#unisondir">The <TT>.unison</TT> Directory</A><BR>
+ •<A HREF="#archives">Archive Files</A><BR>
+ •<A HREF="#prefs">Preferences</A><BR>
+ •<A HREF="#profile">Profiles</A><BR>
+ •<A HREF="#profileegs">Sample Profiles</A><BR>
+ <A HREF="#minimalprofile">A Minimal Profile</A><BR>
+ <A HREF="#basicprofile">A Basic Profile</A><BR>
+ <A HREF="#powerprofile">A Power-User Profile</A><BR>
+ •<A HREF="#backups">Keeping Backups</A><BR>
+ •<A HREF="#merge">Merging Conflicting Versions</A><BR>
+ •<A HREF="#ui">The User Interface</A><BR>
+ •<A HREF="#exit">Exit code</A><BR>
+ •<A HREF="#pathspec">Path specification</A><BR>
+ •<A HREF="#ignore">Ignoring Paths</A><BR>
+ •<A HREF="#symlinks">Symbolic Links</A><BR>
+ •<A HREF="#perms">Permissions</A><BR>
+ •<A HREF="#crossplatform">Cross-Platform Synchronization</A><BR>
+ •<A HREF="#speed">Slow Links</A><BR>
+ •<A HREF="#speeding">Making Unison Faster on Large Files</A><BR>
+ •<A HREF="#fastcheck">Fast Update Detection</A><BR>
+ •<A HREF="#mountpoints">Mount Points and Removable Media</A><BR>
+ •<A HREF="#click">Click-starting Unison</A><BR>
+<A HREF="#ssh"><FONT SIZE=4><B>Installing Ssh</B></FONT></A><BR>
+ •<A HREF="#ssh-unix">Unix</A><BR>
+ •<A HREF="#ssh-win">Windows</A><BR>
+<A HREF="#news"><FONT SIZE=4><B>Changes in Version 2.40.61</B></FONT></A><BR>
+
+ </BLOCKQUOTE>
+
+<hr><!--TOC section Overview-->
+
+<H2 CLASS="section"><A NAME="overview"></A>Overview</H2><!--SEC END -->
+
+Unison is a file-synchronization tool for Unix and Windows. It allows
+two replicas of a collection of files and directories to be stored on
+different hosts (or different disks on the same host), modified
+separately, and then brought up to date by propagating the changes in
+each replica to the other.<BR>
+<BR>
+Unison
+shares a number of features with tools such as configuration
+management packages (<A HREF="http://www.cyclic.com/">CVS</A>,
+<A HREF="http://www.XCF.Berkeley.EDU/~jmacd/prcs.html">PRCS</A>,
+etc.),
+distributed filesystems
+(<A HREF="http://www.coda.cs.cmu.edu/">Coda</A>,
+etc.),
+uni-directional mirroring utilities
+(<A HREF="http://samba.anu.edu.au/rsync/">rsync</A>,
+etc.),
+and other synchronizers
+(<A HREF="http://www.pumatech.com">Intellisync</A>,
+<A HREF="http://www.merl.com/reports/TR99-14/">Reconcile</A>,
+etc).
+However, there are several points where it differs:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Unison runs on both Windows (95, 98, NT, 2k, and XP) and Unix (OSX, Solaris,
+ Linux, etc.) systems. Moreover, Unison works <EM>across</EM>
+ platforms, allowing you to synchronize a Windows laptop with a
+ Unix server, for example.
+<LI CLASS="li-itemize">Unlike a distributed filesystem, Unison is a user-level program:
+ there is no need to modify the kernel or to have
+ superuser privileges on either host.
+<LI CLASS="li-itemize">Unlike simple mirroring or backup utilities, Unison can deal
+ with updates to both replicas of a distributed directory structure.
+ Updates that do not conflict are propagated automatically.
+ Conflicting updates are detected and displayed.
+<LI CLASS="li-itemize">Unison works between any pair of machines connected to the
+ internet, communicating over either a direct socket link or
+ tunneling over an encrypted <TT>ssh</TT> connection.
+ It is careful with network bandwidth, and runs well over slow links
+ such as PPP connections. Transfers of small updates to large files are
+ optimized using a compression protocol similar to rsync.
+<LI CLASS="li-itemize">Unison has a clear and precise specification, described
+below. <LI CLASS="li-itemize">Unison is resilient to failure. It is careful to leave the
+ replicas and its own private structures in a sensible state at all
+ times, even in case of abnormal termination or communication
+ failures.
+<LI CLASS="li-itemize">Unison is free; full source code is available under the GNU
+Public License.
+</UL>
+<hr><!--TOC section Preface-->
+
+<H2 CLASS="section"><A NAME="intro"></A>Preface</H2><!--SEC END -->
+
+<!--TOC subsection People-->
+
+<H3 CLASS="subsection"><A NAME="people"></A>People</H3><!--SEC END -->
+
+<A HREF="http://www.cis.upenn.edu/~bcpierce/">Benjamin Pierce</A> leads the
+Unison project.
+The current version of Unison was designed and implemented by
+ <A HREF="http://www.research.att.com/~trevor/">Trevor Jim</A>,
+ <A HREF="http://www.cis.upenn.edu/~bcpierce/">Benjamin Pierce</A>,
+and
+ <A HREF="http://www.pps.jussieu.fr/~vouillon/">Jérôme Vouillon</A>,
+with
+ <A HREF="http://alan.petitepomme.net/">Alan Schmitt</A>,
+ Malo Denielou,
+ <A HREF="http://www.brics.dk/~zheyang/">Zhe Yang</A>,
+ Sylvain Gommier, and
+ Matthieu Goulay.
+The Mac user interface was started by Trevor Jim and enormously improved by
+Ben Willmore.
+Our implementation of the
+ <A HREF="http://samba.org/rsync/">rsync</A>
+ protocol was built by
+ <A HREF="http://www.eecs.harvard.edu/~nr/">Norman Ramsey</A>
+ and Sylvain Gommier. It is based on
+ <A HREF="http://samba.anu.edu.au/~tridge/">Andrew Tridgell</A>'s
+ <A HREF="http://samba.anu.edu.au/~tridge/phd_thesis.pdf">thesis work</A>
+ and inspired by his
+ <A HREF="http://samba.org/rsync/">rsync</A>
+ utility.
+The mirroring and merging functionality was implemented by
+ Sylvain Roy, improved by Malo Denielou, and improved yet further by
+ Stéphane Lescuyer.
+<A HREF="http://wwwfun.kurims.kyoto-u.ac.jp/~garrigue/">Jacques Garrigue</A>
+ contributed the original Gtk version of the user
+ interface; the Gtk2 version was built by Stephen Tse.
+Sundar Balasubramaniam helped build a prototype implementation of
+an earlier synchronizer in Java.
+<A HREF="http://www.cis.upenn.edu/~ishin/">Insik Shin</A>
+and
+<A HREF="http://www.cis.upenn.edu/~lee/">Insup Lee</A> contributed design
+ideas to this implementation.
+<A HREF="http://research.microsoft.com/~fournet/">Cedric Fournet</A>
+contributed to an even earlier prototype.<BR>
+<BR>
+<!--TOC subsection Mailing Lists and Bug Reporting-->
+
+<H3 CLASS="subsection"><A NAME="lists"></A>Mailing Lists and Bug Reporting</H3><!--SEC END -->
+
+<!--TOC paragraph Mailing Lists:-->
+
+<H5 CLASS="paragraph">Mailing Lists:</H5><!--SEC END -->
+
+Moderated mailing lists are available for bug reporting, announcements
+of new versions, discussions among users, and discussions among
+developers. See
+<BLOCKQUOTE CLASS="quote">
+<A HREF="http://www.cis.upenn.edu/~bcpierce/unison/lists.html"><TT>http://www.cis.upenn.edu/~bcpierce/unison/lists.html</TT></A>
+</BLOCKQUOTE>
+for more
+information.<BR>
+<BR>
+<!--TOC subsection Development Status-->
+
+<H3 CLASS="subsection"><A NAME="status"></A>Development Status</H3><!--SEC END -->
+
+Unison is no longer under active development as a research
+project. (Our research efforts are now focused on a follow-on
+project called Harmony, described at
+<A HREF="http://www.cis.upenn.edu/~bcpierce/harmony"><TT>http://www.cis.upenn.edu/~bcpierce/harmony</TT></A>.)
+At this point, there is no one whose job it is to maintain Unison,
+fix bugs, or answer questions.<BR>
+<BR>
+However, the original developers are all still using Unison daily. It
+will continue to be maintained and supported for the foreseeable future,
+and we will occasionally release new versions with bug fixes, small
+improvements, and contributed patches.<BR>
+<BR>
+Reports of bugs affecting correctness or safety are of interest to many
+people and will generally get high priority. Other bug reports will be
+looked at as time permits. Bugs should be reported to the users list at
+<A HREF="mailto:unison-users at yahoogroups.com"><TT>unison-users at yahoogroups.com</TT></A>. <BR>
+<BR>
+Feature requests are welcome, but will probably just be added to the
+ever-growing todo list. They should also be sent to <A HREF="mailto:unison-users at yahoogroups.com"><TT>unison-users at yahoogroups.com</TT></A>.<BR>
+<BR>
+Patches are even more welcome. They should be sent to
+<A HREF="mailto:unison-hackers at lists.seas.upenn.edu"><TT>unison-hackers at lists.seas.upenn.edu</TT></A>.
+(Since safety and robustness are Unison's most important properties,
+patches will be held to high standards of clear design and clean coding.)
+If you want to contribute to Unison, start by downloading the developer
+tarball from the download page. For some details on how the code is
+organized, etc., see the file <TT>CONTRIB</TT>.<BR>
+<BR>
+<!--TOC subsection Copying-->
+
+<H3 CLASS="subsection"><A NAME="copying"></A>Copying</H3><!--SEC END -->
+
+This file is part of Unison.<BR>
+<BR>
+Unison is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.<BR>
+<BR>
+Unison is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.<BR>
+<BR>
+The GNU Public License can be found at
+ <A HREF="http://www.gnu.org/licenses"><TT>http://www.gnu.org/licenses</TT></A>. A copy is also included in the
+ Unison source distribution in the file <TT>COPYING</TT>.<BR>
+<BR>
+<!--TOC subsection Acknowledgements-->
+
+<H3 CLASS="subsection"><A NAME="ack"></A>Acknowledgements</H3><!--SEC END -->
+
+Work on Unison has been supported by the National Science Foundation
+under grants CCR-9701826 and ITR-0113226, <EM>Principles and Practice of
+ Synchronization</EM>, and by University of Pennsylvania's Institute for
+Research in Cognitive Science (IRCS).<BR>
+<BR>
+<hr><!--TOC section Installation-->
+
+<H2 CLASS="section"><A NAME="install"></A>Installation</H2><!--SEC END -->
+
+Unison is designed to be easy to install. The following sequence of
+steps should get you a fully working installation in a few minutes. If
+you run into trouble, you may find the suggestions on the
+<A HREF="http://www.cis.upenn.edu/~bcpierce/unison/faq.html">Frequently Asked
+Questions page</A> helpful. Pre-built binaries are available for a
+variety of platforms.<BR>
+<BR>
+Unison can be used with either of two user interfaces:
+<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
+a simple textual interface, suitable for dumb terminals (and
+running from scripts), and
+<LI CLASS="li-enumerate">a more sophisticated grapical interface, based on Gtk2 (on
+ Linux/Windows) or the native UI framework (on OSX).
+</OL>
+You will need to install a copy of Unison on every machine that you
+want to synchronize. However, you only need the version with a
+graphical user interface (if you want a GUI at all) on the machine
+where you're actually going to display the interface (the <EM>client</EM>
+machine). Other machines that you synchronize with can get along just
+fine with the textual version.<BR>
+<BR>
+<!--TOC subsection Downloading Unison-->
+
+<H3 CLASS="subsection"><A NAME="download"></A>Downloading Unison</H3><!--SEC END -->
+
+The Unison download site lives under
+<A HREF="http://www.cis.upenn.edu/~bcpierce/unison"><TT>http://www.cis.upenn.edu/~bcpierce/unison</TT></A>.<BR>
+<BR>
+If a pre-built binary of Unison is available for the client machine's
+architecture, just download it and put it somewhere in your search
+path (if you're going to invoke it from the command line) or on your
+desktop (if you'll be click-starting it).<BR>
+<BR>
+The executable file for the graphical version (with a name including
+<CODE>gtkui</CODE>) actually provides <EM>both</EM> interfaces: the graphical one
+appears by default, while the textual interface can be selected by including
+<CODE>-ui text</CODE> on the command line. The <CODE>textui</CODE> executable
+provides just the textual interface.<BR>
+<BR>
+If you don't see a pre-built executable for your architecture, you'll
+need to build it yourself. See the <A HREF="#building">Building Unison</A> section.
+There are also a small number of contributed ports to other
+architectures that are not maintained by us. See the
+<A HREF="http://www.cis.upenn.edu/~bcpierce/unison/download.html">Contributed
+Ports page</A> to check what's available.<BR>
+<BR>
+Check to make sure that what you have downloaded is really executable.
+Either click-start it, or type <FONT SIZE=4><TT>unison -version</TT></FONT> at the command
+line. <BR>
+<BR>
+Unison can be used in three different modes: with different directories on a
+single machine, with a remote machine over a direct socket connection, or
+with a remote machine using <TT>ssh</TT> for authentication and secure
+transfer. If you intend to use the last option, you may need to install
+<TT>ssh</TT>; see the <A HREF="#ssh">Installing Ssh</A> section.<BR>
+<BR>
+<!--TOC subsection Running Unison-->
+
+<H3 CLASS="subsection"><A NAME="afterinstall"></A>Running Unison</H3><!--SEC END -->
+
+Once you've got Unison installed on at least one system, read
+the <A HREF="#tutorial">Tutorial</A> section of the user manual (or type <FONT SIZE=4><TT>unison -doc
+ tutorial</TT></FONT>) for instructions on how to get started.<BR>
+<BR>
+<!--TOC subsection Upgrading-->
+
+<H3 CLASS="subsection"><A NAME="upgrading"></A>Upgrading</H3><!--SEC END -->
+
+Upgrading to a new version of Unison is as simple as throwing away the old
+binary and installing the new one.<BR>
+<BR>
+Before upgrading, it is a good idea to run the <EM>old</EM> version one last
+time, to make sure all your replicas are completely synchronized. A new
+version of Unison will sometimes introduce a different format for the
+archive files used to remember information about the previous state of the
+replicas. In this case, the old archive will be ignored (not deleted — if
+you roll back to the previous version of Unison, you will find the old
+archives intact), which means that any differences between the replicas will
+show up as conflicts that need to be resolved manually.<BR>
+<BR>
+<!--TOC subsection Building Unison from Scratch-->
+
+<H3 CLASS="subsection"><A NAME="building"></A>Building Unison from Scratch</H3><!--SEC END -->
+
+If a pre-built image is not available, you will need to compile it from
+scratch; the sources are available from the same place as the binaries.<BR>
+<BR>
+In principle, Unison should work on any platform to which OCaml has been
+ported and on which the <CODE>Unix</CODE> module is fully implemented. It has
+been tested on many flavors of Windows (98, NT, 2000, XP) and Unix (OS X,
+Solaris, Linux, FreeBSD), and on both 32- and 64-bit architectures.<BR>
+<BR>
+<!--TOC subsubsection Unix-->
+
+<H4 CLASS="subsubsection"><A NAME="build-unix"></A>Unix</H4><!--SEC END -->
+
+You'll need the Objective Caml compiler (version 3.11.2 or later), which is
+available from <A HREF="http://caml.inria.fr"><TT>http://caml.inria.fr</TT></A>. Building and installing OCaml
+on Unix systems is very straightforward; just follow the instructions in the
+distribution. You'll probably want to build the native-code compiler in
+addition to the bytecode compiler, as Unison runs much faster when compiled
+to native code, but this is not absolutely necessary.
+(Quick start: on many systems, the following sequence of commands will
+get you a working and installed compiler: first do <TT>make world opt</TT>,
+then <TT>su</TT> to root and do <TT>make install</TT>.)<BR>
+<BR>
+You'll also need the GNU <TT>make</TT> utility, standard on many Unix
+systems. (Type <FONT SIZE=4><TT>make –version</TT></FONT> to check that you've got the
+GNU version.)<BR>
+<BR>
+Once you've got OCaml installed, grab a copy of the Unison sources,
+unzip and untar them, change to the new <FONT SIZE=4><TT>unison</TT></FONT> directory, and
+type “<TT>make UISTYLE=text</TT>.”
+The result should be an executable file called <FONT SIZE=4><TT>unison</TT></FONT>.
+Type <FONT SIZE=4><TT>./unison</TT></FONT> to make sure the program is executable. You
+should get back a usage message.<BR>
+<BR>
+If you want to build the graphical user interface, you will need to install
+two additional things:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+The Gtk2 libraries. These areavailable from
+ <A HREF="http://www.gtk.org"><TT>http://www.gtk.org</TT></A> and are standard on many Unix installations. <BR>
+<BR>
+<LI CLASS="li-itemize">The <TT>lablgtk2</TT> OCaml library. Grab the
+ developers' tarball from
+ <BLOCKQUOTE CLASS="quote">
+ <A HREF="http://wwwfun.kurims.kyoto-u.ac.jp/soft/olabl/lablgtk.html"><TT>http://wwwfun.kurims.kyoto-u.ac.jp/soft/olabl/lablgtk.html</TT></A>,
+ </BLOCKQUOTE>
+ untar it, and follow the instructions to build and install it.<BR>
+<BR>
+(Quick start: <TT>make configure</TT>, then <TT>make</TT>, then <TT>make
+ opt</TT>, then <TT>su</TT> and <TT>make install</TT>.)
+</UL>
+Now build unison. If your search paths are set up correctly, simply typing
+<TT>make</TT>
+again should build a <CODE>unison</CODE> executable with a Gtk2 graphical
+interface. (In previous releases of Unison, it was necessary to add <TT>UISTYLE=gtk2</TT> to the 'make' command above. This requirement has been
+removed: the makefile should detect automatically when lablgtk2 is
+present and set this flag automatically.) <BR>
+<BR>
+Put the <CODE>unison</CODE> executable somewhere in your search path, either
+by adding the Unison directory to your PATH variable or by copying the
+executable to some standard directory where executables are stored.<BR>
+<BR>
+<!--TOC subsubsection Mac OS X-->
+
+<H4 CLASS="subsubsection"><A NAME="build-osx"></A>Mac OS X</H4><!--SEC END -->
+
+To build the text-only user interface, follow the instructions above for
+building on Unix systems. You should do this first, even if you are also
+planning on building the GUI, just to make sure it works.<BR>
+<BR>
+To build the basic GUI version, you'll first need to download and install
+the XCode developer tools from Apple. Once this is done, just type <TT>make UISTYLE=macnew</TT> in the <TT>src</TT> directory, and if things go well you
+should get an application that you can move from <TT>uimacnew/build/Default/Unison.app</TT> to wherever you want it.<BR>
+<BR>
+There is also an experimental GUI with a somewhat smoother look and feel.
+To compile this one (once you've got the basic one working), proceed as
+follows:
+<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
+Go to the <TT>uimacnew09</TT> directory and double-click the file <TT>BWToolkit.ibplugin</TT>.
+<LI CLASS="li-enumerate">Go back up to the <TT>src</TT> directory and type <TT>make
+ UISTYLE=macnew09</TT>.
+<LI CLASS="li-enumerate">You should get an application built for you at <TT>uimacnew09/build/Default/Unison.app</TT>.
+</OL>
+<!--TOC subsubsection Windows-->
+
+<H4 CLASS="subsubsection"><A NAME="build-win"></A>Windows</H4><!--SEC END -->
+
+Although the binary distribution should work on any version of Windows,
+some people may want to build Unison from scratch on those systems too.<BR>
+<BR>
+<!--TOC paragraph Bytecode version:-->
+
+<H5 CLASS="paragraph">Bytecode version:</H5><!--SEC END -->
+ The simpler but slower compilation option
+to build a Unison executable is to build a bytecode version. You need
+first install Windows version of the OCaml compiler (version 3.07 or
+later, available from <A HREF="http://caml.inria.fr"><TT>http://caml.inria.fr</TT></A>). Then grab a copy
+of Unison sources and type
+<PRE CLASS="verbatim">
+ make NATIVE=false
+</PRE>to compile the bytecode. The result should be an executable file called
+<CODE>unison.exe</CODE>. <BR>
+<BR>
+<!--TOC paragraph Native version:-->
+
+<H5 CLASS="paragraph">Native version:</H5><!--SEC END -->
+ Building a more efficient, native version of
+Unison on Windows requires a little more work. See the file <TT>INSTALL.win32</TT> in the source code distribution.<BR>
+<BR>
+<!--TOC subsubsection Installation Options-->
+
+<H4 CLASS="subsubsection"><A NAME="build-opts"></A>Installation Options</H4><!--SEC END -->
+
+The <CODE>Makefile</CODE> in the distribution includes several switches that
+can be used to control how Unison is built. Here are the most useful
+ones:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Building with <CODE>NATIVE=true</CODE> uses the native-code OCaml
+compiler, yielding an executable that will run quite a bit faster. We use
+this for building distribution versions.
+<LI CLASS="li-itemize">Building with <CODE>make DEBUGGING=true</CODE> generates debugging
+symbols.
+<LI CLASS="li-itemize">Building with <CODE>make STATIC=true</CODE> generates a (mostly)
+statically linked executable. We use this for building distribution
+versions, for portability.
+</UL>
+
+<hr><!--TOC section Tutorial-->
+
+<H2 CLASS="section"><A NAME="tutorial"></A>Tutorial</H2><!--SEC END -->
+
+<!--TOC subsection Preliminaries-->
+
+<H3 CLASS="subsection"><A NAME="prelim"></A>Preliminaries</H3><!--SEC END -->
+
+Unison can be used with either of two user interfaces:
+<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
+a straightforward textual interface and
+<LI CLASS="li-enumerate">a more sophisticated graphical interface
+</OL>
+The textual interface is more convenient for running from scripts and
+works on dumb terminals; the graphical interface is better for most
+interactive use. For this tutorial, you can use either. If you are running
+Unison from the command line, just typing <TT>unison</TT>
+will select either the text or the graphical interface, depending on which
+has been selected as default when the executable you are running was
+built. You can force the text interface even if graphical is the default by
+adding <TT>-ui text</TT>.
+The other command-line arguments to both versions are identical. <BR>
+<BR>
+The graphical version can also be run directly by clicking on its icon, but
+this may require a little set-up (see the <A HREF="#click">Click-starting
+ Unison</A> section). For this tutorial, we assume that you're starting it from the
+command line.<BR>
+<BR>
+Unison can synchronize files and directories on a single machine, or
+between two machines on a network. (The same program runs on both
+machines; the only difference is which one is responsible for
+displaying the user interface.) If you're only interested in a
+single-machine setup, then let's call that machine the <EM>client</EM>. If
+you're synchronizing two machines, let's call them <EM>client</EM> and
+<EM>server</EM>.<BR>
+<BR>
+<!--TOC subsection Local Usage-->
+
+<H3 CLASS="subsection"><A NAME="local"></A>Local Usage</H3><!--SEC END -->
+
+Let's get the client machine set up first and see how to synchronize
+two directories on a single machine.<BR>
+<BR>
+Follow the instructions in the <A HREF="#install">Installation</A> section to either
+download or build an executable version of Unison, and install it
+somewhere on your search path. (If you just want to use the textual user
+interface, download the appropriate textui binary. If you just want to
+the graphical interface—or if you will use both interfaces [the gtkui
+binary actually has both compiled in]—then download the gtkui binary.)<BR>
+<BR>
+Create a small test directory <TT>a.tmp</TT> containing a couple of files
+and/or subdirectories, e.g.,
+<PRE CLASS="verbatim">
+ mkdir a.tmp
+ touch a.tmp/a a.tmp/b
+ mkdir a.tmp/d
+ touch a.tmp/d/f
+</PRE>Copy this directory to b.tmp:
+<PRE CLASS="verbatim">
+ cp -r a.tmp b.tmp
+</PRE>
+Now try synchronizing <TT>a.tmp</TT> and <TT>b.tmp</TT>. (Since they are
+identical, synchronizing them won't propagate any changes, but Unison
+will remember the current state of both directories so that it will be
+able to tell next time what has changed.) Type:
+<PRE CLASS="verbatim">
+ unison a.tmp b.tmp
+</PRE>(You may need to add <CODE>-ui text</CODE>, depending how your unison binary was built.)<BR>
+<BR>
+<BR>
+<EM>Textual Interface:</EM><UL CLASS="itemize"><LI CLASS="li-itemize">
+
+You should see a message notifying you that all the files are actually
+equal and then get returned to the command line.
+</UL>
+<BR>
+<EM>Graphical Interface:</EM><UL CLASS="itemize"><LI CLASS="li-itemize">
+
+You should get a big empty window with a message at the bottom
+notifying you that all files are identical. Choose the Exit item from
+the File menu to get back to the command line.
+</UL>
+Next, make some changes in a.tmp and/or b.tmp. For example:
+<PRE CLASS="verbatim">
+ rm a.tmp/a
+ echo "Hello" > a.tmp/b
+ echo "Hello" > b.tmp/b
+ date > b.tmp/c
+ echo "Hi there" > a.tmp/d/h
+ echo "Hello there" > b.tmp/d/h
+</PRE>Run Unison again:
+<PRE CLASS="verbatim">
+ unison a.tmp b.tmp
+</PRE>
+This time, the user interface will display only the files that have
+changed. If a file has been modified in just one
+replica, then it will be displayed with an arrow indicating the
+direction that the change needs to be propagated. For example,
+<PRE CLASS="verbatim">
+ <--- new file c [f]
+</PRE>indicates that the file <TT>c</TT> has been modified only in the second
+replica, and that the default action is therefore to propagate the new
+version to the first replica. To <B>f</B>ollow Unison's recommendation,
+press the “f” at the prompt.<BR>
+<BR>
+If both replicas are modified and their contents are different, then
+the changes are in conflict: <TT><-?-></TT> is displayed to indicate
+that Unison needs guidance on which replica should override the
+other.
+<PRE CLASS="verbatim">
+ new file <-?-> new file d/h []
+</PRE>By default, neither version will be propagated and both
+replicas will remain as they are. <BR>
+<BR>
+If both replicas have been modified but their new contents are the same
+(as with the file <TT>b</TT>), then no propagation is necessary and
+nothing is shown. Unison simply notes that the file is up to date.<BR>
+<BR>
+These display conventions are used by both versions of the user
+interface. The only difference lies in the way in which Unison's
+default actions are either accepted or overridden by the user.<BR>
+<BR>
+<BR>
+<EM>Textual Interface:</EM><UL CLASS="itemize"><LI CLASS="li-itemize">
+
+The status of each modified file is displayed, in turn.
+When the copies of a file in the two replicas are not identical, the
+user interface will ask for instructions as to how to propagate the
+change. If some default action is indicated (by an arrow), you can
+simply press Return to go on to the next changed file. If you want to
+do something different with this file, press “<CODE><</CODE>” or “<CODE>></CODE>” to force
+the change to be propagated from right to left or from left to right,
+or else press “<CODE>/</CODE>” to skip this file and leave both replicas alone.
+When it reaches the end of the list of modified files, Unison will ask
+you one more time whether it should proceed with the updates that have
+been selected.<BR>
+<BR>
+When Unison stops to wait for input from the user, pressing “<CODE>?</CODE>”
+will always give a list of possible responses and their meanings.
+</UL>
+<BR>
+<EM>Graphical Interface:</EM><UL CLASS="itemize"><LI CLASS="li-itemize">
+
+The main window shows all the files that have been modified in either
+<TT>a.tmp</TT> or <TT>b.tmp</TT>. To override a default action (or to select
+an action in the case when there is no default), first select the file, either
+by clicking on its name or by using the up- and down-arrow keys. Then
+press either the left-arrow or “<CODE><</CODE>” key (to cause the version in b.tmp to
+propagate to a.tmp) or the right-arrow or “<CODE>></CODE>” key (which makes the a.tmp
+version override b.tmp). <BR>
+<BR>
+Every keyboard command can also be invoked from the menus at the top
+of the user interface. (Conversely, each menu item is annotated with
+its keyboard equivalent, if it has one.)<BR>
+<BR>
+When you are satisfied with the directions for the propagation of changes
+as shown in the main window, click the “Go” button to set them in
+motion. A check sign will be displayed next to each filename
+when the file has been dealt with.
+</UL>
+<!--TOC subsection Remote Usage-->
+
+<H3 CLASS="subsection"><A NAME="remote"></A>Remote Usage</H3><!--SEC END -->
+
+Next, we'll get Unison set up to synchronize replicas on two different
+machines.<BR>
+<BR>
+Follow the instructions in the Installation section to download or
+build an executable version of Unison on the server machine, and
+install it somewhere on your search path. (It doesn't matter whether
+you install the textual or graphical version, since the copy of Unison on
+the server doesn't need to display any user interface at all.) <BR>
+<BR>
+It is important that the version of Unison installed on the server
+machine is the same as the version of Unison on the client machine.
+But some flexibility on the version of Unison at the client side can
+be achieved by using the <CODE>-addversionno</CODE> option; see
+the <A HREF="#prefs">Preferences</A> section.<BR>
+<BR>
+Now there is a decision to be made. Unison provides two methods for
+communicating between the client and the server:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+<EM>Remote shell method</EM>: To use this method, you must have
+ some way of invoking remote commands on the server from the client's
+ command line, using a facility such as <CODE>ssh</CODE>.
+ This method is more convenient (since there is no need to manually
+ start a “unison server” process on the server) and also more
+ secure (especially if you use <CODE>ssh</CODE>).<BR>
+<BR>
+<LI CLASS="li-itemize"><EM>Socket method</EM>: This method requires only that you can get
+ TCP packets from the client to the server and back. A draconian
+ firewall can prevent this, but otherwise it should work anywhere.
+</UL>
+Decide which of these you want to try, and continue with
+the <A HREF="#rshmeth">Remote Shell Method</A> section or
+the <A HREF="#socketmeth">Socket Method</A> section, as appropriate.<BR>
+<BR>
+<!--TOC subsection Remote Shell Method-->
+
+<H3 CLASS="subsection"><A NAME="rshmeth"></A>Remote Shell Method</H3><!--SEC END -->
+
+The standard remote shell facility on Unix systems is <CODE>ssh</CODE>, which provides the
+same functionality as the older <CODE>rsh</CODE> but much better security. Ssh is available from
+<A HREF="ftp://ftp.cs.hut.fi/pub/ssh/"><TT>ftp://ftp.cs.hut.fi/pub/ssh/</TT></A>; up-to-date binaries for some
+architectures can also be found at
+<A HREF="ftp://ftp.faqs.org/ssh/contrib"><TT>ftp://ftp.faqs.org/ssh/contrib</TT></A>. See section <A HREF="#ssh-win">A.2</A>
+for installation instructions for the Windows version.<BR>
+<BR>
+Running
+<CODE>ssh</CODE> requires some coordination between the client and server
+machines to establish that the client is allowed to invoke commands on
+the server; please refer to the <CODE>ssh</CODE> documentation
+for information on how to set this up. The examples in this section
+use <CODE>ssh</CODE>, but you can substitute <CODE>rsh</CODE> for <CODE>ssh</CODE> if
+you wish.<BR>
+<BR>
+First, test that we can invoke Unison on the server from the client.
+Typing
+<PRE>
+ ssh <I>remotehostname</I> unison -version
+</PRE>
+should print the same version information as running
+<PRE CLASS="verbatim">
+ unison -version
+</PRE>locally on the client. If remote execution fails, then either
+something is wrong with your ssh setup (e.g., “permission denied”)
+or else the search path that's being used when executing commands on
+the server doesn't contain the <CODE>unison</CODE> executable (e.g.,
+“command not found”).<BR>
+<BR>
+Create a test directory <TT>a.tmp</TT> in your home directory on the client
+machine. <BR>
+<BR>
+Test that the local unison client can start and connect to the
+remote server. Type
+<PRE>
+ unison -testServer a.tmp ssh://<I>remotehostname</I>/a.tmp
+</PRE>
+Now cd to your home directory and type:
+<PRE CLASS="verbatim">
+ unison a.tmp ssh://remotehostname/a.tmp
+</PRE>The result should be that the entire directory <TT>a.tmp</TT> is propagated
+from the client to your home directory on the server.<BR>
+<BR>
+After finishing the first synchronization, change a few files and try
+synchronizing again. You should see similar results as in the local
+case.<BR>
+<BR>
+If your user name on the server is not the same as on the client, you
+need to specify it on the command line:
+<PRE CLASS="verbatim">
+ unison a.tmp ssh://username@remotehostname/a.tmp
+</PRE>
+<I>Notes:</I>
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+If you want to put <CODE>a.tmp</CODE> some place other than your home
+directory on the remote host, you can give an absolute path for it by
+adding an extra slash between <CODE>remotehostname</CODE> and the beginning
+of the path:
+<PRE CLASS="verbatim">
+ unison a.tmp ssh://remotehostname//absolute/path/to/a.tmp
+</PRE><BR>
+<BR>
+<LI CLASS="li-itemize">You can give an explicit path for the <CODE>unison</CODE> executable
+ on the server by using the command-line option <FONT SIZE=4><TT>-servercmd
+ /full/path/name/of/unison</TT></FONT> or adding
+ <FONT SIZE=4><TT>servercmd=/full/path/name/of/unison</TT></FONT> to your profile (see
+ the <A HREF="#profile">Profile</A> section). Similarly, you can specify a
+ explicit path for the <CODE>ssh</CODE> program using the <FONT SIZE=4><TT>-sshcmd</TT></FONT>
+ option.
+ Extra arguments can be passed to <CODE>ssh</CODE> by setting the
+ <CODE>-sshargs</CODE> preference.
+</UL>
+<!--TOC subsection Socket Method-->
+
+<H3 CLASS="subsection"><A NAME="socketmeth"></A>Socket Method</H3><!--SEC END -->
+
+<BLOCKQUOTE CLASS="quote">
+ <B><FONT COLOR=red>Warning:</FONT></B> The socket method is
+ insecure: not only are the texts of your changes transmitted over
+ the network in unprotected form, it is also possible for anyone in
+ the world to connect to the server process and read out the contents
+ of your filesystem! (Of course, to do this they must understand the
+ protocol that Unison uses to communicate between client and server,
+ but all they need for this is a copy of the Unison sources.) The socket
+ method is provided only for expert users with specific needs; everyone
+ else should use the <CODE>ssh</CODE> method.
+</BLOCKQUOTE>
+To run Unison over a socket connection, you must start a Unison
+daemon process on the server. This process runs continuously,
+waiting for connections over a given socket from client machines
+running Unison and processing their requests in turn.<BR>
+<BR>
+To start the daemon, type
+<PRE CLASS="verbatim">
+ unison -socket NNNN
+</PRE>on the server machine, where <TT>NNNN</TT> is the socket number that the
+daemon should listen on for connections from clients. (<TT>NNNN</TT> can
+be any large number that is not being used by some other program; if
+<TT>NNNN</TT> is already in use, Unison will exit with an error
+message.) Note that paths specified by the client will be interpreted
+relative to the directory in which you start the server process; this
+behavior is different from the ssh case, where the path is relative to
+your home directory on the server.<BR>
+<BR>
+Create a test directory <TT>a.tmp</TT> in your home directory on the
+client machine. Now type:
+<PRE>
+ unison a.tmp socket://<I>remotehostname</I>:NNNN/a.tmp
+</PRE>
+The result should be that the entire directory <TT>a.tmp</TT> is
+propagated from the client to the server (<TT>a.tmp</TT> will be
+created on the server in the directory that the server was started
+from).
+After finishing the first synchronization, change a few files and try
+synchronizing again. You should see similar results as in the local
+case.<BR>
+<BR>
+Since the socket method is not used by many people, its functionality is
+rather limited. For example, the server can only deal with one client at a
+time. <BR>
+<BR>
+<!--TOC subsection Using Unison for All Your Files-->
+
+<H3 CLASS="subsection"><A NAME="usingit"></A>Using Unison for All Your Files</H3><!--SEC END -->
+
+Once you are comfortable with the basic operation of Unison, you may
+find yourself wanting to use it regularly to synchronize your commonly
+used files. There are several possible ways of going about this:
+<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
+Synchronize your whole home directory, using the Ignore facility
+(see the <A HREF="#ignore">Ignore</A> section)
+to avoid synchronizing temporary files and things that only belong on
+one host.
+<LI CLASS="li-enumerate">Create a subdirectory called <TT>shared</TT> (or <TT>current</TT>, or
+whatever) in your home directory on each host, and put all the files
+you want to synchronize into this directory.
+<LI CLASS="li-enumerate">Create a subdirectory called <TT>shared</TT> (or <TT>current</TT>, or
+whatever) in your home directory on each host, and put <EM>links to</EM>
+all the files you want to synchronize into this directory. Use the
+<TT>follow</TT> preference (see the <A HREF="#symlinks">Symbolic Links</A> section) to make
+Unison treat these links as transparent.
+<LI CLASS="li-enumerate">Make your home directory the root of the synchronization, but
+tell Unison to synchronize only some of the files and subdirectories
+within it on any given run. This can be accomplished by using the <TT>-path</TT> switch
+on the command line:
+<PRE>
+ unison /home/<I>username</I> ssh://<I>remotehost</I>//home/<I>username</I> -path shared
+</PRE>
+The <TT>-path</TT> option can be used as many times as needed, to
+synchronize several files or subdirectories:
+<PRE>
+ unison /home/<I>username</I> ssh://<I>remotehost</I>//home/<I>username</I> <CODE>\</CODE>
+ -path shared <CODE>\</CODE>
+ -path pub <CODE>\</CODE>
+ -path .netscape/bookmarks.html
+</PRE>
+These <CODE>-path</CODE> arguments can also be put in your preference file.
+See the <A HREF="#prefs">Preferences</A> section for an example.
+</OL>
+Most people find that they only need to maintain a profile (or
+profiles) on one of the hosts that they synchronize, since Unison is
+always initiated from this host. (For example, if you're
+synchronizing a laptop with a fileserver, you'll probably always run
+Unison on the laptop.) This is a bit different from the usual
+situation with asymmetric mirroring programs like <CODE>rdist</CODE>, where
+the mirroring operation typically needs to be initiated from the
+machine with the most recent changes. the <A HREF="#profile">Profile</A> section
+covers the syntax of Unison profiles, together with some sample profiles.<BR>
+<BR>
+Some tips on improving Unison's performance can be found on the
+<A HREF="http://www.cis.upenn.edu/~bcpierce/unison/faq.html">Frequently
+ Asked Questions page</A>.<BR>
+<BR>
+<!--TOC subsection Using Unison to Synchronize More Than Two Machines-->
+
+<H3 CLASS="subsection"><A NAME="usingmultiple"></A>Using Unison to Synchronize More Than Two Machines</H3><!--SEC END -->
+
+Unison is designed for synchronizing pairs of replicas. However, it is
+possible to use it to keep larger groups of machines in sync by performing
+multiple pairwise synchronizations. <BR>
+<BR>
+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.<BR>
+<BR>
+<!--TOC subsection Going Further-->
+
+<H3 CLASS="subsection"><A NAME="further"></A>Going Further</H3><!--SEC END -->
+
+On-line documentation for the various features of Unison
+can be obtained either by typing
+<PRE CLASS="verbatim">
+ unison -doc topics
+</PRE>at the command line, or by selecting the Help menu in the graphical
+user interface.
+The on-line information and the printed manual are essentially identical.
+<BR>
+<BR>
+If you use Unison regularly, you should subscribe to one of the mailing
+lists, to receive announcements of new versions. See
+the <A HREF="#lists">Mailing Lists</A> section. <BR>
+<BR>
+<hr><!--TOC section Basic Concepts-->
+
+<H2 CLASS="section"><A NAME="basics"></A>Basic Concepts</H2><!--SEC END -->
+
+To understand how Unison works, it is necessary to discuss a few
+straightforward concepts.
+These concepts are developed more rigorously and at more length in a number
+of papers, available at <A HREF="http://www.cis.upenn.edu/~bcpierce/papers"><TT>http://www.cis.upenn.edu/~bcpierce/papers</TT></A>.
+But the informal presentation here should be enough for most users.<BR>
+<BR>
+<!--TOC subsection Roots-->
+
+<H3 CLASS="subsection"><A NAME="roots"></A>Roots</H3><!--SEC END -->
+
+A replica's <EM>root</EM> tells Unison where to find a set of files to be
+synchronized, either on the local machine or on a remote host.
+For example,
+<PRE>
+ <I>relative/path/of/root</I>
+</PRE>
+specifies a local root relative to the directory where Unison is
+started, while
+<PRE>
+ /<I>absolute/path/of/root</I>
+</PRE>
+specifies a root relative to the top of the local filesystem,
+independent of where Unison is running. Remote roots can begin with
+<CODE>ssh://</CODE>,
+<CODE>rsh://</CODE>
+to indicate that the remote server should be started with rsh or ssh:
+<PRE>
+ ssh://<I>remotehost</I>//<I>absolute/path/of/root</I>
+ rsh://<I>user</I>@<I>remotehost</I>/<I>relative/path/of/root</I>
+</PRE>
+If the remote server is already running (in the socket mode), then the syntax
+<PRE>
+ socket://<I>remotehost</I>:<I>portnum</I>//<I>absolute/path/of/root</I>
+ socket://<I>remotehost</I>:<I>portnum</I>/<I>relative/path/of/root</I>
+</PRE>
+is used to specify the hostname and the port that the client Unison should
+use to contact it.<BR>
+<BR>
+The syntax for roots is based on that of URIs (described in RFC 2396).
+The full grammar is:
+<PRE>
+ <I>replica</I> ::= [<I>protocol</I>:]//[<I>user</I>@][<I>host</I>][:<I>port</I>][/<I>path</I>]
+ | <I>path</I>
+
+ <I>protocol</I> ::= file
+ | socket
+ | ssh
+ | rsh
+
+ <I>user</I> ::= [-_a-zA-Z0-9]+
+
+ <I>host</I> ::= [-_a-zA-Z0-9.]+
+
+ <I>port</I> ::= [0-9]+
+</PRE>
+When <CODE>path</CODE> is given without any protocol prefix, the protocol is
+assumed to be <CODE>file:</CODE>. Under Windows, it is possible to
+synchronize with a remote directory using the <CODE>file:</CODE> protocol over
+the Windows Network Neighborhood. For example,
+<PRE CLASS="verbatim">
+ unison foo //host/drive/bar
+</PRE>synchronizes the local directory <CODE>foo</CODE> with the directory
+<CODE>drive:\bar</CODE> on the machine <CODE>host</CODE>, provided that <CODE>host</CODE>
+is accessible via Network Neighborhood. When the <CODE>file:</CODE> protocol
+is used in this way, there is no need for a Unison server to be running
+on the remote host. However, running Unison this way is only a good
+idea if the remote host is reached by a very fast network connection,
+since the full contents of every file in the remote replica will have to
+be transferred to the local machine to detect updates.<BR>
+<BR>
+The names of roots are <EM>canonized</EM> by Unison before it uses them
+to compute the names of the corresponding archive files, so <TT>//saul//home/bcpierce/common</TT> and <TT>//saul.cis.upenn.edu/common</TT>
+will be recognized as the same replica under different names.<BR>
+<BR>
+<!--TOC subsection Paths-->
+
+<H3 CLASS="subsection"><A NAME="paths"></A>Paths</H3><!--SEC END -->
+
+A <EM>path</EM> refers to a point <EM>within</EM> a set of files being
+synchronized; it is specified relative to the root of the replica.<BR>
+<BR>
+Formally, a path is just a sequence of names, separated by <CODE>/</CODE>.
+Note that the path separator character is always a forward slash, no
+matter what operating system Unison is running on. Forward slashes
+are converted to backslashes as necessary when paths are converted to
+filenames in the local filesystem on a particular host.
+(For example, suppose that we run Unison on a Windows system, synchronizing
+the local root <CODE>c:\pierce</CODE> with the root
+<CODE>ssh://saul.cis.upenn.edu/home/bcpierce</CODE> on a Unix server. Then
+the path <CODE>current/todo.txt</CODE> refers to the file
+<CODE>c:\pierce\current\todo.txt</CODE> on the client and
+<CODE>/home/bcpierce/current/todo.txt</CODE> on the server.)<BR>
+<BR>
+The empty path (i.e., the empty sequence of names) denotes the whole
+replica. Unison displays the empty path as “<CODE>[root]</CODE>.”<BR>
+<BR>
+If <CODE>p</CODE> is a path and <CODE>q</CODE> is a path beginning with <CODE>p</CODE>, then
+<CODE>q</CODE> is said to be a <EM>descendant</EM> of <CODE>p</CODE>. (Each path is also a
+descendant of itself.)<BR>
+<BR>
+<!--TOC subsection What is an Update?-->
+
+<H3 CLASS="subsection"><A NAME="updates"></A>What is an Update?</H3><!--SEC END -->
+
+The <EM>contents</EM> of a path <CODE>p</CODE> in a particular replica could be a
+file, a directory, a symbolic link, or absent (if <CODE>p</CODE> does not
+refer to anything at all in that replica). More specifically:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+If <CODE>p</CODE> refers to an ordinary file, then the
+contents of <CODE>p</CODE> are the actual contents of this file (a string of bytes)
+plus the current permission bits of the file.
+<LI CLASS="li-itemize">If <CODE>p</CODE> refers to a symbolic link, then the contents of <CODE>p</CODE>
+are just the string specifying where the link points.
+<LI CLASS="li-itemize">If <CODE>p</CODE> refers to a directory, then the
+contents of <CODE>p</CODE> are just the token “DIRECTORY” plus the current
+permission bits of the directory.
+<LI CLASS="li-itemize">If <CODE>p</CODE> does not refer to anything in this replica, then the
+contents of <CODE>p</CODE> are the token “ABSENT.”
+</UL>
+Unison keeps a record of the contents of each path after each
+successful synchronization of that path (i.e., it remembers the
+contents at the last moment when they were the same in the two
+replicas). <BR>
+<BR>
+We say that a path is <EM>updated</EM> (in some replica) if its current
+contents are different from its contents the last time it was successfully
+synchronized. Note that whether a path is updated has nothing to do with
+its last modification time—Unison considers only the contents when
+determining whether an update has occurred. This means that touching a file
+without changing its contents will <EM>not</EM> be recognized as an update. A
+file can even be changed several times and then changed back to its original
+contents; as long as Unison is only run at the end of this process, no
+update will be recognized.<BR>
+<BR>
+What Unison actually calculates is a close approximation to this
+definition; see the <A HREF="#caveats">Caveats and Shortcomings</A> section.<BR>
+<BR>
+<!--TOC subsection What is a Conflict?-->
+
+<H3 CLASS="subsection"><A NAME="conflicts"></A>What is a Conflict?</H3><!--SEC END -->
+
+A path is said to be <EM>conflicting</EM> if the following conditions all hold:
+<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
+it has been updated in one replica,
+<LI CLASS="li-enumerate">it or any of its descendants has been updated in the other
+ replica,
+and
+<LI CLASS="li-enumerate">its contents in the two replicas are not identical.
+</OL>
+<!--TOC subsection Reconciliation-->
+
+<H3 CLASS="subsection"><A NAME="recon"></A>Reconciliation</H3><!--SEC END -->
+
+Unison operates in several distinct stages:
+<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
+On each host, it compares its archive file (which records
+the state of each path in the replica when it was last synchronized)
+with the current contents of the replica, to determine which paths
+have been updated.
+<LI CLASS="li-enumerate">It checks for “false conflicts” — paths that have been
+updated on both replicas, but whose current values are identical.
+These paths are silently marked as synchronized in the archive files
+in both replicas.
+<LI CLASS="li-enumerate">It displays all the updated paths to the user. For updates that
+do not conflict, it suggests a default action (propagating the new
+contents from the updated replica to the other). Conflicting updates
+are just displayed. The user is given an opportunity to examine the
+current state of affairs, change the default actions for
+nonconflicting updates, and choose actions for conflicting updates.
+<LI CLASS="li-enumerate">It performs the selected actions, one at a time. Each action is
+performed by first transferring the new contents to a temporary file
+on the receiving host, then atomically moving them into place.
+<LI CLASS="li-enumerate">It updates its archive files to reflect the new state of the
+replicas.
+</OL>
+<!--TOC subsection Invariants-->
+
+<H3 CLASS="subsection"><A NAME="failures"></A>Invariants</H3><!--SEC END -->
+
+Given the importance and delicacy of the job that it performs, it is
+important to understand both what a synchronizer does under normal
+conditions and what can happen under unusual conditions such as system
+crashes and communication failures. <BR>
+<BR>
+Unison is careful to protect both its internal state and the state of
+the replicas at every point in this process. Specifically, the
+following guarantees are enforced:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+At every moment, each path in each replica has either (1) its <EM>original</EM> contents (i.e., no change at all has been made to this
+path), or (2) its <EM>correct</EM> final contents (i.e., the value that the
+user expected to be propagated from the other replica).
+<LI CLASS="li-itemize">At every moment, the information stored on disk about Unison's
+private state can be either (1) unchanged, or (2) updated to reflect
+those paths that have been successfully synchronized.
+</UL>
+The upshot is that it is safe to interrupt Unison at any time, either
+manually or accidentally. [Caveat: the above is <EM>almost</EM> true there
+are occasionally brief periods where it is not (and, because of
+shortcoming of the Posix filesystem API, cannot be); in particular, when
+it is copying a file onto a directory or vice versa, it must first move
+the original contents out of the way. If Unison gets
+interrupted during one of these periods, some manual cleanup may be
+required. In this case, a file called <TT>DANGER.README</TT> will be left
+in your home directory, containing information about the operation that
+was interrupted. The next time you try to run Unison, it will notice this
+file and warn you about it.]<BR>
+<BR>
+If an interruption happens while it is propagating updates, then there
+may be some paths for which an update has been propagated but which
+have not been marked as synchronized in Unison's archives. This is no
+problem: the next time Unison runs, it will detect changes to these
+paths in both replicas, notice that the contents are now equal, and
+mark the paths as successfully updated when it writes back its private
+state at the end of this run.<BR>
+<BR>
+If Unison is interrupted, it may sometimes leave temporary working files
+(with suffix <CODE>.tmp</CODE>) in the replicas. It is safe to delete these
+files. Also, if the <CODE>backups</CODE> flag is set, Unison will
+leave around old versions of files that it overwrites, with names like
+<CODE>file.0.unison.bak</CODE>. These can be deleted safely when they are no
+longer wanted.<BR>
+<BR>
+Unison is not bothered by clock skew between the different hosts on
+which it is running. It only performs comparisons between timestamps
+obtained from the same host, and the only assumption it makes about
+them is that the clock on each system always runs forward.<BR>
+<BR>
+If Unison finds that its archive files have been deleted (or that the
+archive format has changed and they cannot be read, or that they don't
+exist because this is the first run of Unison on these particular
+roots), it takes a conservative approach: it behaves as though the
+replicas had both been completely empty at the point of the last
+synchronization. The effect of this is that, on the first run, files
+that exist in only one replica will be propagated to the other, while
+files that exist in both replicas but are unequal will be marked as
+conflicting. <BR>
+<BR>
+Touching a file without changing its contents should never affect whether or
+not Unison does an update. (When running with the fastcheck preference set
+to true—the default on Unix systems—Unison uses file modtimes for a
+quick first pass to tell which files have definitely not changed; then, for
+each file that might have changed, it computes a fingerprint of the file's
+contents and compares it against the last-synchronized contents. Also, the
+<CODE>-times</CODE> option allows you to synchronize file times, but it does not
+cause identical files to be changed; Unison will only modify the file
+times.)<BR>
+<BR>
+It is safe to “brainwash” Unison by deleting its archive files
+<EM>on both replicas</EM>. The next time it runs, it will assume that
+all the files it sees in the replicas are new. <BR>
+<BR>
+It is safe to modify files while Unison is working. If Unison
+discovers that it has propagated an out-of-date change, or that the
+file it is updating has changed on the target replica, it will signal
+a failure for that file. Run Unison again to propagate the latest
+change.
+<BR>
+<BR>
+Changes to the ignore patterns from the user interface (e.g., using
+the `i' key) are immediately reflected in the current profile.<BR>
+<BR>
+<!--TOC subsection Caveats and Shortcomings-->
+
+<H3 CLASS="subsection"><A NAME="caveats"></A>Caveats and Shortcomings</H3><!--SEC END -->
+
+Here are some things to be careful of when using Unison.
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+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 <A HREF="#updates">What is an Update?</A> section. <BR>
+<BR>
+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.<BR>
+<BR>
+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
+ <CODE>retouch</CODE> to change a file's modtime back to a time in the past.
+ <BR>
+<BR>
+<LI CLASS="li-itemize">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. <BR>
+<BR>
+You can control this by setting your <CODE>umask</CODE> on both computers to
+something like 022, masking out the “world write” and “group write”
+permission bits. <BR>
+<BR>
+Unison does not synchronize the <CODE>setuid</CODE> and <CODE>setgid</CODE> bits, for
+security. <BR>
+<BR>
+<LI CLASS="li-itemize">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.<BR>
+<BR>
+<LI CLASS="li-itemize">Unison does not understand hard links.<BR>
+<BR>
+<LI CLASS="li-itemize">It is important to be a little careful when renaming directories
+containing <TT>ignore</TT>d files. <BR>
+<BR>
+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.<BR>
+<BR>
+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 (<EM>not</EM> including the ignored files, since they
+ are completely invisible to it).
+</UL>
+<hr><!--TOC section Reference Guide-->
+
+<H2 CLASS="section"><A NAME="reference"></A>Reference Guide</H2><!--SEC END -->
+
+This section covers the features of Unison in detail. <BR>
+<BR>
+<!--TOC subsection Running Unison-->
+
+<H3 CLASS="subsection"><A NAME="running"></A>Running Unison</H3><!--SEC END -->
+
+There are several ways to start Unison.
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Typing “<TT>unison <I>profile</I></TT>” on the command line. Unison
+will look for a file <TT><I>profile</I></TT><TT>.prf</TT> in the <CODE>.unison</CODE>
+directory. 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.
+<LI CLASS="li-itemize">Typing “<TT>unison <I>profile</I></TT><TT> <I>root1</I></TT><TT> <I>root2</I></TT>” on the command
+line.
+In this case, Unison will use <TT><I>profile</I></TT>, which should not contain
+any <TT>root</TT> directives.
+<LI CLASS="li-itemize">Typing “<TT>unison <I>root1</I></TT><TT> <I>root2</I></TT>” on the command line. This
+has the same effect as typing “<TT>unison default <I>root1</I></TT><TT> <I>root2</I></TT>.”
+<LI CLASS="li-itemize">Typing just “<TT>unison</TT>” (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).
+</UL>
+<!--TOC subsection The <TT>.unison</TT> Directory-->
+
+<H3 CLASS="subsection"><A NAME="unisondir"></A>The <TT>.unison</TT> Directory</H3><!--SEC END -->
+
+Unison stores a variety of information in a private directory on each
+host. If the environment variable <TT>UNISON</TT> is defined, then its
+value will be used as the name of this directory. If <TT>UNISON</TT> is
+not defined, then the name of the directory depends on which
+operating system you are using. In Unix, the default is to use
+<TT>$HOME/.unison</TT>.
+In Windows, if the environment variable
+<TT>USERPROFILE</TT> is defined, then the directory will be
+<TT>$USERPROFILE\.unison</TT>;
+otherwise if <TT>HOME</TT> is defined, it will be
+<TT>$HOME\.unison</TT>;
+otherwise, it will be
+<TT>c:\.unison</TT>.<BR>
+<BR>
+The archive file for each replica is found in the <TT>.unison</TT>
+directory on that replica's host. Profiles (described below) are
+always taken from the <TT>.unison</TT> directory on the client host.<BR>
+<BR>
+Note that Unison maintains a completely different set of archive files
+for each pair of roots.<BR>
+<BR>
+We do not recommend synchronizing the whole <TT>.unison</TT> directory, as this
+will involve frequent propagation of large archive files. It should be safe
+to do it, though, if you really want to. Synchronizing just the profile
+files in the <TT>.unison</TT> directory is definitely OK.<BR>
+<BR>
+<!--TOC subsection Archive Files-->
+
+<H3 CLASS="subsection"><A NAME="archives"></A>Archive Files</H3><!--SEC END -->
+
+The name of the archive file on each replica is calculated from
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+the <EM>canonical names</EM> of all the hosts (short names like
+ <CODE>saul</CODE> are converted into full addresses like <CODE>saul.cis.upenn.edu</CODE>),
+<LI CLASS="li-itemize">the paths to the replicas on all the hosts (again, relative
+ pathnames, symbolic links, etc. are converted into full, absolute paths), and
+<LI CLASS="li-itemize">an internal version number that is changed whenever a new Unison
+ release changes the format of the information stored in the archive.
+</UL>
+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.<BR>
+<BR>
+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
+<CODE>gethostname</CODE> operating system call. However, if the environment
+variable <CODE>UNISONLOCALHOSTNAME</CODE> is set, its value will be used
+instead. This makes it easier to use Unison in situations where a
+machine's name changes frequently (e.g., because it is a laptop and gets
+moved around a lot).<BR>
+<BR>
+A more powerful way of changing archive names is provided by the
+<CODE>rootalias</CODE> preference. The preference file may contain any number of
+lines of the form:
+<PRE>
+ rootalias = //<I>hostnameA</I>//<I>path-to-replicaA</I> -> //<I>hostnameB</I>/<I>path-to-replicaB</I>
+</PRE>
+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.<BR>
+<BR>
+So, if you need to relocate a root on one of the hosts, you can add a
+rule of the form:
+<PRE>
+ rootalias = //<I>new-hostname</I>//<I>new-path</I> -> //<I>old-hostname</I>/<I>old-path</I>
+</PRE>
+Note that root aliases are case-sensitive, even on case-insensitive file
+systems.<BR>
+<BR>
+<EM>Warning</EM>: The <CODE>rootalias</CODE> 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 <CODE>rootalias</CODE>, it is a good idea to run Unison
+a few times interactively (with the <CODE>batch</CODE> flag off, etc.) and
+carefully check that things look reasonable—in particular, that update
+detection is working as expected.<BR>
+<BR>
+<!--TOC subsection Preferences-->
+
+<H3 CLASS="subsection"><A NAME="prefs"></A>Preferences</H3><!--SEC END -->
+
+Many details of Unison's behavior are configurable by user-settable
+“preferences.” <BR>
+<BR>
+Some preferences are boolean-valued; these are often called <EM>flags</EM>.
+Others take numeric or string arguments, indicated in the preferences
+list by <TT>n</TT> or <TT>xxx</TT>. Most of the string preferences can be
+given several times; the arguments are accumulated into a list
+internally.<BR>
+<BR>
+There are two ways to set the values of preferences: temporarily, by
+providing command-line arguments to a particular run of Unison, or
+permanently, by adding commands to a <EM>profile</EM> in the <TT>.unison</TT>
+directory on the client host. The order of preferences (either on the
+command line or in preference files) is not significant. On the command
+line, preferences and other arguments (the profile name and roots) can be
+intermixed in any order.<BR>
+<BR>
+To set the value of a preference <TT>p</TT> from the command line, add an
+argument <TT>-p</TT> (for a boolean flag) or <TT>-p n</TT> or <TT>-p xxx</TT> (for
+a numeric or string preference) anywhere on the command line. To set a
+boolean flag to <CODE>false</CODE> on the command line, use <TT>-p=false</TT>.<BR>
+<BR>
+Here are all the preferences supported by Unison. This list can be
+ obtained by typing <TT>unison -help</TT>.
+<BLOCKQUOTE CLASS="quote">
+<PRE CLASS="verbatim">
+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
+ -group synchronize group attributes
+ -ignore xxx add a pattern to the ignore list
+ -ignorenot xxx add a pattern to the ignorenot list
+ -nocreation xxx prevent file creations on one replica
+ -nodeletion xxx prevent file deletions on one replica
+ -noupdate xxx prevent file updates and deletions on one replica
+ -owner synchronize owner
+ -path xxx path to synchronize
+ -perms n part of the permissions which is synchronized
+ -root xxx root of a replica (should be used exactly twice)
+ -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
+ -confirmbigdel ask about whole-replica (or path) deletes (default true)
+ -confirmmerge ask for confirmation before commiting results of a merge
+ -contactquietly suppress the 'contacting server' message during startup
+ -copymax n maximum number of simultaneous copyprog transfers
+ -copyprog xxx external program for copying large files
+ -copyprogrest xxx variant of copyprog for resuming partial transfers
+ -copyquoterem xxx add quotes to remote file name for copyprog (true/false/default)
+ -copythreshold n use copyprog on files bigger than this (if >=0, in Kb)
+ -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)
+ -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
+ -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
+ -xferbycopying optimize transfers using local copies (default true)
+
+</PRE>
+</BLOCKQUOTE>
+Here, in more detail, is what they do. Many are discussed in greater detail
+in other sections of the manual.
+<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
+<B>addprefsto <TT>xxx</TT></B><DD CLASS="dd-description">
+By default, new preferences added by Unison (e.g., new <CODE>ignore</CODE> clauses) will be appended to whatever preference file Unison was told to load at the beginning of the run. Setting the preference <TT>addprefsto <I>filename</I></TT> makes Unison add new preferences to the file named <TT><I>filename</I></TT> instead.<BR>
+<BR>
+<DT CLASS="dt-description"><B>addversionno </B><DD CLASS="dd-description">
+When this flag is set to <TT>true</TT>, Unison will use <TT>unison-<I>currentversionnumber</I></TT> instead of just <CODE>unison</CODE> 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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>auto </B><DD CLASS="dd-description">
+When set to <TT>true</TT>, 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.)<BR>
+<BR>
+<DT CLASS="dt-description"><B>backup <TT>xxx</TT></B><DD CLASS="dd-description">
+Including the preference <TT>-backup <I>pathspec</I></TT> causes Unison to keep backup files for each path that matches <TT><I>pathspec</I></TT>. These backup files are kept in the directory specified by the <CODE>backuplocation</CODE> preference. The backups are named according to the <CODE>backupprefix</CODE> and <CODE>backupsuffix</CODE> preferences. The number of versions that are kept is determined by the <CODE>maxbackups</CODE> preference.<BR>
+<BR>
+The syntax of <TT><I>pathspec</I></TT> is described in the <A HREF="#pathspec">Path Specification</A> section.<BR>
+<BR>
+<DT CLASS="dt-description"><B>backupcurr <TT>xxx</TT></B><DD CLASS="dd-description">
+Including the preference <TT>-backupcurr <I>pathspec</I></TT> causes Unison to keep a backup of the <EM>current</EM> version of every file matching <TT><I>pathspec</I></TT>. 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 <CODE>merge</CODE> preference. For more details, see the <A HREF="#merge">Merging Conflicting Versions</A> section.<BR>
+<BR>
+The syntax of <TT><I>pathspec</I></TT> is described in the <A HREF="#pathspec">Path Specification</A> section.<BR>
+<BR>
+<DT CLASS="dt-description"><B>backupcurrnot <TT>xxx</TT></B><DD CLASS="dd-description">
+Exceptions to <CODE>backupcurr</CODE>, like the <CODE>ignorenot</CODE> preference.<BR>
+<BR>
+<DT CLASS="dt-description"><B>backupdir <TT>xxx</TT></B><DD CLASS="dd-description">
+If this preference is set, Unison will use it as the name of the directory used to store backup files specified by the <TT>backup</TT> preference, when <TT>backuplocation</TT> is set to <CODE>central</CODE>. It is checked <EM>after</EM> the <TT>UNISONBACKUPDIR</TT> environment variable.<BR>
+<BR>
+<DT CLASS="dt-description"><B>backuploc <TT>xxx</TT></B><DD CLASS="dd-description">
+This preference determines whether backups should be kept locally, near the original files, or in a central directory specified by the <TT>backupdir</TT> preference. If set to <CODE>local</CODE>, backups will be kept in the same directory as the original files, and if set to <CODE>central</CODE>, <TT>backupdir</TT> will be used instead.<BR>
+<BR>
+<DT CLASS="dt-description"><B>backupnot <TT>xxx</TT></B><DD CLASS="dd-description">
+The values of this preference specify paths or individual files or regular expressions that should <EM>not</EM> be backed up, even if the <TT>backup</TT> preference selects them—i.e., it selectively overrides <TT>backup</TT>. The same caveats apply here as with <TT>ignore</TT> and <TT>ignorenot</TT>.<BR>
+<BR>
+<DT CLASS="dt-description"><B>backupprefix <TT>xxx</TT></B><DD CLASS="dd-description">
+When a backup for a file <CODE>NAME</CODE> is created, it is stored in a directory specified by <TT>backuplocation</TT>, in a file called <TT>backupprefix</TT><CODE>NAME</CODE><TT>backupsuffix</TT>. <TT>backupprefix</TT> can include a directory name (causing Unison to keep all backup files for a given directory in a subdirectory with this name), and both <TT>backupprefix</TT> and <TT>backupsuffix</TT> can contain the string<TT><I>$VERSION</I></TT>, which will be replaced by the <EM>age</EM> 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. <BR>
+<BR>
+One thing to be careful of: If the <TT>backuploc</TT> preference is set to <TT>local</TT>, Unison will automatically ignore <EM>all</EM> files whose prefix and suffix match <TT>backupprefix</TT> and <TT>backupsuffix</TT>. So be careful to choose values for these preferences that are sufficiently different from the names of your real files.<BR>
+<BR>
+<DT CLASS="dt-description"><B>backups </B><DD CLASS="dd-description">
+Setting this flag to true is equivalent to setting <TT>backuplocation</TT> to <TT>local</TT> and <TT>backup</TT> to <CODE>Name *</CODE>.<BR>
+<BR>
+<DT CLASS="dt-description"><B>backupsuffix <TT>xxx</TT></B><DD CLASS="dd-description">
+See <TT>backupprefix</TT> for full documentation.<BR>
+<BR>
+<DT CLASS="dt-description"><B>batch </B><DD CLASS="dd-description">
+When this is set to <TT>true</TT>, the user interface will ask no questions at all. Non-conflicting changes will be propagated; conflicts will be skipped.<BR>
+<BR>
+<DT CLASS="dt-description"><B>confirmbigdel </B><DD CLASS="dd-description">
+When this is set to <TT>true</TT>, Unison will request an extra confirmation if it appears that the entire replica has been deleted, before propagating the change. If the <TT>batch</TT> flag is also set, synchronization will be aborted. When the <TT>path</TT> 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 <TT>mountpoint</TT> preference.<BR>
+<BR>
+<DT CLASS="dt-description"><B>confirmmerge </B><DD CLASS="dd-description">
+Setting this preference causes both the text and graphical interfaces to ask the user if the results of a merge command may be commited 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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>contactquietly </B><DD CLASS="dd-description">
+If this flag is set, Unison will skip displaying the `Contacting server' message (which some users find annoying) during startup.<BR>
+<BR>
+<DT CLASS="dt-description"><B>copymax <TT>n</TT></B><DD CLASS="dd-description">
+A number indicating how many instances of the external copying utility Unison is allowed to run simultaneously (default to 1).<BR>
+<BR>
+<DT CLASS="dt-description"><B>copyprog <TT>xxx</TT></B><DD CLASS="dd-description">
+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 <TT>rsync</TT> with appropriate options—most users should not need to change it.<BR>
+<BR>
+<DT CLASS="dt-description"><B>copyprogrest <TT>xxx</TT></B><DD CLASS="dd-description">
+A variant of <TT>copyprog</TT> that names an external program that should be used to continue the transfer of a large file that has already been partially transferred. Typically, <TT>copyprogrest</TT> will just be <TT>copyprog</TT> with one extra option (e.g., <TT>–partial</TT>, for rsync). The default setting invokes <TT>rsync</TT> with appropriate options—most users should not need to change it.<BR>
+<BR>
+<DT CLASS="dt-description"><B>copyquoterem <TT>xxx</TT></B><DD CLASS="dd-description">
+When set to <TT>true</TT>, 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 <TT>default</TT>, extra quotes are added if the value of <TT>copyprog</TT> contains the string <TT>rsync</TT>.<BR>
+<BR>
+<DT CLASS="dt-description"><B>copythreshold <TT>n</TT></B><DD CLASS="dd-description">
+A number indicating above what filesize (in kilobytes) Unison should use the external copying utility specified by <TT>copyprog</TT>. Specifying 0 will cause <EM>all</EM> copies to use the external program; a negative number will prevent any files from using it. The default is -1. See the <A HREF="#speeding">Making Unison Faster on Large Files</A> section for more information.<BR>
+<BR>
+<DT CLASS="dt-description"><B>debug <TT>xxx</TT></B><DD CLASS="dd-description">
+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 <CODE>debug</CODE> can be found by looking for calls to <CODE>Util.debug</CODE> in the sources (using, e.g., <CODE>grep</CODE>). Setting <CODE>-debug all</CODE> causes information from <EM>all</EM> 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); <CODE>-debug verbose</CODE> turns on some additional debugging output from some modules (e.g., it will show exactly what bytes are being sent across the network).<BR>
+<BR>
+<DT CLASS="dt-description"><B>diff <TT>xxx</TT></B><DD CLASS="dd-description">
+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 `<CODE>diff -u CURRENT2 CURRENT1</CODE>'. 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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>doc <TT>xxx</TT></B><DD CLASS="dd-description">
+The command-line argument <TT>-doc <I>secname</I></TT> causes unison to display section <TT><I>secname</I></TT> of the manual on the standard output and then exit. Use <CODE>-doc all</CODE> to display the whole manual, which includes exactly the same information as the printed and HTML manuals, modulo formatting. Use <CODE>-doc topics</CODE> to obtain a list of the names of the various sections that can be printed.<BR>
+<BR>
+<DT CLASS="dt-description"><B>dontchmod </B><DD CLASS="dd-description">
+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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>dumbtty </B><DD CLASS="dd-description">
+When set to <CODE>true</CODE>, 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. <BR>
+<BR>
+When <CODE>dumbtty</CODE> 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.)<BR>
+<BR>
+This preference has no effect on the graphical user interface.<BR>
+<BR>
+<DT CLASS="dt-description"><B>dumparchives </B><DD CLASS="dd-description">
+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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>fastcheck <TT>xxx</TT></B><DD CLASS="dd-description">
+When this preference is set to <CODE>true</CODE>, 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. 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 <EM>overwrite</EM> 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 under Windows most of the time and occasionally run Unison once with <TT>fastcheck</TT> set to <CODE>false</CODE>, if you are worried that Unison may have overlooked an update. For backward compatibility, <CODE>yes</CODE>, <CODE>no</CODE>, and <CODE>default</CODE> can be used in place of <CODE>true</CODE>, <CODE>false</CODE>, and <CODE>auto</CODE>. See the <A HREF="#fastcheck">Fast Checking</A> section for more information.<BR>
+<BR>
+<DT CLASS="dt-description"><B>fat </B><DD CLASS="dd-description">
+When this is set to <TT>true</TT>, 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 (<TT>perms = 0</TT>); never use chmod ( t dontchmod = true); treat filenames as case insensitive (<TT>ignorecase = true</TT>); do not attempt to synchronize symbolic links (<TT>links = false</TT>); ignore inode number changes when detecting updates (<TT>ignoreinodenumbers = true</TT>). Any of these change can be overridden by explicitely setting the corresponding preference in the profile.<BR>
+<BR>
+<DT CLASS="dt-description"><B>follow <TT>xxx</TT></B><DD CLASS="dd-description">
+Including the preference <TT>-follow <I>pathspec</I></TT> causes Unison to treat symbolic links matching <TT><I>pathspec</I></TT> as `invisible' and behave as if the object pointed to by the link had appeared literally at this position in the replica. See the <A HREF="#symlinks">Symbolic Links</A> section for more details. The syntax of <TT><I>pathspec</I></TT> is described in the <A HREF="#pathspec">Path Specification</A> section.<BR>
+<BR>
+<DT CLASS="dt-description"><B>force <TT>xxx</TT></B><DD CLASS="dd-description">
+Including the preference <TT>-force <I>root</I></TT> causes Unison to resolve all differences (even non-conflicting changes) in favor of <TT><I>root</I></TT>. This effectively changes Unison from a synchronizer into a mirroring utility. <BR>
+<BR>
+You can also specify <CODE>-force newer</CODE> (or <CODE>-force older</CODE>) to force Unison to choose the file with the later (earlier) modtime. In this case, the <CODE>-times</CODE> preference must also be enabled.<BR>
+<BR>
+This preference is overridden by the <CODE>forcepartial</CODE> preference.<BR>
+<BR>
+This preference should be used only if you are <EM>sure</EM> you know what you are doing!<BR>
+<BR>
+<DT CLASS="dt-description"><B>forcepartial <TT>xxx</TT></B><DD CLASS="dd-description">
+Including the preference <TT>forcepartial = <I>PATHSPEC</I></TT><TT> -> <I>root</I></TT> causes Unison to resolve all differences (even non-conflicting changes) in favor of <TT><I>root</I></TT> for the files in <TT><I>PATHSPEC</I></TT> (see the <A HREF="#pathspec">Path Specification</A> section for more information). This effectively changes Unison from a synchronizer into a mirroring utility. <BR>
+<BR>
+You can also specify <CODE>forcepartial PATHSPEC -> newer</CODE> (or <CODE>forcepartial PATHSPEC older</CODE>) to force Unison to choose the file with the later (earlier) modtime. In this case, the <CODE>-times</CODE> preference must also be enabled.<BR>
+<BR>
+This preference should be used only if you are <EM>sure</EM> you know what you are doing!<BR>
+<BR>
+<DT CLASS="dt-description"><B>group </B><DD CLASS="dd-description">
+When this flag is set to <CODE>true</CODE>, the group attributes of the files are synchronized. Whether the group names or the group identifiers are synchronized depends on the preference <TT>numerids</TT>.<BR>
+<BR>
+<DT CLASS="dt-description"><B>halfduplex </B><DD CLASS="dd-description">
+When this flag is set to <TT>true</TT>, 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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>height <TT>n</TT></B><DD CLASS="dd-description">
+Used to set the height (in lines) of the main window in the graphical user interface.<BR>
+<BR>
+<DT CLASS="dt-description"><B>ignore <TT>xxx</TT></B><DD CLASS="dd-description">
+Including the preference <TT>-ignore <I>pathspec</I></TT> causes Unison to completely ignore paths that match <TT><I>pathspec</I></TT> (as well as their children). This is useful for avoiding synchronizing temporary files, object files, etc. The syntax of <TT><I>pathspec</I></TT> is described in the <A HREF="#pathspec">Path Specification</A> section, and further details on ignoring paths is found in the <A HREF="#ignore">Ignoring Paths</A> section.<BR>
+<BR>
+<DT CLASS="dt-description"><B>ignorearchives </B><DD CLASS="dd-description">
+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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>ignorecase <TT>xxx</TT></B><DD CLASS="dd-description">
+When set to <TT>true</TT>, 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 <TT>false</TT>, Unison will treat all filenames as case sensitive. Ordinarily, when the flag is set to <TT>default</TT>, 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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>ignoreinodenumbers </B><DD CLASS="dd-description">
+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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>ignorelocks </B><DD CLASS="dd-description">
+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 <EM>positive</EM> 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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>ignorenot <TT>xxx</TT></B><DD CLASS="dd-description">
+This preference overrides the preference <TT>ignore</TT>.
+ It gives a list of patterns
+ (in the same format as
+ <CODE>ignore</CODE>) for paths that should definitely <EM>not</EM> be ignored,
+ whether or not they happen to match one of the <CODE>ignore</CODE> patterns.
+ <BR>
+<BR>
+Note that the semantics of <TT>ignore</TT> and <TT>ignorenot</TT> 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 <TT>ignore</TT> and does not match <TT>ignorenot</TT>; in this case
+ it skips this path <EM>and all its descendants</EM>. This means that,
+ if some parent of a given path matches an <TT>ignore</TT> pattern, then
+ it will be skipped even if the path itself matches an <TT>ignorenot</TT>
+ pattern. In particular, putting <TT>ignore = Path *</TT> in your profile
+ and then using <TT>ignorenot</TT> to select particular paths to be
+ synchronized will not work. Instead, you should use the <TT>path</TT>
+ preference to choose particular paths to synchronize.<BR>
+<BR>
+<DT CLASS="dt-description"><B>immutable <TT>xxx</TT></B><DD CLASS="dd-description">
+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).<BR>
+<BR>
+<DT CLASS="dt-description"><B>immutablenot <TT>xxx</TT></B><DD CLASS="dd-description">
+This preference overrides <TT>immutable</TT>.<BR>
+<BR>
+<DT CLASS="dt-description"><B>key <TT>xxx</TT></B><DD CLASS="dd-description">
+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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>killserver </B><DD CLASS="dd-description">
+When set to <CODE>true</CODE>, this flag causes Unison to kill the remote server process when the synchronization is finished. This behavior is the default for <CODE>ssh</CODE> connections, so this preference is not normally needed when running over <CODE>ssh</CODE>; 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.)<BR>
+<BR>
+<DT CLASS="dt-description"><B>label <TT>xxx</TT></B><DD CLASS="dd-description">
+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.)<BR>
+<BR>
+<DT CLASS="dt-description"><B>links <TT>xxx</TT></B><DD CLASS="dd-description">
+When set to <TT>true</TT>, this flag causes Unison to synchronize symbolic links. When the flag is set to <TT>false</TT>, symbolic links will result in an error during update detection. Ordinarily, when the flag is set to <TT>default</TT>, 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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>log </B><DD CLASS="dd-description">
+When this flag is set, Unison will log all changes to the filesystems
+ on a file.<BR>
+<BR>
+<DT CLASS="dt-description"><B>logfile <TT>xxx</TT></B><DD CLASS="dd-description">
+By default, logging messages will be appended to the file
+ <CODE>unison.log</CODE> in your HOME directory. Set this preference if
+ you prefer another file.<BR>
+<BR>
+<DT CLASS="dt-description"><B>maxbackups <TT>n</TT></B><DD CLASS="dd-description">
+This preference specifies the number of backup versions that will be kept by unison, for each path that matches the predicate <CODE>backup</CODE>. The default is 2.<BR>
+<BR>
+<DT CLASS="dt-description"><B>maxerrors <TT>n</TT></B><DD CLASS="dd-description">
+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).<BR>
+<BR>
+<DT CLASS="dt-description"><B>maxthreads <TT>n</TT></B><DD CLASS="dd-description">
+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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>merge <TT>xxx</TT></B><DD CLASS="dd-description">
+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 <TT>merge</TT> preference for a path will also cause this path to be backed up, just like t backup. The syntax of <TT><I>pathspec>cmd</I></TT> is described in the <A HREF="#pathspec">Path Specification</A> section, and further details on Merging functions are present in the <A HREF="#merge">Merging files</A> section.<BR>
+<BR>
+<DT CLASS="dt-description"><B>mountpoint <TT>xxx</TT></B><DD CLASS="dd-description">
+Including the preference <TT>-mountpoint PATH</TT> causes Unison to double-check, at the end of update detection, that <TT>PATH</TT> 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 <A HREF="#mountpoints">Mount Points</A> section.<BR>
+<BR>
+<DT CLASS="dt-description"><B>nocreation <TT>xxx</TT></B><DD CLASS="dd-description">
+Including the preference <TT>-nocreation <I>root</I></TT> prevents Unison from performing any file creation on root <TT><I>root</I></TT>.<BR>
+<BR>
+This preference can be included twice, once for each root, if you want to prevent any creation.<BR>
+<BR>
+<DT CLASS="dt-description"><B>nocreationpartial <TT>xxx</TT></B><DD CLASS="dd-description">
+Including the preference <TT>nocreationpartial = <I>PATHSPEC</I></TT><TT> -> <I>root</I></TT> prevents Unison from performing any file creation in <TT><I>PATHSPEC</I></TT> on root <TT><I>root</I></TT> (see the <A HREF="#pathspec">Path Specification</A> section for more information). It is recommended to use <TT>BelowPath</TT> patterns when selecting a directory and all its contents.<BR>
+<BR>
+<DT CLASS="dt-description"><B>nodeletion <TT>xxx</TT></B><DD CLASS="dd-description">
+Including the preference <TT>-nodeletion <I>root</I></TT> prevents Unison from performing any file deletion on root <TT><I>root</I></TT>.<BR>
+<BR>
+This preference can be included twice, once for each root, if you want to prevent any creation.<BR>
+<BR>
+<DT CLASS="dt-description"><B>nodeletionpartial <TT>xxx</TT></B><DD CLASS="dd-description">
+Including the preference <TT>nodeletionpartial = <I>PATHSPEC</I></TT><TT> -> <I>root</I></TT> prevents Unison from performing any file deletion in <TT><I>PATHSPEC</I></TT> on root <TT><I>root</I></TT> (see the <A HREF="#pathspec">Path Specification</A> section for more information). It is recommended to use <TT>BelowPath</TT> patterns when selecting a directory and all its contents.<BR>
+<BR>
+<DT CLASS="dt-description"><B>noupdate <TT>xxx</TT></B><DD CLASS="dd-description">
+Including the preference <TT>-noupdate <I>root</I></TT> prevents Unison from performing any file update or deletion on root <TT><I>root</I></TT>.<BR>
+<BR>
+This preference can be included twice, once for each root, if you want to prevent any update.<BR>
+<BR>
+<DT CLASS="dt-description"><B>noupdatepartial <TT>xxx</TT></B><DD CLASS="dd-description">
+Including the preference <TT>noupdatepartial = <I>PATHSPEC</I></TT><TT> -> <I>root</I></TT> prevents Unison from performing any file update or deletion in <TT><I>PATHSPEC</I></TT> on root <TT><I>root</I></TT> (see the <A HREF="#pathspec">Path Specification</A> section for more information). It is recommended to use <TT>BelowPath</TT> patterns when selecting a directory and all its contents.<BR>
+<BR>
+<DT CLASS="dt-description"><B>numericids </B><DD CLASS="dd-description">
+When this flag is set to <CODE>true</CODE>, groups and users are synchronized numerically, rather than by name. <BR>
+<BR>
+The special uid 0 and the special group 0 are never mapped via user/group names even if this preference is not set.<BR>
+<BR>
+<DT CLASS="dt-description"><B>owner </B><DD CLASS="dd-description">
+When this flag is set to <CODE>true</CODE>, the owner attributes of the files are synchronized. Whether the owner names or the owner identifiers are synchronizeddepends on the preference <TT>numerids</TT>.<BR>
+<BR>
+<DT CLASS="dt-description"><B>path <TT>xxx</TT></B><DD CLASS="dd-description">
+When no <CODE>path</CODE> preference is given, Unison will simply synchronize the two entire replicas, beginning from the given pair of roots. If one or more <CODE>path</CODE> preferences are given, then Unison will synchronize only these paths and their children. (This is useful for doing a fast sync of just one directory, for example.) Note that <TT>path</TT> preferences are intepreted literally—they are not regular expressions.<BR>
+<BR>
+<DT CLASS="dt-description"><B>perms <TT>n</TT></B><DD CLASS="dd-description">
+The integer value of this preference is a mask indicating which permission bits should be synchronized. It is set by default to 0<I>o</I>1777: 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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>prefer <TT>xxx</TT></B><DD CLASS="dd-description">
+Including the preference <TT>-prefer <I>root</I></TT> causes Unison always to resolve conflicts in favor of <TT><I>root</I></TT>, rather than asking for guidance from the user. (The syntax of <TT><I>root</I></TT> is the same as for the <CODE>root</CODE> preference, plus the special values <CODE>newer</CODE> and <CODE>older</CODE>.) <BR>
+<BR>
+This preference is overridden by the <CODE>preferpartial</CODE> preference.<BR>
+<BR>
+This preference should be used only if you are <EM>sure</EM> you know what you are doing!<BR>
+<BR>
+<DT CLASS="dt-description"><B>preferpartial <TT>xxx</TT></B><DD CLASS="dd-description">
+Including the preference <TT>preferpartial = <I>PATHSPEC</I></TT><TT> -> <I>root</I></TT> causes Unison always to resolve conflicts in favor of <TT><I>root</I></TT>, rather than asking for guidance from the user, for the files in <TT><I>PATHSPEC</I></TT> (see the <A HREF="#pathspec">Path Specification</A> section for more information). (The syntax of <TT><I>root</I></TT> is the same as for the <CODE>root</CODE> preference, plus the special values <CODE>newer</CODE> and <CODE>older</CODE>.) <BR>
+<BR>
+This preference should be used only if you are <EM>sure</EM> you know what you are doing!<BR>
+<BR>
+<DT CLASS="dt-description"><B>repeat <TT>xxx</TT></B><DD CLASS="dd-description">
+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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>retry <TT>n</TT></B><DD CLASS="dd-description">
+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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>root <TT>xxx</TT></B><DD CLASS="dd-description">
+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 <CODE>root</CODE> 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 <A HREF="#roots">Roots</A> section.<BR>
+<BR>
+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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>rootalias <TT>xxx</TT></B><DD CLASS="dd-description">
+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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>rshargs <TT>xxx</TT></B><DD CLASS="dd-description">
+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 <CODE>rsh</CODE> command used to invoke the remote server. <BR>
+<BR>
+<DT CLASS="dt-description"><B>rshcmd <TT>xxx</TT></B><DD CLASS="dd-description">
+This preference can be used to explicitly set the name of the rsh executable (e.g., giving a full path name), if necessary.<BR>
+<BR>
+<DT CLASS="dt-description"><B>rsrc <TT>xxx</TT></B><DD CLASS="dd-description">
+When set to <TT>true</TT>, 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 <TT>false</TT>, Unison will not synchronize these data. Ordinarily, the flag is set to <TT>default</TT>, and these data are
+ automatically synchronized if either host is running OSX. In rare circumstances it is useful to set the flag manually.<BR>
+<BR>
+<DT CLASS="dt-description"><B>rsync </B><DD CLASS="dd-description">
+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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>selftest </B><DD CLASS="dd-description">
+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.)<BR>
+<BR>
+<DT CLASS="dt-description"><B>servercmd <TT>xxx</TT></B><DD CLASS="dd-description">
+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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>showarchive </B><DD CLASS="dd-description">
+When this preference is set, Unison will print out the 'true names'of the roots, in the same form as is expected by the <TT>rootalias</TT>preference.<BR>
+<BR>
+<DT CLASS="dt-description"><B>silent </B><DD CLASS="dd-description">
+When this preference is set to <TT>true</TT>, the textual user interface will print nothing at all, except in the case of errors. Setting <TT>silent</TT> to true automatically sets the <TT>batch</TT> preference to <TT>true</TT>.<BR>
+<BR>
+<DT CLASS="dt-description"><B>sortbysize </B><DD CLASS="dd-description">
+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.<BR>
+<BR>
+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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>sortfirst <TT>xxx</TT></B><DD CLASS="dd-description">
+Each argument to <TT>sortfirst</TT> is a pattern <TT><I>pathspec</I></TT>, which describes a set of paths. Files matching any of these patterns will be listed first in the user interface. The syntax of <TT><I>pathspec</I></TT> is described in the <A HREF="#pathspec">Path Specification</A> section.<BR>
+<BR>
+<DT CLASS="dt-description"><B>sortlast <TT>xxx</TT></B><DD CLASS="dd-description">
+Similar to <CODE>sortfirst</CODE>, except that files matching one of these patterns will be listed at the very end.<BR>
+<BR>
+<DT CLASS="dt-description"><B>sortnewfirst </B><DD CLASS="dd-description">
+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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>sshargs <TT>xxx</TT></B><DD CLASS="dd-description">
+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 <CODE>ssh</CODE> command used to invoke the remote server. <BR>
+<BR>
+<DT CLASS="dt-description"><B>sshcmd <TT>xxx</TT></B><DD CLASS="dd-description">
+This preference can be used to explicitly set the name of the ssh executable (e.g., giving a full path name), if necessary.<BR>
+<BR>
+<DT CLASS="dt-description"><B>sshversion <TT>xxx</TT></B><DD CLASS="dd-description">
+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 <CODE>ssh1</CODE> or<CODE>ssh2</CODE> instead of just <CODE>ssh</CODE> to invoke ssh. The default value is empty, which will make unison use whatever version of ssh is installed as the default `ssh' command.<BR>
+<BR>
+<DT CLASS="dt-description"><B>stream </B><DD CLASS="dd-description">
+When this preference is set, Unison will use an experimental streaming protocol for transferring file contents more efficiently. The default value is <TT>true</TT>.<BR>
+<BR>
+<DT CLASS="dt-description"><B>terse </B><DD CLASS="dd-description">
+When this preference is set to <TT>true</TT>, the user interface will not print status messages.<BR>
+<BR>
+<DT CLASS="dt-description"><B>testserver </B><DD CLASS="dd-description">
+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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>times </B><DD CLASS="dd-description">
+When this flag is set to <CODE>true</CODE>, file modification times (but not directory modtimes) are propagated.<BR>
+<BR>
+<DT CLASS="dt-description"><B>ui <TT>xxx</TT></B><DD CLASS="dd-description">
+This preference selects either the graphical or the textual user interface. Legal values are <CODE>graphic</CODE> or <CODE>text</CODE>. <BR>
+<BR>
+Because this option is processed specially during Unison's start-up sequence, it can <EM>only</EM> be used on the command line. In preference files it has no effect.<BR>
+<BR>
+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.)<BR>
+<BR>
+<DT CLASS="dt-description"><B>unicode <TT>xxx</TT></B><DD CLASS="dd-description">
+When set to <TT>true</TT>, this flag causes Unison to perform case insensitive file comparisons assuming Unicode encoding. This is the default. When the flag is set to <TT>false</TT>, 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.<BR>
+<BR>
+<DT CLASS="dt-description"><B>version </B><DD CLASS="dd-description">
+Print the current version number and exit. (This option only makes sense on the command line.)<BR>
+<BR>
+<DT CLASS="dt-description"><B>xferbycopying </B><DD CLASS="dd-description">
+When this preference is set, Unison will try to avoid transferring file contents across the network by recognizing when a file with the required contents already exists in the target replica. This usually allows file moves to be propagated very quickly. The default value is<TT>true</TT>. </DL>
+
+
+<!--TOC subsection Profiles-->
+
+<H3 CLASS="subsection"><A NAME="profile"></A>Profiles</H3><!--SEC END -->
+
+A <EM>profile</EM> is a text file that specifies permanent settings for
+roots, paths, ignore patterns, and other preferences, so that they do
+not need to be typed at the command line every time Unison is run.
+Profiles should reside in the <CODE>.unison</CODE> directory on the client
+machine. If Unison is started with just one argument <TT><I>name</I></TT> on
+the command line, it looks for a profile called <TT><I>name</I></TT><TT>.prf</TT> in
+the <CODE>.unison</CODE> directory. If it is started with no arguments, it
+scans the <CODE>.unison</CODE> directory for files whose names end in
+<CODE>.prf</CODE> and offers a menu (provided that the Unison executable is compiled with the graphical user interface). If a file named <CODE>default.prf</CODE> is
+found, its settings will be offered as the default choices.<BR>
+<BR>
+To set the value of a preference <TT>p</TT> permanently, add to the
+appropriate profile a line of the form
+<PRE CLASS="verbatim">
+ p = true
+</PRE>for a boolean flag or
+<PRE CLASS="verbatim">
+ p = <value>
+</PRE>for a preference of any other type. <BR>
+<BR>
+Whitespaces around <TT>p</TT> and <TT>xxx</TT> are ignored.
+A profile may also include blank lines and lines beginning
+with <TT>#</TT>; both are ignored.<BR>
+<BR>
+When Unison starts, it first reads the profile and then the command
+line, so command-line options will override settings from the
+profile. <BR>
+<BR>
+Profiles may also include lines of the form <TT>include
+ <I>name</I></TT>, which will cause the file <TT><I>name</I></TT> (or
+<TT><I>name</I></TT><TT>.prf</TT>, if <TT><I>name</I></TT> does not exist in the
+<CODE>.unison</CODE> directory) to be read at the point, and included as if
+its contents, instead of the <TT>include</TT> line, was part of the
+profile. Include lines allows settings common to several profiles to
+be stored in one place.<BR>
+<BR>
+A profile may include a preference `<TT>label = <I>desc</I></TT>' to
+provide a description of the options selected in this profile. The
+string <TT><I>desc</I></TT> 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.<BR>
+<BR>
+The graphical user-interface also supports one-key shortcuts for commonly
+used profiles. If a profile contains a preference of the form
+`<TT>key = <I>n</I></TT>', where <TT><I>n</I></TT> 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.<BR>
+<BR>
+<!--TOC subsection Sample Profiles-->
+
+<H3 CLASS="subsection"><A NAME="profileegs"></A>Sample Profiles</H3><!--SEC END -->
+
+<!--TOC subsubsection A Minimal Profile-->
+
+<H4 CLASS="subsubsection"><A NAME="minimalprofile"></A>A Minimal Profile</H4><!--SEC END -->
+
+Here is a very minimal profile file, such as might be found in <TT>.unison/default.prf</TT>:
+<PRE CLASS="verbatim">
+ # Roots of the synchronization
+ root = /home/bcpierce
+ root = ssh://saul//home/bcpierce
+
+ # Paths to synchronize
+ path = current
+ path = common
+ path = .netscape/bookmarks.html
+</PRE>
+<!--TOC subsubsection A Basic Profile-->
+
+<H4 CLASS="subsubsection"><A NAME="basicprofile"></A>A Basic Profile</H4><!--SEC END -->
+
+Here is a more sophisticated profile, illustrating some other useful
+features.
+<PRE CLASS="verbatim">
+ # 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
+</PRE>
+<!--TOC subsubsection A Power-User Profile-->
+
+<H4 CLASS="subsubsection"><A NAME="powerprofile"></A>A Power-User Profile</H4><!--SEC END -->
+
+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 <TT>include</TT> mechanism can also be used to allow the same set of preference
+settings to be used with different roots.)<BR>
+<BR>
+The collection
+of profiles implementing this scheme might look as follows.
+The file <TT>default.prf</TT> is empty except for an <TT>include</TT>
+directive:
+<PRE CLASS="verbatim">
+ # Include the contents of the file common
+ include common
+</PRE>Note that the name of the common file is <TT>common</TT>, not <TT>common.prf</TT>; this prevents Unison from offering <TT>common</TT> as one of
+the list of profiles in the opening dialog (in the graphical UI).<BR>
+<BR>
+The file <TT>common</TT> contains the real preferences:
+<PRE CLASS="verbatim">
+ # 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
+</PRE>Note that there are no <TT>path</TT> preferences in <TT>common</TT>. This
+means that, when we invoke Unison with the default profile (e.g., by
+typing '<TT>unison default</TT>' or just '<TT>unison</TT>' on the command
+line), the whole replicas will be synchronized. (If we <EM>never</EM> want
+to synchronize the whole replicas, then <TT>default.prf</TT> would instead
+include settings for all the paths that are usually synchronized.)<BR>
+<BR>
+To synchronize just part of the replicas, Unison is invoked with an
+alternate preference file—e.g., doing '<TT>unison workingset</TT>', where the
+preference file <TT>workingset.prf</TT> contains
+<PRE CLASS="verbatim">
+ path = current/papers
+ path = Mail/inbox
+ path = Mail/drafts
+ include common
+</PRE>causes Unison to synchronize just the listed subdirectories.<BR>
+<BR>
+The <TT>key</TT> preference can be used in combination with the graphical UI
+to quickly switch between different sets of paths. For example, if the
+file <TT>mail.prf</TT> contains
+<PRE CLASS="verbatim">
+ path = Mail
+ batch = true
+ key = 2
+ include common
+</PRE>then pressing 2 will cause Unison to look for updates in the <TT>Mail</TT>
+subdirectory and (because the <TT>batch</TT> flag is set) immediately
+propagate any that it finds.<BR>
+<BR>
+<!--TOC subsection Keeping Backups-->
+
+<H3 CLASS="subsection"><A NAME="backups"></A>Keeping Backups</H3><!--SEC END -->
+
+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.<BR>
+<BR>
+To enable backups, you must give one or more <CODE>backup</CODE> preferences.
+Each of these has the form
+<PRE CLASS="verbatim">
+ backup = <pathspec>
+</PRE>where <CODE><pathspec></CODE> has the same form as for the <CODE>ignore</CODE>
+preference. For example,
+<PRE CLASS="verbatim">
+ backup = Name *
+</PRE>causes Unison to keep backups of <EM>all</EM> files and directories. The
+<CODE>backupnot</CODE> preference can be used to give a few exceptions: it
+specifies which files and directories should <EM>not</EM> be backed up, even if
+they match the <CODE>backup</CODE> pathspec. <BR>
+<BR>
+It is important to note that the <CODE>pathspec</CODE> is matched against the path
+that is being updated by Unison, not its descendants. For example, if you
+set <CODE>backup = Name *.txt</CODE> and then delete a whole directory named
+<CODE>foo</CODE> containing some text files, these files will not be backed up
+because Unison will just check that <CODE>foo</CODE> does not match <CODE>*.txt</CODE>.
+Similarly, if the directory itself happened to be called <CODE>foo.txt</CODE>,
+then the whole directory and all the files in it will be backed up,
+regardless of their names. <BR>
+<BR>
+Backup files can be stored either <EM>centrally</EM> or <EM>locally</EM>. This
+behavior is controlled by the preference <CODE>backuplocation</CODE>, whose value
+must be either <CODE>central</CODE> or <CODE>local</CODE>. (The default is
+<CODE>central</CODE>.) <BR>
+<BR>
+When backups are stored locally, they are kept in the same
+directory as the original.<BR>
+<BR>
+When backups are stored centrally, the directory used to hold them is
+controlled by the preference <CODE>backupdir</CODE> and the
+environment variable <CODE>UNISONBACKUPDIR</CODE>. (The environment variable is
+checked first.) If neither of these are set, then the directory
+<CODE>.unison/backup</CODE> in the user's home directory is used.<BR>
+<BR>
+The preference <CODE>maxbackups</CODE> controls how many previous versions of
+each file are kept (including the current version). <BR>
+<BR>
+By default, backup files are named <CODE>.bak.VERSION.FILENAME</CODE>,
+where <CODE>FILENAME</CODE> is the original filename and <CODE>VERSION</CODE> is the
+backup number (1 for the most recent, 2 for the next most recent,
+etc.). This can be changed by setting the preferences <CODE>backupprefix</CODE>
+and/or <CODE>backupsuffix</CODE>. If desired, <CODE>backupprefix</CODE> may include a
+directory prefix; this can be used with <CODE>backuplocation = local</CODE> to put all
+backup files for each directory into a single subdirectory. For example, setting
+<PRE CLASS="verbatim">
+ backuplocation = local
+ backupprefix = .unison/$VERSION.
+ backupsuffix =
+</PRE>will put all backups in a local subdirectory named <CODE>.unison</CODE>. Also,
+note that the string <CODE>$VERSION</CODE> in either <CODE>backupprefix</CODE> or
+<CODE>backupsuffix</CODE> (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.<BR>
+<BR>
+For backward compatibility, the <CODE>backups</CODE> preference is also supported.
+It simply means <CODE>backup = Name *</CODE> and <CODE>backuplocation = local</CODE>.<BR>
+<BR>
+<!--TOC subsection Merging Conflicting Versions-->
+
+<H3 CLASS="subsection"><A NAME="merge"></A>Merging Conflicting Versions</H3><!--SEC END -->
+
+Unison can invoke external programs to merge conflicting versions of a file.
+The preference <CODE>merge</CODE> controls this process. <BR>
+<BR>
+The <CODE>merge</CODE> 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:
+<PRE CLASS="verbatim">
+ merge = <PATHSPEC> -> <MERGECMD>
+</PRE>The <CODE><PATHSPEC></CODE> here has exactly the same format as for the
+<CODE>ignore</CODE> preference (see the <A HREF="#pathspec">Path specification</A> section). For example,
+using “<CODE>Name *.txt</CODE>” as the <CODE><PATHSPEC></CODE> tells Unison that this
+command should be used whenever a file with extension <CODE>.txt</CODE> needs to
+be merged. <BR>
+<BR>
+Many external merging programs require as inputs not just the two files that
+need to be merged, but also a file containing the <EM>last synchronized
+ version</EM>. You can ask Unison to keep a copy of the last synchronized
+version for some files using the <CODE>backupcurrent</CODE> preference. This
+preference is used in exactly the same way as <CODE>backup</CODE> and its meaning
+is similar, except that it causes backups to be kept of the <EM>current</EM>
+contents of each file after it has been synchronized by Unison, rather than
+the <EM>previous</EM> contents that Unison overwrote. These backups are kept
+on <EM>both</EM> replicas in the same place as ordinary backup files—i.e.
+according to the <CODE>backuplocation</CODE> and <CODE>backupdir</CODE> preferences.
+They are named like the original files if <CODE>backupslocation</CODE> is set to
+'central' and otherwise, Unison uses the <CODE>backupprefix</CODE> and
+<CODE>backupsuffix</CODE> preferences and assumes a version number 000 for these
+backups.<BR>
+<BR>
+The <CODE><MERGECMD></CODE> part of the preference specifies what external command
+should be invoked to merge files at paths matching the <CODE><PATHSPEC></CODE>.
+Within this string, several special substrings are recognized; these will be
+substituted with appropriate values before invoking a sub-shell to execute
+the command.
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+<CODE>CURRENT1</CODE> is replaced by the name of (a temporary copy of)
+ the local variant of the file.
+<LI CLASS="li-itemize"><CODE>CURRENT2</CODE> 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.
+<LI CLASS="li-itemize"><CODE>CURRENTARCH</CODE> 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
+ <CODE>backupcurrent</CODE> preference, as explained above), if one exists.
+ If no archive exists and <CODE>CURRENTARCH</CODE> appears in the
+ merge command, then an error is signalled.
+<LI CLASS="li-itemize"><CODE>CURRENTARCHOPT</CODE> 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.
+<LI CLASS="li-itemize"><CODE>NEW</CODE> 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.
+<LI CLASS="li-itemize"><CODE>PATH</CODE> is replaced by the path (relative to the roots of
+ the replicas) of the file being merged.
+<LI CLASS="li-itemize"><CODE>NEW1</CODE> and <CODE>NEW2</CODE> 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, <CODE>NEW1</CODE>
+ will be written back to the local replica and <CODE>NEW2</CODE> to the remote
+ replica; <CODE>NEWARCH</CODE>, 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.)
+</UL>
+To accomodate the wide variety of programs that users might want to use for
+merging, Unison checks for several possible situations when the merge
+program exits:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+If the merge program exits with a non-zero status, then merge is
+ considered to have failed and the replicas are not changed.
+<LI CLASS="li-itemize">If the file <CODE>NEW</CODE> has been created, it is written back to both
+ replicas (and stored in the backup directory). Similarly, if just the
+ file <CODE>NEW1</CODE> has been created, it is written back to both
+ replicas.
+<LI CLASS="li-itemize">If neither <CODE>NEW</CODE> nor <CODE>NEW1</CODE> have been created, then Unison
+ examines the temporary files <CODE>CURRENT1</CODE> and <CODE>CURRENT2</CODE> 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 <CODE>CURRENT1</CODE> or <CODE>CURRENT2</CODE> has
+ been <EM>deleted</EM>, then the contents of the other are written back to
+ both replicas.
+<LI CLASS="li-itemize">If the files <CODE>NEW1</CODE>, <CODE>NEW2</CODE>, and <CODE>NEWARCH</CODE> have all
+ been created, they are written back to the local replica, remote replica,
+ and backup directory, respectively. If the files <CODE>NEW1</CODE>, <CODE>NEW2</CODE> have
+ been created, but <CODE>NEWARCH</CODE> has not, then these files are written back to the
+ local replica and remote replica, respectively. Also, if <CODE>NEW1</CODE> and
+ <CODE>NEW2</CODE> have identical contents, then the same contents are stored as
+ a backup (if the <CODE>backupcurrent</CODE> preference is set for this path) to
+ reflect the fact that the path is currently in sync.
+ <LI CLASS="li-itemize">If <CODE>NEW1</CODE> and <CODE>NEW2</CODE> (resp. <CODE>CURRENT1</CODE> and
+ <CODE>CURRENT2</CODE>) 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 <CODE>NEW1</CODE> (resp. <CODE>CURRENT1</CODE>) to the other replica and
+ to the archive. <BR>
+<BR>
+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.)
+</UL>
+If the <CODE>confirmmerge</CODE> 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.<BR>
+<BR>
+A large number of external merging programs are available.
+For example, on Unix systems setting the <CODE>merge</CODE> preference to
+<PRE CLASS="verbatim">
+ merge = Name *.txt -> diff3 -m CURRENT1 CURRENTARCH CURRENT2
+ > NEW || echo "differences detected"
+</PRE>will tell Unison to use the external <CODE>diff3</CODE> program for merging.
+Alternatively, users of <CODE>emacs</CODE> may find the following settings convenient:
+<PRE CLASS="verbatim">
+ merge = Name *.txt -> emacs -q --eval '(ediff-merge-files-with-ancestor
+ "CURRENT1" "CURRENT2" "CURRENTARCH" nil "NEW")'
+</PRE>(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.) <BR>
+<BR>
+Users running emacs under windows may find something like this useful:
+<PRE CLASS="verbatim">
+ merge = Name * -> C:\Progra~1\Emacs\emacs\bin\emacs.exe -q --eval
+ "(ediff-files """CURRENT1""" """CURRENT2""")"
+</PRE>
+Users running Mac OS X (you may need the Developer Tools installed to get
+the <TT>opendiff</TT> utility) may prefer
+<PRE CLASS="verbatim">
+ merge = Name *.txt -> opendiff CURRENT1 CURRENT2 -ancestor CURRENTARCH -merge NEW
+</PRE>Here is a slightly more involved hack. The <TT>opendiff</TT> program can
+operate either with or without an archive file. A merge command of this
+form
+<PRE CLASS="verbatim">
+ merge = Name *.txt ->
+ if [ CURRENTARCHOPTx = x ];
+ then opendiff CURRENT1 CURRENT2 -merge NEW;
+ else opendiff CURRENT1 CURRENT2 -ancestor CURRENTARCHOPT -merge NEW;
+ fi
+</PRE>(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 <TT>opendiff</TT>. <BR>
+<BR>
+Ordinarily, external merge programs are only invoked when Unison is <EM>not</EM> running in batch mode. To specify an external merge program that
+should be used no matter the setting of the <TT>batch</TT> flag, use the <TT>mergebatch</TT> preference instead of <TT>merge</TT>.
+<BLOCKQUOTE CLASS="quote">
+<I>Please post suggestions for other useful values of the
+</I><CODE><I>merge</I></CODE><I> preference to the <TT>unison-users</TT> mailing list—we'd like
+to give several examples here.
+</I></BLOCKQUOTE>
+<!--TOC subsection The User Interface-->
+
+<H3 CLASS="subsection"><A NAME="ui"></A>The User Interface</H3><!--SEC END -->
+
+Both the textual and the graphical user interfaces are intended to be
+mostly self-explanatory. Here are just a few tricks:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+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 “<CODE>></CODE>” to tell Unison to
+propagate a file from left to right, rather than “<CODE>></CODE> Enter.”)<BR>
+<BR>
+There are some situations, though, where this will not work — for
+example, when Unison is running in a shell window inside Emacs.
+Setting the <CODE>dumbtty</CODE> preference will force Unison to leave the
+terminal alone and process input a line at a time.
+</UL>
+<!--TOC subsection Exit code-->
+
+<H3 CLASS="subsection"><A NAME="exit"></A>Exit code</H3><!--SEC END -->
+
+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:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+0: successful synchronization; everything is up-to-date now.
+<LI CLASS="li-itemize">1: some files were skipped, but all file transfers were successful.
+<LI CLASS="li-itemize">2: non-fatal failures occurred during file transfer.
+<LI CLASS="li-itemize">3: a fatal error occurred, or the execution was interrupted.
+</UL>
+The graphical interface does not return any useful information through the
+exit status.<BR>
+<BR>
+<!--TOC subsection Path specification-->
+
+<H3 CLASS="subsection"><A NAME="pathspec"></A>Path specification</H3><!--SEC END -->
+
+Several Unison preferences (e.g., <CODE>ignore</CODE>/<CODE>ignorenot</CODE>,
+<CODE>follow</CODE>, <CODE>sortfirst</CODE>/<CODE>sortlast</CODE>, <CODE>backup</CODE>,
+<CODE>merge</CODE>, 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.
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+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 form
+<PRE>
+ ignore = <TT><I>pattern</I></TT>
+</PRE>
+adds <TT><I>pattern</I></TT> to the list of patterns to be ignored.<BR>
+<BR>
+<LI CLASS="li-itemize">Each <TT><I>pattern</I></TT> can have one of three forms. The most
+general form is a Posix extended regular expression introduced by the
+keyword <CODE>Regex</CODE>. (The collating sequences and character classes of
+full Posix regexps are not currently supported).
+<PRE>
+ Regex <TT><I>regexp</I></TT>
+</PRE>
+For convenience, three other styles of pattern are also recognized:
+<PRE>
+ Name <TT><I>name</I></TT>
+</PRE>
+matches any path in which the last component matches <TT><I>name</I></TT>,
+<PRE>
+ Path <TT><I>path</I></TT>
+</PRE>
+matches exactly the path <TT><I>path</I></TT>, and
+<PRE>
+ BelowPath <TT><I>path</I></TT>
+</PRE>
+matches the path <TT><I>path</I></TT> and any path below.
+The <TT><I>name</I></TT> and <TT><I>path</I></TT> arguments of the latter forms of
+patterns are <EM>not</EM> regular expressions. Instead,
+standard “globbing” conventions can be used in <TT><I>name</I></TT> and
+<TT><I>path</I></TT>:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+a <CODE>*</CODE> matches any sequence of characters not including <CODE>/</CODE>
+(and not beginning with <CODE>.</CODE>, when used at the beginning of a
+<TT><I>name</I></TT>)
+<LI CLASS="li-itemize">a <CODE>?</CODE> matches any single character except <CODE>/</CODE> (and leading
+ <CODE>.</CODE>)
+<LI CLASS="li-itemize"><CODE>[xyz]</CODE> matches any character from the set {<TT><I>x</I></TT>,
+ <TT><I>y</I></TT>, <TT><I>z</I></TT> }
+<LI CLASS="li-itemize"><CODE>{a,bb,ccc}</CODE> matches any one of <CODE>a</CODE>, <CODE>bb</CODE>, or
+ <CODE>ccc</CODE>.
+</UL>
+<LI CLASS="li-itemize">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.
+</UL>
+Some examples of path patterns appear in the <A HREF="#ignore">Ignoring
+ Paths</A> section.<BR>
+<BR>
+<!--TOC subsection Ignoring Paths-->
+
+<H3 CLASS="subsection"><A NAME="ignore"></A>Ignoring Paths</H3><!--SEC END -->
+
+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 <A HREF="#pathspec">Path Patterns</A> section.<BR>
+<BR>
+For example, the following pattern will make Unison ignore any
+path containing the name <CODE>CVS</CODE> or a name ending in <CODE>.cmo</CODE>:
+<PRE CLASS="verbatim">
+ ignore = Name {CVS,*.cmo}
+</PRE>The next pattern makes Unison ignore the path <CODE>a/b</CODE>:
+<PRE CLASS="verbatim">
+ ignore = Path a/b
+</PRE>Path patterns do <EM>not</EM> skip filesnames beginning with <CODE>.</CODE> (as Name
+patterns do). For example,
+<PRE CLASS="verbatim">
+ ignore = Path */tmp
+</PRE>will include <CODE>.foo/tmp</CODE> in the set of ignore directories, as it is a
+path, not a name, that is ignored.<BR>
+<BR>
+The following pattern makes Unison ignore any path beginning with <CODE>a/b</CODE>
+and ending with a name ending by <CODE>.ml</CODE>.
+<PRE CLASS="verbatim">
+ ignore = Regex a/b/.*\.ml
+</PRE>Note that regular expression patterns are “anchored”: they must
+match the whole path, not just a substring of the path.<BR>
+<BR>
+Here are a few extra points regarding the <TT>ignore</TT> preference.
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+If a directory is ignored, all its descendents will be too.<BR>
+<BR>
+<LI CLASS="li-itemize">The user interface provides some convenient commands for adding
+ new patterns to be ignored. To ignore a particular file, select it
+ and press “<TT>i</TT>”. To ignore all files with the same extension,
+ select it and press “<TT>E</TT>” (with the shift key). To ignore all
+ files with the same name, no matter what directory they appear in,
+ select it and press “<TT>N</TT>”.
+These new patterns become permanent: they
+are immediately added to the current profile on disk.<BR>
+<BR>
+<LI CLASS="li-itemize">If you use the <CODE>include</CODE> directive to include a common
+collection of preferences in several top-level preference files, you will
+probably also want to set the <CODE>addprefsto</CODE> 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. <BR>
+<BR>
+<LI CLASS="li-itemize">Ignore patterns can also be specified on the command line, if
+you like (this is probably not very useful), using an option like
+<CODE>-ignore 'Name temp.txt'</CODE>.<BR>
+<BR>
+<LI CLASS="li-itemize">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).<BR>
+<BR>
+<LI CLASS="li-itemize">There is also an <CODE>ignorenot</CODE> preference, which specifies a set of
+ patterns for paths that should <EM>not</EM> be ignored, even if they match an
+ <CODE>ignore</CODE> pattern. However, the interaction of these two sets of
+ patterns can be a little tricky. Here is exactly how it works:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+ Unison starts detecting updates from the root of the
+ replicas—i.e., from the empty path. If the empty path matches an
+ <CODE>ignore</CODE> pattern and does not match an <CODE>ignorenot</CODE> pattern, then
+ the whole replica will be ignored. (For this reason, it is not a good
+ idea to include <CODE>Name *</CODE> as an <CODE>ignore</CODE> pattern. If you want to
+ ignore everything except a certain set of files, use <CODE>Name ?*</CODE>.)
+ <LI CLASS="li-itemize">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
+ <CODE>ignore</CODE> pattern and does not match an <CODE>ignorenot</CODE> pattern, then
+ this whole path <EM>including everything below it</EM> will be ignored.
+ <LI CLASS="li-itemize">If any of the non-ignored children are directories, then the process
+ continues recursively.
+ </UL>
+</UL>
+<!--TOC subsection Symbolic Links-->
+
+<H3 CLASS="subsection"><A NAME="symlinks"></A>Symbolic Links</H3><!--SEC END -->
+
+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.<BR>
+<BR>
+It is sometimes useful to treat a symbolic link “transparently,”
+acting as though whatever it points to were physically <EM>in</EM> 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 form
+<PRE>
+ follow = <TT><I>pathspec</I></TT>
+</PRE>
+to the profile, where <TT><I>pathspec</I></TT> is a path pattern as described in
+the <A HREF="#pathspec">Path Patterns</A> section.<BR>
+<BR>
+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
+<CODE>ignore</CODE> pattern or a <CODE>follow</CODE> pattern.<BR>
+<BR>
+<!--TOC subsection Permissions-->
+
+<H3 CLASS="subsection"><A NAME="perms"></A>Permissions</H3><!--SEC END -->
+
+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:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+When the permission bits of an existing file or directory are
+changed, the values of those bits that make sense on <EM>both</EM>
+operating systems will be propagated to the other replica. The other
+bits will not be changed.
+<LI CLASS="li-itemize">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).
+<LI CLASS="li-itemize">For security reasons, the Unix <CODE>setuid</CODE> and <CODE>setgid</CODE>
+bits are not propagated.
+<LI CLASS="li-itemize">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.
+</UL>
+<!--TOC subsection Cross-Platform Synchronization-->
+
+<H3 CLASS="subsection"><A NAME="crossplatform"></A>Cross-Platform Synchronization</H3><!--SEC END -->
+
+If you use Unison to synchronize files between Windows and Unix
+systems, there are a few special issues to be aware of.<BR>
+<BR>
+<B>Case conflicts.</B> In Unix, filenames are case sensitive:
+<TT>foo</TT> and <TT>FOO</TT> can refer to different files. In
+Windows, on the other hand, filenames are not case sensitive:
+<TT>foo</TT> and <TT>FOO</TT> can only refer to the same file. This
+means that a Unix <TT>foo</TT> and <TT>FOO</TT> 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. <BR>
+<BR>
+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 <A HREF="#ignore">Ignore</A> section).<BR>
+<BR>
+<B>Illegal filenames.</B> 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 <TT>foo:bar</TT> 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.<BR>
+<BR>
+<!--TOC subsection Slow Links-->
+
+<H3 CLASS="subsection"><A NAME="speed"></A>Slow Links</H3><!--SEC END -->
+
+Unison is built to run well even over relatively slow links such as
+modems and DSL connections. <BR>
+<BR>
+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 (<A HREF="http://samba.anu.edu.au/rsync/"><TT>http://samba.anu.edu.au/rsync/</TT></A>).<BR>
+<BR>
+If you are using Unison with <TT>ssh</TT>, you may get some speed
+improvement by enabling <TT>ssh</TT>'s compression feature. Do this by
+adding the option “<TT>-sshargs -C</TT>” to the command line or “<TT>sshargs = -C</TT>” to your profile. <BR>
+<BR>
+<!--TOC subsection Making Unison Faster on Large Files-->
+
+<H3 CLASS="subsection"><A NAME="speeding"></A>Making Unison Faster on Large Files</H3><!--SEC END -->
+
+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.<BR>
+<BR>
+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 <TT>rsync</TT> tool, which is available
+by default on most Unix systems and can easily be installed on Windows
+systems using Cygwin.<BR>
+<BR>
+If you have <TT>rsync</TT> installed on both hosts, you can make Unison use it
+simply by setting the <TT>copythreshold</TT> flag to something non-negative.
+If you set it to 0, Unison will use the external copy utility for <EM>all</EM>
+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).<BR>
+<BR>
+If you want to use a different external copy utility, set both the <TT>copyprog</TT> and <TT>copyprogpartial</TT> 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:
+<PRE CLASS="verbatim">
+ copyprog = rsync --inplace --compress
+ copyprogrest = rsync --partial --inplace --compress
+</PRE>You may also need to set the <TT>copyquoterem</TT> preference. When it is set
+to <TT>true</TT>, 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
+<TT>default</TT>, extra quotes are added if the value of <TT>copyprog</TT>
+contains the string <TT>rsync</TT>. The default value is <TT>default</TT>,
+naturally.<BR>
+<BR>
+If a <EM>directory</EM> 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 <TT>copythreshold</TT> 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 <TT>.unison.DIRNAME....</TT>) until the transfer is
+complete.<BR>
+<BR>
+<!--TOC subsection Fast Update Detection-->
+
+<H3 CLASS="subsection"><A NAME="fastcheck"></A>Fast Update Detection</H3><!--SEC END -->
+
+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 <TT>fastcheck</TT> that, when set to
+<CODE>true</CODE>, 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. <BR>
+<BR>
+When <CODE>fastcheck</CODE> is set to <CODE>no</CODE>,
+Unison will perform slow checking—re-scanning the contents of each file
+on each synchronization—on all replicas. When <CODE>fastcheck</CODE> is set
+to <CODE>default</CODE> (which, naturally, is the default), Unison will use
+fast checks on Unix replicas and slow checks on Windows replicas.<BR>
+<BR>
+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 <EM>overwrite</EM> 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 <TT>fastcheck</TT> set to <CODE>no</CODE>, if you are worried that Unison may have
+overlooked an update.<BR>
+<BR>
+Fastcheck is (always) automatically disabled for files with extension
+<CODE>.xls</CODE> or <CODE>.mpp</CODE>, to prevent Unison from being confused by the
+habits of certain programs (Excel, in particular) of updating files without
+changing their modification times.<BR>
+<BR>
+<!--TOC subsection Mount Points and Removable Media-->
+
+<H3 CLASS="subsection"><A NAME="mountpoints"></A>Mount Points and Removable Media</H3><!--SEC END -->
+
+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!<BR>
+<BR>
+To prevent accidents, Unison provides a preference called
+<CODE>mountpoint</CODE>. Including a line like
+<PRE CLASS="verbatim">
+ mountpoint = foo
+</PRE>in your preference file will cause Unison to check, after it finishes
+detecting updates, that something actually exists at the path
+<CODE>foo</CODE> on both replicas; if it does not, the Unison run will
+abort. <BR>
+<BR>
+<!--TOC subsection Click-starting Unison-->
+
+<H3 CLASS="subsection"><A NAME="click"></A>Click-starting Unison</H3><!--SEC END -->
+
+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, <EM>as long as you are not using ssh</EM>.
+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.<BR>
+<BR>
+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.<BR>
+<BR>
+To use Unison in this mode, you must first create a profile (see
+the <A HREF="#profile">Profile</A> section). Use your favorite editor for this. <BR>
+<BR>
+<hr><!--TOC section Installing Ssh-->
+
+<H2 CLASS="section"><A NAME="ssh"></A>Installing Ssh</H2><!--SEC END -->
+
+<EM>Warning: These instructions may be out of date. More current
+ information can be found the
+ </EM><A HREF="http://alliance.seas.upenn.edu/ bcpierce/wiki/index.php?n=Main.UnisonFAQOSSpecific"><EM>Unison
+ Wiki</EM></A><EM>.</EM><BR>
+<BR>
+Your local host will need just an ssh client; the remote host needs an
+ssh server (or daemon), which is available on Unix systems. Unison is
+known to work with ssh version 1.2.27 (Unix) and version 1.2.14
+(Windows); other versions may or may not work.<BR>
+<BR>
+<!--TOC subsection Unix-->
+
+<H3 CLASS="subsection"><A NAME="ssh-unix"></A>Unix</H3><!--SEC END -->
+
+Most modern Unix installations come with <CODE>ssh</CODE> pre-installed.<BR>
+<BR>
+<!--TOC subsection Windows-->
+
+<H3 CLASS="subsection"><A NAME="ssh-win"></A>Windows</H3><!--SEC END -->
+
+Many Windows implementations of ssh only provide graphical interfaces,
+but Unison requires an ssh client that it can invoke with a
+command-line interface. A suitable version of ssh can be installed as
+follows.
+<OL CLASS="enumerate" type=1><LI CLASS="li-enumerate">
+Download an <CODE>ssh</CODE> executable. <BR>
+<BR>
+Warning: there are many implementations and ports of ssh for
+Windows, and not all of them will work with Unison. We have gotten
+Unison to work with Cygwin's port of openssh, and we suggest you try
+that one first. Here's how to install it:
+<OL CLASS="enumerate" type=a><LI CLASS="li-enumerate">
+First, create a new folder on your desktop to hold temporary
+ installation files. It can have any name you like, but in these
+ instructions we'll assume that you call it <CODE>Foo</CODE>.
+<LI CLASS="li-enumerate">Direct your web browser to www.cygwin.com, and click on the
+ “Install now!” link. This will download a file, <CODE>setup.exe</CODE>;
+ save it in the directory <CODE>Foo</CODE>. The file <CODE>setup.exe</CODE> is a
+ small program that will download the actual install files from
+ the Internet when you run it.
+<LI CLASS="li-enumerate">Start <CODE>setup.exe</CODE> (by double-clicking). This brings up a
+ series of dialogs that you will have to go through. Select
+ “Install from Internet.” For “Local Package Directory” select
+ the directory <CODE>Foo</CODE>. For “Select install root directory” we
+ recommend that you use the default, <CODE>C:\cygwin</CODE>. The next
+ dialog asks you to select the way that you want to connect to the
+ network to download the installation files; we have used “Use IE5
+ Settings” successfully, but you may need to make a different
+ selection depending on your networking setup. The next dialog gives
+ a list of mirrors; select one close to you.<BR>
+<BR>
+Next you are asked to select which packages to install. The default
+ settings in this dialog download a lot of packages that are not
+ strictly necessary to run Unison with ssh. If you don't want to
+ install a package, click on it until “skip” is shown. For a
+ minimum installation, select only the packages “cygwin” and
+ “openssh,” which come to about 1900KB; the full installation is
+ much larger.
+<BLOCKQUOTE CLASS="quote"> <EM>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.
+ </EM></BLOCKQUOTE>
+After the packages are downloaded and installed, the next dialog
+ allows you to choose whether to “Create Desktop Icon” and “Add to
+ Start Menu.” You make the call.
+<LI CLASS="li-enumerate">You can now delete the directory <CODE>Foo</CODE> and its contents.
+</OL>
+Some people have reported problems using Cygwin's ssh with Unison. If
+you have trouble, you might try this one instead:
+<PRE CLASS="verbatim">
+ http://opensores.thebunker.net/pub/mirrors/ssh/contrib/ssh-1.2.14-win32bin.zip
+</PRE><BR>
+<BR>
+<LI CLASS="li-enumerate">You must set the environment variables HOME and PATH.
+ Ssh will create a directory <CODE>.ssh</CODE> in the directory given
+ by HOME, so that it has a place to keep data like your public and
+ private keys. PATH must be set to include the Cygwin <CODE>bin</CODE>
+ directory, so that Unison can find the ssh executable.
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+ On Windows 95/98, add the lines
+<PRE CLASS="verbatim">
+ set PATH=%PATH%;<SSHDIR>
+ set HOME=<HOMEDIR>
+</PRE>to the file <CODE>C:\AUTOEXEC.BAT</CODE>, where <CODE><HOMEDIR></CODE> is the
+ directory where you want ssh to create its <CODE>.ssh</CODE> directory,
+ and <CODE><SSHDIR></CODE> is the directory where the executable
+ <CODE>ssh.exe</CODE> is stored; if you've installed Cygwin in the
+ default location, this is <CODE>C:\cygwin\bin</CODE>. You will have to
+ reboot your computer to take the changes into account.
+ <LI CLASS="li-itemize">On Windows NT/2k/XP, open the environment variables dialog box:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+ Windows NT: My Computer/Properties/Environment
+ <LI CLASS="li-itemize">Windows 2k: My Computer/Properties/Advanced/Environment
+ variables
+ </UL>
+ then select Path and edit its value by appending <CODE>;<SSHDIR></CODE>
+ to it, where <CODE><SSHDIR></CODE> is the full name of the directory
+ that includes the ssh executable; if you've installed Cygwin in
+ the default location, this is <CODE>C:\cygwin\bin</CODE>.
+ </UL>
+ <LI CLASS="li-enumerate">Test ssh from a DOS shell by typing
+<PRE CLASS="verbatim">
+ ssh <remote host> -l <login name>
+</PRE>You should get a prompt for your password on <CODE><remote host></CODE>,
+ followed by a working connection.
+ <LI CLASS="li-enumerate">Note that <CODE>ssh-keygen</CODE> may not work (fails with
+ “gethostname: no such file or directory”) on some systems. This is
+ OK: you can use ssh with your regular password for the remote
+ system.
+<LI CLASS="li-enumerate">You should now be able to use Unison with an ssh connection. If
+ you are logged in with a different user name on the local and remote
+ hosts, provide your remote user name when providing the remote root
+ (i.e., <CODE>//username at host/path...</CODE>).
+</OL>
+<hr><!--TOC section Changes in Version 2.40.61-->
+
+<H2 CLASS="section"><A NAME="news"></A>Changes in Version 2.40.61</H2><!--SEC END -->
+
+Changes since 2.40.1:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Added "BelowPath" patterns, that match a path as well as all paths below
+ (convenient to use with nodeletion,update,creationpartial preferences)
+<LI CLASS="li-itemize">Added a "fat" preference that makes Unison use the right options
+ when one of the replica is on a FAT filesystem.
+<LI CLASS="li-itemize">Allow "prefer/force=newer" even when not synchronizing modification
+ times. (The reconciler will not be aware of the modification time
+ of unchanged files, so the synchronization choices of Unison can be
+ different from when "times=true", but the behavior remains sane:
+ changed files with the most recent modification time will be
+ propagated.)
+<LI CLASS="li-itemize">Minor fixes and improvements:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Compare filenames up to decomposition in case sensitive mode when
+ one host is running MacOSX and the unicode preference is set to
+ true.
+<LI CLASS="li-itemize">Rsync: somewhat faster compressor
+<LI CLASS="li-itemize">Make Unicode the default on all architectures (it was only the
+ default when a Mac OS X or Windows machine was involved).
+</UL>
+
+ </UL>
+
+Changes since 2.32:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Major enhancement: Unicode support.
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Unison should now handle unicode filenames correctly on all platforms.
+<LI CLASS="li-itemize">This functionality is controlled by a new preference <TT>unicode</TT>.
+<LI CLASS="li-itemize">Unicode mode is now the default when one of the hosts is under
+ Windows or MacOS. This may make upgrades a bit more painful (the
+ archives cannot be reused), but this is a much saner default.
+</UL>
+<LI CLASS="li-itemize">Partial transfer of directories. If an error occurs while
+ transferring a directory, the part transferred so far is copied into
+ place (and the archives are updated accordingly).
+ The "maxerrors" preference controls how many transfer error Unison
+ will accept before stopping the transfer of a directory (by default,
+ only one). This makes it possible to transfer most of a directory
+ even if there are some errors. Currently, only the first error is
+ reported by the GUIs.<BR>
+<BR>
+Also, allow partial transfer of a directory when there was an error deep
+ inside this directory during update detection. At the moment, this
+ is only activated with the text and GTK UIs, which have been
+ modified so that they show that the transfer is going to be partial
+ and so that they can display all errors.
+<LI CLASS="li-itemize">Improvement to the code for resuming directory transfers:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+if a file was not correctly transferred (or the source has been
+ modified since, with unchanged size), Unison performs a new
+ transfer rather than failing
+ <LI CLASS="li-itemize">spurious files are deleted (this can happen if a file is deleted
+ on the source replica before resuming the transfer; not deleting
+ the file would result in it reappearing on the target replica)
+</UL>
+<LI CLASS="li-itemize">Experimental streaming protocol for transferring file contents (can
+ be disabled by setting the directive "stream" to false): file
+ contents is transfered asynchronously (without waiting for a response
+ from the destination after each chunk sent) rather than using the
+ synchronous RPC mechanism. As a consequence:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+ Unison now transfers the contents of a single file at a time
+ (Unison used to transfer several contents simultaneously in order
+ to hide the connection latency.)
+ <LI CLASS="li-itemize">the transfer of large files uses the full available bandwidth
+ and is not slowed done due to the connection latency anymore
+ <LI CLASS="li-itemize">we get performance improvement for small files as well by
+ scheduling many files simultaneously (as scheduling a file for
+ transfer consume little ressource: it does not mean allocating a
+ large buffer anymore)
+ </UL>
+<LI CLASS="li-itemize">Changes to the internal implementation of the rsync algorithm:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+use longer blocks for large files (the size of a block is the
+ square root of the size of the file for large files);
+ <LI CLASS="li-itemize">transmit less checksum information per block (we still have less
+ than one chance in a hundred million of transferring a file
+ incorrectly, and Unison will catch any transfer error when
+ fingerprinting the whole file)
+ <LI CLASS="li-itemize">avoid transfer overhead (which was 4 bytes per block)
+</UL>
+ For a 1G file, the first optimization saves a factor 50 on the
+ amount of data transferred from the target to the source (blocks
+ are 32768 bytes rather than just 700 bytes). The two other
+ optimizations save another factor of 2 (from 24 bytes per block
+ down to 10).
+<LI CLASS="li-itemize">Implemented an on-disk file fingerprint cache to speed-up update
+ detection after a crash: this way, Unison does not have do recompute
+ all the file fingerprints from scratch.
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+ When Unison detects that the archive case-sensitivity mode
+ does not match the current settings, it populates the fingerprint
+ cache using the archive contents. This way, changing the
+ case-sensitivity mode should be reasonably fast.
+ </UL>
+<LI CLASS="li-itemize">New preferences "noupdate=root", "nodeletion=root", "nocreation=root"
+ that prevent Unison from performing files updates, deletions or
+ creations on the given root. Also 'partial' versions of 'noupdate',
+ 'nodeletion' and 'nocreation'
+<LI CLASS="li-itemize">Limit the number of simultaneous external copy program
+ ("copymax" preference)
+<LI CLASS="li-itemize">New "links" preference. When set to false, Unison will report an
+ error on symlinks during update detection. (This is the default
+ when one host is running Windows but not Cygwin.) This is better
+ than failing during propagation.
+<LI CLASS="li-itemize">Added a preference "halfduplex" to force half-duplex communication
+ with the server. This may be useful on unreliable links (as a more
+ efficient alternative to "maxthreads = 1").
+<LI CLASS="li-itemize">Renamed preference "pretendwin" to "ignoreinodenumbers" (an alias is
+ kept for backwards compatibility).
+<LI CLASS="li-itemize">Ignore one-second differences when synchronizing modification time.
+ (Technically, this is an incompatible archive format change, but it
+ is backward compatible. To trigger a problem, a user would have to
+ synchronize modification times on a filesystem with a two-second
+ granularity and then downgrade to a previous version of Unison,
+ which does not work well in such a case. Thus, it does not
+ seem worthwhile to increment the archive format number, which would
+ impact all users.)
+<LI CLASS="li-itemize">Do not keep many files simultaneously opened anymore when the rsync
+ algorithm is in use.
+<LI CLASS="li-itemize">Add “ignorearchives” preference to ignore existing archives (to
+ avoid forcing users to delete them manually, in situations where one
+ archive has gotten deleted or corrupted).
+<LI CLASS="li-itemize">Mac OS
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+fixed rsync bug which could result in an "index out of bounds"
+ error when transferring resource forks.
+<LI CLASS="li-itemize">Fixed bug which made Unison ignore finder information and resource
+ fork when compiled to 64bit on Mac OSX.
+<LI CLASS="li-itemize">should now be 64 bit clean (the Growl framework is not up to date,
+ though)
+<LI CLASS="li-itemize">Made the bridge between Objective C and Ocaml code GC friendly
+ (it was allocating ML values and putting them in an array which
+ was not registered with the GC)
+<LI CLASS="li-itemize">use darker grey arrows (patch contributed by Eric Y. Kow)
+</UL>
+<LI CLASS="li-itemize">GTK user interface
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+assistant for creating profiles
+<LI CLASS="li-itemize">profile editor
+<LI CLASS="li-itemize">pop up a summary window when the replicas are not fully
+ synchronized after transport
+<LI CLASS="li-itemize">display estimated remaining time and transfer rate on the
+ progress bar
+<LI CLASS="li-itemize">allow simultaneous selection of several items
+<LI CLASS="li-itemize">Do not reload the preference file before a new update
+ detection if it is unchanged
+<LI CLASS="li-itemize">disabled scrolling to the first unfinished item during transport.
+ It goes way too fast when lot of small files are synchronized, and it
+ makes it impossible to browse the file list during transport.
+<LI CLASS="li-itemize">take into account the "height" preference again
+<LI CLASS="li-itemize">the internal list of selected reconciler item was not always in
+ sync with what was displayed (GTK bug?); workaround implemented
+<LI CLASS="li-itemize">Do not display "Looking for change" messages during propagation
+ (when checking the targe is unchanged) but only during update detection
+<LI CLASS="li-itemize">Apply patch to fix some crashes in the OSX GUI, thanks to Onne Gorter.
+</UL>
+<LI CLASS="li-itemize">Text UI
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+During update detection, display status by updating a single line
+rather than generating a new line of output every so often. Should be less
+confusing.
+</UL>
+<LI CLASS="li-itemize">Windows
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Fastcheck is now the default under Windows. People mostly use NTFS
+ nowadays and the Unicode API provides an equivalent to inode numbers
+ for this filesystem.
+<LI CLASS="li-itemize">Only use long UNC path for accessing replicas (as '..' is
+ not handled with this format of paths, but can be useful)
+<LI CLASS="li-itemize">Windows text UI: now put the console into UTF-8 output mode. This
+ is the right thing to do when in Unicode mode, and is no worse than
+ what we had previously otherwise (the console use some esoteric
+ encoding by default). This only works when using a Unicode font
+ instead of the default raster font.
+<LI CLASS="li-itemize">Don't get the home directory from environment variable HOME under
+ Windows (except for Cygwin binaries): we don't want the behavior of
+ Unison to depends on whether it is run from a Cygwin shell (where
+ HOME is set) or in any other way (where HOME is usually not set).
+</UL>
+<LI CLASS="li-itemize">Miscellaneous fixes and improvements
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Made a server waiting on a socket more resilient to unexpected
+ lost connections from the client.
+<LI CLASS="li-itemize">Small patch to property setting code suggested by Ulrich Gernkow.
+<LI CLASS="li-itemize">Several fixes to the change transfer functions (both the internal ones
+ and external transfers using rsync). In particular, limit the number of
+ simultaneous transfer using an rsync
+ (as the rsync algorithm can use a large amount of memory when
+ processing huge files)
+<LI CLASS="li-itemize">Keep track of which file contents are being transferred, and delay
+ the transfer of a file when another file with the same contents is
+ currently being transferred. This way, the second transfer can be
+ skipped and replaced by a local copy.
+<LI CLASS="li-itemize">Experimental update detection optimization:
+ do not read the contents of unchanged directories
+<LI CLASS="li-itemize">When a file transfer fails, turn off fastcheck for this file on the
+ next sync.
+<LI CLASS="li-itemize">Fixed bug with case insensitive mode on a case sensitive filesystem:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+if file "a/a" is created on one replica and directory "A" is
+ created on the other, the file failed to be synchronized the first
+ time Unison is run afterwards, as Unison uses the wrong path "a/a"
+ (if Unison is run again, the directories are in the archive, so
+ the right path is used);
+ <LI CLASS="li-itemize">if file "a" appears on one replica and file "A" appears on the
+ other with different contents, Unison was unable to synchronize
+ them.
+</UL>
+<LI CLASS="li-itemize">Improved error reporting when the destination is updated during
+ synchronization: Unison now tells which file has been updated, and how.
+<LI CLASS="li-itemize">Limit the length of temporary file names
+<LI CLASS="li-itemize">Case sensitivity information put in the archive (in a backward
+ compatible way) and checked when the archive is loaded
+<LI CLASS="li-itemize">Got rid of the 16mb marshalling limit by marshalling to a bigarray.
+<LI CLASS="li-itemize">Resume copy of partially transferred files.
+</UL>
+
+ </UL>
+
+Changes since 2.31:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Small user interface changes
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Small change to text UI "scanning..." messages, to print just
+ directories (hopefully making it clearer that individual files are
+ not necessarily being fingerprinted).
+</UL>
+<LI CLASS="li-itemize">Minor fixes and improvements:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Ignore one hour differences when deciding whether a file may have
+ been updated. This avoids slow update detection after daylight
+ saving time changes under Windows. This makes Unison slightly more
+ likely to miss an update, but it should be safe enough.
+<LI CLASS="li-itemize">Fix a small bug that was affecting mainly windows users. We need to
+ commit the archives at the end of the sync even if there are no
+ updates to propagate because some files (in fact, if we've just
+ switched to DST on windows, a LOT of files) might have new modtimes
+ in the archive. (Changed the text UI only. It's less clear where
+ to change the GUI.)
+<LI CLASS="li-itemize">Don't delete the temp file when a transfer fails due to a
+ fingerprint mismatch (so that we can have a look and see why!) We've also
+ added more debugging code togive more informative error messages when we
+ encounter the dreaded and longstanding "assert failed during file
+ transfer" bug
+<LI CLASS="li-itemize">Incorrect paths ("path" directive) now result in an error update
+ item rather than a fatal error.
+<LI CLASS="li-itemize">Create parent directories (with correct permissions) during
+ transport for paths which point to non-existent locations in the
+ destination replica.
+</UL>
+
+ </UL>
+
+Changes since 2.27:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+If Unison is interrupted during a directory transfer, it will now
+leave the partially transferred directory intact in a temporary
+location. (This maintains the invariant that new files/directories are
+transferred either completely or not at all.) The next time Unison is run,
+it will continue filling in this temporary directory, skipping transferring
+files that it finds are already there.
+<LI CLASS="li-itemize">We've added experimental support for invoking an external file
+transfer tool for whole-file copies instead of Unison's built-in transfer
+protocol. Three new preferences have been added:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+<TT>copyprog</TT> is a string giving the name (and command-line
+switches, if needed) of an external program that can be used to copy large
+files efficiently. By default, rsync is invoked, but other tools such as
+scp can be used instead by changing the value of this preference. (Although
+this is not its primary purpose, rsync is actually a pretty fast way of
+copying files that don't already exist on the receiving host.) For files
+that do already exist on (but that have been changed in one replica), Unison
+will always use its built-in implementation of the rsync algorithm.
+<LI CLASS="li-itemize">Added a "copyprogrest" preference, so that we can give different
+command lines for invoking the external copy utility depending on whether a
+partially transferred file already exists or not. (Rsync doesn't seem to
+care about this, but other utilities may.)
+<LI CLASS="li-itemize"><TT>copythreshold</TT> is an integer (-1 by default), indicating above what
+filesize (in megabytes) Unison should use the external copying utility
+specified by copyprog. Specifying 0 will cause ALL copies to use the
+external program; a negative number will prevent any files from using it.
+(Default is -1.)
+</UL>
+Thanks to Alan Schmitt for a huge amount of hacking and to an anonymous
+sponsor for suggesting and underwriting this extension.
+<LI CLASS="li-itemize">Small improvements:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Added a new preference, <TT>dontchmod</TT>. By default, Unison uses the
+<TT>chmod</TT> 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 <TT>chmod</TT>.
+<LI CLASS="li-itemize">Don't ignore files that look like backup files if the <TT>backuplocation</TT> preference is set to <TT>central</TT>
+<LI CLASS="li-itemize">Shortened the names of several preferences. The old names are also
+still supported, for backwards compatibility, but they do not appear in the
+documentation.
+<LI CLASS="li-itemize">Lots of little documentation tidying. (In particular, preferences are
+separated into Basic and Advanced! This should hopefully make Unison a
+little more approachable for new users.
+<LI CLASS="li-itemize">Unison can sometimes fail to transfer a file, giving the unhelpful
+message "Destination updated during synchronization" even though the file
+has not been changed. This can be caused by programs that change either the
+file's contents <EM>or</EM> the file's extended attributes without changing
+its modification time. It's not clear what is the best fix for this – it
+is not Unison's fault, but it makes Unison's behavior puzzling – but at
+least Unison can be more helpful about suggesting a workaround (running once
+with <TT>fastcheck</TT> set to false). The failure message has been changed to
+give this advice.
+<LI CLASS="li-itemize">Further improvements to the OS X GUI (thanks to Alan Schmitt and Craig
+Federighi).
+</UL>
+<LI CLASS="li-itemize">Very preliminary support for triggering Unison from an external
+ filesystem-watching utility. The current implementation is very
+ simple, not efficient, and almost completely untested—not ready
+ for real users. But if someone wants to help improve it (e.g.,
+ by writing a filesystem watcher for your favorite OS), please make
+ yourself known!<BR>
+<BR>
+On the Unison side, the new behavior is very simple:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+ use the text UI
+ <LI CLASS="li-itemize">start Unison with the command-line flag "-repeat FOO",
+ where FOO is name of a file where Unison should look
+ for notifications of changes
+ <LI CLASS="li-itemize">when it starts up, Unison will read the whole contents
+ of this file (on both hosts), which should be a
+ newline-separated list of paths (relative to the root
+ of the synchronization) and synchronize just these paths,
+ as if it had been started with the "-path=xxx" option for
+ each one of them
+ <LI CLASS="li-itemize">when it finishes, it will sleep for a few seconds and then
+ examine the watchfile again; if anything has been added, it
+ will read the new paths, synchronize them, and go back to
+ sleep
+ <LI CLASS="li-itemize">that's it!
+ </UL>
+ To use this to drive Unison "incrementally," just start it in
+ this mode and start up a tool (on each host) to watch for
+ new changes to the filesystem and append the appropriate paths
+ to the watchfile. Hopefully such tools should not be too hard
+ to write.
+<LI CLASS="li-itemize">Bug fixes:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Fixed a bug that was causing new files to be created with
+ permissions 0x600 instead of using a reasonable default (like
+ 0x644), if the 'perms' flag was set to 0. (Bug reported by Ben
+ Crowell.)
+<LI CLASS="li-itemize">Follow maxthreads preference when transferring directories.
+</UL>
+
+ </UL>
+
+Changes since 2.17:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Major rewrite and cleanup of the whole Mac OS X graphical user
+interface by Craig Federighi. Thanks, Craig!!!
+<LI CLASS="li-itemize">Small fix to ctime (non-)handling in update detection under windows
+ with fastcheck.
+<LI CLASS="li-itemize">Several small fixes to the GTK2 UI to make it work better under
+Windows [thanks to Karl M for these].
+<LI CLASS="li-itemize">The backup functionality has been completely rewritten. The external
+interface has not changed, but numerous bugs, irregular behaviors, and
+cross-platform inconsistencies have been corrected.
+<LI CLASS="li-itemize">The Unison project now accepts donations via PayPal. If you'd like to
+donate, you can find a link to the donation page on the
+<A HREF="http://www.cis.upenn.edu/ bcpierce/unison/lists.html">Unison home
+ page</A>.
+<LI CLASS="li-itemize">Some important safety improvements:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Added a new <CODE>mountpoint</CODE> preference, which can be used to specify
+a path that must exist in both replicas at the end of update detection
+(otherwise Unison aborts). This can be used to avoid potentially dangerous
+situations when Unison is used with removable media such as external hard
+drives and compact flash cards.
+<LI CLASS="li-itemize">The confirmation of “big deletes” is now controlled by a boolean preference
+ <CODE>confirmbigdeletes</CODE>. Default is true, which gives the same behavior as
+ previously. (This functionality is at least partly superceded by the
+ <CODE>mountpoint</CODE> preference, but it has been left in place in case it is
+ useful to some people.)
+ <LI CLASS="li-itemize">If Unison is asked to “follow” a symbolic link but there is
+ nothing at the other end of the link, it will now flag this path as an
+ error, rather than treating the symlink itself as missing or deleted.
+ This avoids a potentially dangerous situation where a followed symlink
+ points to an external filesystem that might be offline when Unison is run
+ (whereupon Unison would cheerfully delete the corresponding files in the
+ other replica!).
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">Smaller changes:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Added <CODE>forcepartial</CODE> and <CODE>preferpartial</CODE> preferences, which
+behave like <CODE>force</CODE> and <CODE>prefer</CODE> but can be specified on a
+per-path basis. [Thanks to Alan Schmitt for this.]
+<LI CLASS="li-itemize">A bare-bones self test feature was added, which runs unison through
+ some of its paces and checks that the results are as expected. The
+ coverage of the tests is still very limited, but the facility has already
+ been very useful in debugging the new backup functionality (especially in
+ exposing some subtle cross-platform issues).
+<LI CLASS="li-itemize">Refined debugging code so that the verbosity of individual modules
+ can be controlled separately. Instead of just putting '-debug
+ verbose' on the command line, you can put '-debug update+', which
+ causes all the extra messages in the Update module, but not other
+ modules, to be printed. Putting '-debug verbose' causes all modules
+ to print with maximum verbosity.
+<LI CLASS="li-itemize">Removed <CODE>mergebatch</CODE> preference. (It never seemed very useful, and
+ its semantics were confusing.)
+<LI CLASS="li-itemize">Rewrote some of the merging functionality, for better cooperation
+ with external Harmony instances.
+<LI CLASS="li-itemize">Changed the temp file prefix from <CODE>.#</CODE> to <CODE>.unison</CODE>.
+<LI CLASS="li-itemize">Compressed the output from the text user interface (particularly
+ when run with the <CODE>-terse</CODE> flag) to make it easier to interpret the
+ results when Unison is run several times in succession from a script.
+<LI CLASS="li-itemize">Diff and merge functions now work under Windows.
+<LI CLASS="li-itemize">Changed the order of arguments to the default diff command (so that
+ the + and - annotations in diff's output are reversed).
+<LI CLASS="li-itemize">Added <CODE>.mpp</CODE> files to the “never fastcheck” list (like
+<CODE>.xls</CODE> files).
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">Many small bugfixes, including:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Fixed a longstanding bug regarding fastcheck and daylight saving time
+ under Windows when Unison is set up to synchronize modification times.
+ (Modification times cannot be updated in the archive in this case,
+ so we have to ignore one hour differences.)
+<LI CLASS="li-itemize">Fixed a bug that would occasionally cause the archives to be left in
+ non-identical states on the two hosts after synchronization.
+<LI CLASS="li-itemize">Fixed a bug that prevented Unison from communicating correctly between
+ 32- and 64-bit architectures.
+<LI CLASS="li-itemize">On windows, file creation times are no longer used as a proxy for
+ inode numbers. (This is unfortunate, as it makes fastcheck a little less
+ safe. But it turns out that file creation times are not reliable
+ under Windows: if a file is removed and a new file is created in its
+ place, the new one will sometimes be given the same creation date as the
+ old one!)
+<LI CLASS="li-itemize">Set read-only file to R/W on OSX before attempting to change other attributes.
+<LI CLASS="li-itemize">Fixed bug resulting in spurious "Aborted" errors during transport
+(thanks to Jerome Vouillon)
+<LI CLASS="li-itemize">Enable diff if file contents have changed in one replica, but
+only properties in the other.
+<LI CLASS="li-itemize">Removed misleading documentation for 'repeat' preference.
+<LI CLASS="li-itemize">Fixed a bug in merging code where Unison could sometimes deadlock
+ with the external merge program, if the latter produced large
+ amounts of output.
+<LI CLASS="li-itemize">Workaround for a bug compiling gtk2 user interface against current versions
+ of gtk2+ libraries.
+<LI CLASS="li-itemize">Added a better error message for "ambiguous paths".
+<LI CLASS="li-itemize">Squashed a longstanding bug that would cause file transfer to fail
+ with the message “Failed: Error in readWrite: Is a directory.”
+<LI CLASS="li-itemize">Replaced symlinks with copies of their targets in the Growl framework in src/uimac.
+ This should make the sources easier to check out from the svn repository on WinXP
+ systems.
+<LI CLASS="li-itemize">Added a workaround (suggested by Karl M.) for the problem discussed
+ on the unison users mailing list where, on the Windows platform, the
+ server would hang when transferring files. I conjecture that
+ the problem has to do with the RPC mechanism, which was used to
+ make a call <EM>back</EM> from the server to the client (inside the Trace.log
+ function) so that the log message would be appended to the log file on
+ the client. The workaround is to dump these messages (about when
+ xferbycopying shortcuts are applied and whether they succeed) just to the
+ standard output of the Unison process, not to the log file.
+</UL>
+
+ </UL>
+
+Changes since 2.13.0:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+The features for performing backups and for invoking external merge
+programs have been completely rewritten by Stephane Lescuyer (thanks,
+Stephane!). The user-visible functionality should not change, but the
+internals have been rationalized and there are a number of new features.
+See the manual (in particular, the description of the <CODE>backupXXX</CODE>
+preferences) for details.
+<LI CLASS="li-itemize">Incorporated patches for ipv6 support, contributed by Samuel Thibault.
+(Note that, due to a bug in the released OCaml 3.08.3 compiler, this code
+will not actually work with ipv6 unless compiled with the CVS version of the
+OCaml compiler, where the bug has been fixed; however, ipv4 should continue
+to work normally.)
+<LI CLASS="li-itemize">OSX interface:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Incorporated Ben Willmore's cool new icon for the Mac UI.
+</UL>
+<LI CLASS="li-itemize">Small fixes:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Fixed off by one error in month numbers (in printed dates) reported
+ by Bob Burger
+</UL>
+
+ </UL>
+
+Changes since 2.12.0:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+New convention for release numbering: Releases will continue to be
+given numbers of the form <CODE>X.Y.Z</CODE>, but,
+from now on, just the major version number (<CODE>X.Y</CODE>) will be considered
+significant when checking compatibility between client and server versions.
+The third component of the version number will be used only to identify
+“patch levels” of releases.<BR>
+<BR>
+This change goes hand in hand with a change to the procedure for making new
+releases. Candidate releases will initially be given “beta release”
+status when they are announced for public consumption. Any bugs that are
+discovered will be fixed in a separate branch of the source repository
+(without changing the major version number) and new tarballs re-released as
+needed. When this process converges, the patched beta version will be
+dubbed stable.
+<LI CLASS="li-itemize">Warning (failure in batch mode) when one path is completely emptied.
+ This prevents Unison from deleting everything on one replica when
+ the other disappear.
+<LI CLASS="li-itemize">Fix diff bug (where no difference is shown the first time the diff
+ command is given).
+<LI CLASS="li-itemize">User interface changes:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Improved workaround for button focus problem (GTK2 UI)
+<LI CLASS="li-itemize">Put leading zeroes in date fields
+<LI CLASS="li-itemize">More robust handling of character encodings in GTK2 UI
+<LI CLASS="li-itemize">Changed format of modification time displays, from <CODE>modified at hh:mm:ss on dd MMM, yyyy</CODE>
+to <CODE>modified on yyyy-mm-dd hh:mm:ss</CODE>
+<LI CLASS="li-itemize">Changed time display to include seconds (so that people on FAT
+ filesystems will not be confused when Unison tries to update a file
+ time to an odd number of seconds and the filesystem truncates it to
+ an even number!)
+<LI CLASS="li-itemize">Use the diff "-u" option by default when showing differences between files
+ (the output is more readable)
+<LI CLASS="li-itemize">In text mode, pipe the diff output to a pager if the environment
+ variable PAGER is set
+<LI CLASS="li-itemize">Bug fixes and cleanups in ssh password prompting. Now works with
+ the GTK2 UI under Linux. (Hopefully the Mac OS X one is not broken!)
+<LI CLASS="li-itemize">Include profile name in the GTK2 window name
+<LI CLASS="li-itemize">Added bindings ',' (same as '<') and '.' (same as '>') in the GTK2 UI
+</UL>
+<LI CLASS="li-itemize">Mac GUI:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+actions like < and > scroll to the next item as necessary.
+<LI CLASS="li-itemize">Restart has a menu item and keyboard shortcut (command-R).
+<LI CLASS="li-itemize">Added a command-line tool for Mac OS X. It can be installed from
+ the Unison menu.
+<LI CLASS="li-itemize">New icon.
+<LI CLASS="li-itemize">Handle the "help" command-line argument properly.
+<LI CLASS="li-itemize">Handle profiles given on the command line properly.
+<LI CLASS="li-itemize">When a profile has been selected, the profile dialog is replaced by a
+ "connecting" message while the connection is being made. This
+ gives better feedback.
+<LI CLASS="li-itemize">Size of left and right columns is now large enough so that
+ "PropsChanged" is not cut off.
+</UL>
+<LI CLASS="li-itemize">Minor changes:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Disable multi-threading when both roots are local
+<LI CLASS="li-itemize">Improved error handling code. In particular, make sure all files
+ are closed in case of a transient failure
+<LI CLASS="li-itemize">Under Windows, use <CODE>$UNISON</CODE> for home directory as a last resort
+ (it was wrongly moved before <CODE>$HOME</CODE> and <CODE>$USERPROFILE</CODE> in
+ Unison 2.12.0)
+<LI CLASS="li-itemize">Reopen the logfile if its name changes (profile change)
+<LI CLASS="li-itemize">Double-check that permissions and modification times have been
+ properly set: there are some combination of OS and filesystem on
+ which setting them can fail in a silent way.
+<LI CLASS="li-itemize">Check for bad Windows filenames for pure Windows synchronization
+ also (not just cross architecture synchronization).
+ This way, filenames containing backslashes, which are not correctly
+ handled by unison, are rejected right away.
+<LI CLASS="li-itemize">Attempt to resolve issues with synchronizing modification times
+ of read-only files under Windows
+<LI CLASS="li-itemize">Ignore chmod failures when deleting files
+<LI CLASS="li-itemize">Ignore trailing dots in filenames in case insensitive mode
+<LI CLASS="li-itemize">Proper quoting of paths, files and extensions ignored using the UI
+<LI CLASS="li-itemize">The strings CURRENT1 and CURRENT2 are now correctly substitued when
+ they occur in the diff preference
+<LI CLASS="li-itemize">Improvements to syncing resource forks between Macs via a non-Mac system.
+</UL>
+
+ </UL>
+
+Changes since 2.10.2:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+<B>Incompatible change:</B>
+ Archive format has changed.
+<LI CLASS="li-itemize">Source code availability: The Unison sources are now managed using
+ Subversion. One nice side-effect is that anonymous checkout is now
+ possible, like this:
+<PRE CLASS="verbatim">
+ svn co https://cvs.cis.upenn.edu:3690/svnroot/unison/
+</PRE>We will also continue to export a “developer tarball” of the current
+(modulo one day) sources in the web export directory. To receive commit logs
+for changes to the sources, subscribe to the <CODE>unison-hackers</CODE> list
+(<A HREF="http://www.cis.upenn.edu/ bcpierce/unison/lists.html"><TT>http://www.cis.upenn.edu/ bcpierce/unison/lists.html</TT></A>).
+<LI CLASS="li-itemize">Text user interface:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Substantial reworking of the internal logic of the text UI to make it
+a bit easier to modify.
+<LI CLASS="li-itemize">The <TT>dumbtty</TT> flag in the text UI is automatically set to true if
+the client is running on a Unix system and the <TT>EMACS</TT> environment
+variable is set to anything other than the empty string.
+</UL>
+<LI CLASS="li-itemize">Native OS X gui:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Added a synchronize menu item with keyboard shortcut
+<LI CLASS="li-itemize">Added a merge menu item, still needs to be debugged
+<LI CLASS="li-itemize">Fixes to compile for Panther
+<LI CLASS="li-itemize">Miscellaneous improvements and bugfixes
+</UL>
+<LI CLASS="li-itemize">Small changes:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Changed the filename checking code to apply to Windows only, instead
+ of OS X as well.
+<LI CLASS="li-itemize">Finder flags now synchronized
+<LI CLASS="li-itemize">Fallback in copy.ml for filesystem that do not support <CODE>O_EXCL</CODE>
+<LI CLASS="li-itemize">Changed buffer size for local file copy (was highly inefficient with
+ synchronous writes)
+<LI CLASS="li-itemize">Ignore chmod failure when deleting a directory
+<LI CLASS="li-itemize">Fixed assertion failure when resolving a conflict content change /
+ permission changes in favor of the content change.
+<LI CLASS="li-itemize">Workaround for transferring large files using rsync.
+<LI CLASS="li-itemize">Use buffered I/O for files (this is the only way to open files in binary
+ mode under Cygwin).
+<LI CLASS="li-itemize">On non-Cygwin Windows systems, the UNISON environment variable is now checked first to determine
+ where to look for Unison's archive and preference files, followed by <CODE>HOME</CODE> and
+ <CODE>USERPROFILE</CODE> in that order. On Unix and Cygwin systems, <CODE>HOME</CODE> is used.
+<LI CLASS="li-itemize">Generalized <CODE>diff</CODE> preference so that it can be given either as just
+ the command name to be used for calculating diffs or else a whole command
+ line, containing the strings <CODE>CURRENT1</CODE> and <CODE>CURRENT2</CODE>, which will be replaced
+ by the names of the files to be diff'ed before the command is called.
+<LI CLASS="li-itemize">Recognize password prompts in some newer versions of ssh.
+</UL>
+
+ </UL>
+
+Changes since 2.9.20:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+<B>Incompatible change:</B>
+ Archive format has changed.
+<LI CLASS="li-itemize">Major functionality changes:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Major tidying and enhancement of 'merge' functionality. The main
+ user-visible change is that the external merge program may either write
+ the merged output to a single new file, as before, or it may modify one or
+ both of its input files, or it may write <EM>two</EM> new files. In the
+ latter cases, its modifications will be copied back into place on both the
+ local and the remote host, and (if the two files are now equal) the
+ archive will be updated appropriately. More information can be found in
+ the user manual. Thanks to Malo Denielou and Alan Schmitt for these
+ improvements.<BR>
+<BR>
+Warning: the new merging functionality is not completely compatible with
+ old versions! Check the manual for details.
+<LI CLASS="li-itemize">Files larger than 2Gb are now supported.
+<LI CLASS="li-itemize">Added preliminary (and still somewhat experimental) support for the
+ Apple OS X operating system.
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Resource forks should be transferred correctly. (See the manual for
+details of how this works when synchronizing HFS with non-HFS volumes.)
+Synchronization of file type and creator information is also supported.
+<LI CLASS="li-itemize">On OSX systems, the name of the directory for storing Unison's
+archives, preference files, etc., is now determined as follows:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+ if <CODE>~/.unison</CODE> exists, use it
+ <LI CLASS="li-itemize">otherwise, use <CODE>~/Library/Application Support/Unison</CODE>,
+ creating it if necessary.
+</UL>
+<LI CLASS="li-itemize">A preliminary native-Cocoa user interface is under construction. This
+still needs some work, and some users experience unpredictable crashes, so
+it is only for hackers for now. Run make with <TT>UISTYLE=mac</TT> to build
+this interface.
+</UL>
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">Minor functionality changes:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Added an <TT>ignorelocks</TT> preference, which forces Unison to override left-over
+ archive locks. (Setting this preference is dangerous! Use it only if you
+ are positive you know what you are doing.)
+<LI CLASS="li-itemize">Added a new preference <TT>assumeContentsAreImmutable</TT>. If a directory
+ matches one of the patterns set in this preference, then update detection
+ is skipped for files in this directory. (The
+ purpose is to speed update detection for cases like Mail folders, which
+ contain lots and lots of immutable files.) Also a preference
+ <TT>assumeContentsAreImmutableNot</TT>, which overrides the first, similarly
+ to <TT>ignorenot</TT>. (Later amendment: these preferences are now called
+ <TT>immutable</TT> and <TT>immutablenot</TT>.)
+<LI CLASS="li-itemize">The <TT>ignorecase</TT> flag has been changed from a boolean to a three-valued
+ preference. The default setting, called <TT>default</TT>, checks the operating systems
+ running on the client and server and ignores filename case if either of them is
+ OSX or Windows. Setting ignorecase to <TT>true</TT> or <TT>false</TT> overrides
+ this behavior. If you have been setting <TT>ignorecase</TT> on the command
+ line using <TT>-ignorecase=true</TT> or <TT>-ignorecase=false</TT>, you will
+ need to change to <TT>-ignorecase true</TT> or <TT>-ignorecase false</TT>.
+<LI CLASS="li-itemize">a new preference, 'repeat', for the text user interface (only). If 'repeat' is set to
+ a number, then, after it finishes synchronizing, Unison will wait for that many seconds and
+ then start over, continuing this way until it is killed from outside. Setting repeat to true
+ will automatically set the batch preference to true.
+<LI CLASS="li-itemize">Excel files are now handled specially, so that the <TT>fastcheck</TT>
+ optimization is skipped even if the <TT>fastcheck</TT> flag is set. (Excel
+ does some naughty things with modtimes, making this optimization
+ unreliable and leading to failures during change propagation.)
+<LI CLASS="li-itemize">The ignorecase flag has been changed from a boolean to a three-valued
+ preference. The default setting, called 'default', checks the operating systems
+ running on the client and server and ignores filename case if either of them is
+ OSX or Windows. Setting ignorecase to 'true' or 'false' overrides this behavior.
+<LI CLASS="li-itemize">Added a new preference, 'repeat', for the text user interface (only,
+ at the moment). If 'repeat' is set to a number, then, after it finishes
+ synchronizing, Unison will wait for that many seconds and then start over,
+ continuing this way until it is killed from outside. Setting repeat to
+ true will automatically set the batch preference to true.
+<LI CLASS="li-itemize">The 'rshargs' preference has been split into 'rshargs' and 'sshargs'
+ (mainly to make the documentation clearer). In fact, 'rshargs' is no longer
+ mentioned in the documentation at all, since pretty much everybody uses
+ ssh now anyway.
+</UL>
+<LI CLASS="li-itemize">Documentation
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+The web pages have been completely redesigned and reorganized.
+ (Thanks to Alan Schmitt for help with this.)
+</UL>
+<LI CLASS="li-itemize">User interface improvements
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Added a GTK2 user interface, capable (among other things) of displaying filenames
+ in any locale encoding. Kudos to Stephen Tse for contributing this code!
+<LI CLASS="li-itemize">The text UI now prints a list of failed and skipped transfers at the end of
+ synchronization.
+<LI CLASS="li-itemize">Restarting update detection from the graphical UI will reload the current
+ profile (which in particular will reset the -path preference, in case
+ it has been narrowed by using the “Recheck unsynchronized items”
+ command).
+<LI CLASS="li-itemize">Several small improvements to the text user interface, including a
+ progress display.
+</UL>
+<LI CLASS="li-itemize">Bug fixes (too numerous to count, actually, but here are some):
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+The <TT>maxthreads</TT> preference works now.
+<LI CLASS="li-itemize">Fixed bug where warning message about uname returning an unrecognized
+ result was preventing connection to server. (The warning is no longer
+ printed, and all systems where 'uname' returns anything other than 'Darwin'
+ are assumed not to be running OS X.)
+<LI CLASS="li-itemize">Fixed a problem on OS X that caused some valid file names (e.g.,
+ those including colons) to be considered invalid.
+<LI CLASS="li-itemize">Patched Path.followLink to follow links under cygwin in addition to Unix
+ (suggested by Matt Swift).
+<LI CLASS="li-itemize">Small change to the storeRootsName function, suggested by bliviero at
+ ichips.intel.com, to fix a problem in unison with the `rootalias'
+ option, which allows you to tell unison that two roots contain the same
+ files. Rootalias was being applied after the hosts were
+ sorted, so it wouldn't work properly in all cases.
+<LI CLASS="li-itemize">Incorporated a fix by Dmitry Bely for setting utimes of read-only files
+ on Win32 systems.
+</UL>
+<LI CLASS="li-itemize">Installation / portability:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Unison now compiles with OCaml version 3.07 and later out of the box.
+<LI CLASS="li-itemize">Makefile.OCaml fixed to compile out of the box under OpenBSD.
+<LI CLASS="li-itemize">a few additional ports (e.g. OpenBSD, Zaurus/IPAQ) are now mentioned in
+ the documentation
+<LI CLASS="li-itemize">Unison can now be installed easily on OSX systems using the Fink
+ package manager
+</UL>
+
+ </UL>
+
+Changes since 2.9.1:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Added a preference <TT>maxthreads</TT> that can be used to limit the
+number of simultaneous file transfers.
+<LI CLASS="li-itemize">Added a <TT>backupdir</TT> preference, which controls where backup
+files are stored.
+<LI CLASS="li-itemize">Basic support added for OSX. In particular, Unison now recognizes
+when one of the hosts being synchronized is running OSX and switches to
+a case-insensitive treatment of filenames (i.e., 'foo' and 'FOO' are
+considered to be the same file).
+ (OSX is not yet fully working,
+ however: in particular, files with resource forks will not be
+ synchronized correctly.)
+<LI CLASS="li-itemize">The same hash used to form the archive name is now also added to
+the names of the temp files created during file transfer. The reason for
+this is that, during update detection, we are going to silently delete
+any old temp files that we find along the way, and we want to prevent
+ourselves from deleting temp files belonging to other instances of Unison
+that may be running in parallel, e.g. synchronizing with a different
+host. Thanks to Ruslan Ermilov for this suggestion.
+<LI CLASS="li-itemize">Several small user interface improvements
+<LI CLASS="li-itemize">Documentation
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+FAQ and bug reporting instructions have been split out as separate
+ HTML pages, accessible directly from the unison web page.
+<LI CLASS="li-itemize">Additions to FAQ, in particular suggestions about performance
+tuning.
+</UL>
+<LI CLASS="li-itemize">Makefile
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Makefile.OCaml now sets UISTYLE=text or UISTYLE=gtk automatically,
+ depending on whether it finds lablgtk installed
+<LI CLASS="li-itemize">Unison should now compile “out of the box” under OSX
+</UL>
+
+ </UL>
+
+Changes since 2.8.1:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Changing profile works again under Windows
+<LI CLASS="li-itemize">File movement optimization: Unison now tries to use local copy instead of
+ transfer for moved or copied files. It is controled by a boolean option
+ “xferbycopying”.
+<LI CLASS="li-itemize">Network statistics window (transfer rate, amount of data transferred).
+ [NB: not available in Windows-Cygwin version.]
+<LI CLASS="li-itemize">symlinks work under the cygwin version (which is dynamically linked).
+<LI CLASS="li-itemize">Fixed potential deadlock when synchronizing between Windows and
+Unix
+<LI CLASS="li-itemize">Small improvements:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+ If neither the <TT>USERPROFILE</TT> nor the <TT>HOME</TT> environment
+ variables are set, then Unison will put its temporary commit log
+ (called <TT>DANGER.README</TT>) into the directory named by the
+ <TT>UNISON</TT> environment variable, if any; otherwise it will use
+ <TT>C:</TT>.
+ <LI CLASS="li-itemize">alternative set of values for fastcheck: yes = true; no = false;
+ default = auto.
+ <LI CLASS="li-itemize">-silent implies -contactquietly
+ </UL>
+<LI CLASS="li-itemize">Source code:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+ Code reorganization and tidying. (Started breaking up some of the
+ basic utility modules so that the non-unison-specific stuff can be
+ made available for other projects.)
+ <LI CLASS="li-itemize">several Makefile and docs changes (for release);
+ <LI CLASS="li-itemize">further comments in “update.ml”;
+ <LI CLASS="li-itemize">connection information is not stored in global variables anymore.
+ </UL>
+
+ </UL>
+
+Changes since 2.7.78:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Small bugfix to textual user interface under Unix (to avoid leaving
+ the terminal in a bad state where it would not echo inputs after Unison
+ exited).
+
+ </UL>
+
+Changes since 2.7.39:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Improvements to the main web page (stable and beta version docs are
+ now both accessible).
+<LI CLASS="li-itemize">User manual revised.
+<LI CLASS="li-itemize">Added some new preferences:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+“sshcmd” and “rshcmd” for specifying paths to ssh and rsh programs.
+<LI CLASS="li-itemize">“contactquietly” for suppressing the “contacting server” message
+during Unison startup (under the graphical UI).
+</UL>
+<LI CLASS="li-itemize">Bug fixes:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Fixed small bug in UI that neglected to change the displayed column
+ headers if loading a new profile caused the roots to change.
+<LI CLASS="li-itemize">Fixed a bug that would put the text UI into an infinite loop if it
+ encountered a conflict when run in batch mode.
+<LI CLASS="li-itemize">Added some code to try to fix the display of non-Ascii characters in
+ filenames on Windows systems in the GTK UI. (This code is currently
+ untested—if you're one of the people that had reported problems with
+ display of non-ascii filenames, we'd appreciate knowing if this actually
+ fixes things.)
+<LI CLASS="li-itemize">`<CODE>-prefer/-force newer</CODE>' works properly now.
+ (The bug was reported by Sebastian Urbaniak and Sean Fulton.)
+</UL>
+<LI CLASS="li-itemize">User interface and Unison behavior:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Renamed `Proceed' to `Go' in the graphical UI.
+<LI CLASS="li-itemize">Added exit status for the textual user interface.
+<LI CLASS="li-itemize">Paths that are not synchronized because of conflicts or errors during
+ update detection are now noted in the log file.
+<LI CLASS="li-itemize"><CODE>[END]</CODE> messages in log now use a briefer format
+<LI CLASS="li-itemize">Changed the text UI startup sequence so that
+ <TT>./unison -ui text</TT> will use the default profile instead of failing.
+<LI CLASS="li-itemize">Made some improvements to the error messages.
+<LI CLASS="li-itemize">Added some debugging messages to remote.ml.
+</UL>
+
+ </UL>
+
+Changes since 2.7.7:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Incorporated, once again, a multi-threaded transport sub-system.
+ It transfers several files at the same time, thereby making much
+ more effective use of available network bandwidth. Unlike the
+ earlier attempt, this time we do not rely on the native thread
+ library of OCaml. Instead, we implement a light-weight,
+ non-preemptive multi-thread library in OCaml directly. This version
+ appears stable. <BR>
+<BR>
+Some adjustments to unison are made to accommodate the multi-threaded
+ version. These include, in particular, changes to the
+ user interface and logging, for example:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+ Two log entries for each transferring task, one for the
+ beginning, one for the end.
+ <LI CLASS="li-itemize">Suppressed warning messages against removing temp files left
+ by a previous unison run, because warning does not work nicely
+ under multi-threading. The temp file names are made less likely
+ to coincide with the name of a file created by the user. They
+ take the form<BR>
+<CODE>.#<filename>.<serial>.unison.tmp</CODE>.
+ [N.b. This was later changed to <CODE>.unison.<filename>.<serial>.unison.tmp</CODE>.]
+ </UL>
+<LI CLASS="li-itemize">Added a new command to the GTK user interface: pressing 'f' causes
+ Unison to start a new update detection phase, using as paths <EM>just</EM>
+ those paths that have been detected as changed and not yet marked as
+ successfully completed. Use this command to quickly restart Unison on
+ just the set of paths still needing attention after a previous run.
+<LI CLASS="li-itemize">Made the <TT>ignorecase</TT> preference user-visible, and changed the
+ initialization code so that it can be manually set to true, even if
+ neither host is running Windows. (This may be useful, e.g., when using
+ Unison running on a Unix system with a FAT volume mounted.)
+<LI CLASS="li-itemize">Small improvements and bug fixes:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+ Errors in preference files now generate fatal errors rather than
+ warnings at startup time. (I.e., you can't go on from them.) Also,
+ we fixed a bug that was preventing these warnings from appearing in the
+ text UI, so some users who have been running (unsuspectingly) with
+ garbage in their prefs files may now get error reports.
+ <LI CLASS="li-itemize">Error reporting for preference files now provides file name and
+ line number.
+ <LI CLASS="li-itemize">More intelligible message in the case of identical change to the same
+ files: “Nothing to do: replicas have been changed only in identical
+ ways since last sync.”
+ <LI CLASS="li-itemize">Files with prefix '.#' excluded when scanning for preference
+ files.
+ <LI CLASS="li-itemize">Rsync instructions are send directly instead of first
+ marshaled.
+ <LI CLASS="li-itemize">Won't try forever to get the fingerprint of a continuously changing file:
+ unison will give up after certain number of retries.
+ <LI CLASS="li-itemize">Other bug fixes, including the one reported by Peter Selinger
+ (<CODE>force=older preference</CODE> not working).
+ </UL>
+<LI CLASS="li-itemize">Compilation:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+ Upgraded to the new OCaml 3.04 compiler, with the LablGtk
+ 1.2.3 library (patched version used for compiling under Windows).
+ <LI CLASS="li-itemize">Added the option to compile unison on the Windows platform with
+ Cygwin GNU C compiler. This option only supports building
+ dynamically linked unison executables.
+ </UL>
+
+ </UL>
+
+Changes since 2.7.4:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Fixed a silly (but debilitating) bug in the client startup sequence.
+
+ </UL>
+
+Changes since 2.7.1:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Added <CODE>addprefsto</CODE> preference, which (when set) controls which
+preference file new preferences (e.g. new ignore patterns) are added to.
+<LI CLASS="li-itemize">Bug fix: read the initial connection header one byte at a time, so
+that we don't block if the header is shorter than expected. (This bug
+did not affect normal operation — it just made it hard to tell when you
+were trying to use Unison incorrectly with an old version of the server,
+since it would hang instead of giving an error message.)
+
+ </UL>
+
+Changes since 2.6.59:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Changed <CODE>fastcheck</CODE> from a boolean to a string preference. Its
+ legal values are <CODE>yes</CODE> (for a fast check), <CODE>no</CODE> (for a safe
+ check), or <CODE>default</CODE> (for a fast check—which also happens to be
+ safe—when running on Unix and a safe check when on Windows). The default
+ is <CODE>default</CODE>.
+ <LI CLASS="li-itemize">Several preferences have been renamed for consistency. All
+ preference names are now spelled out in lowercase. For backward
+ compatibility, the old names still work, but they are not mentioned in
+ the manual any more.
+<LI CLASS="li-itemize">The temp files created by the 'diff' and 'merge' commands are now
+ named by <EM>pre</EM>pending a new prefix to the file name, rather than
+ appending a suffix. This should avoid confusing diff/merge programs
+ that depend on the suffix to guess the type of the file contents.
+<LI CLASS="li-itemize">We now set the keepalive option on the server socket, to make sure
+ that the server times out if the communication link is unexpectedly broken.
+<LI CLASS="li-itemize">Bug fixes:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+When updating small files, Unison now closes the destination file.
+<LI CLASS="li-itemize">File permissions are properly updated when the file is behind a
+ followed link.
+<LI CLASS="li-itemize">Several other small fixes.
+</UL>
+
+ </UL>
+
+Changes since 2.6.38:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Major Windows performance improvement! <BR>
+<BR>
+We've added a preference <CODE>fastcheck</CODE> that makes Unison look only at
+a file's creation time and last-modified time to check whether it has
+changed. This should result in a huge speedup when checking for updates
+in large replicas.<BR>
+<BR>
+When this switch is set, Unison will use file creation times as
+ 'pseudo inode numbers' when scanning Windows replicas for updates,
+ instead of reading the full contents of every file. This may cause
+ Unison to miss propagating an update if the create time,
+ modification time, and length of the file are all unchanged by
+ the update (this is not easy to achieve, but it can be done).
+ However, Unison will never <EM>overwrite</EM> 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 <TT>fastcheck</TT> set to false,
+ if you are worried that Unison may have overlooked an update.<BR>
+<BR>
+Warning: This change is has not yet been thoroughly field-tested. If you
+ set the <CODE>fastcheck</CODE> preference, pay careful attention to what
+ Unison is doing.<BR>
+<BR>
+<LI CLASS="li-itemize">New functionality: centralized backups and merging
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+This version incorporates two pieces of major new functionality,
+ implemented by Sylvain Roy during a summer internship at Penn: a
+ <EM>centralized backup</EM> facility that keeps a full backup of
+ (selected files
+ in) each replica, and a <EM>merging</EM> feature that allows Unison to
+ invoke an external file-merging tool to resolve conflicting changes to
+ individual files.<BR>
+<BR>
+<LI CLASS="li-itemize">Centralized backups:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+ Unison now maintains full backups of the last-synchronized versions
+ of (some of) the files in each replica; these function both as
+ backups in the usual sense
+ and as the “common version” when invoking external
+ merge programs.
+ <LI CLASS="li-itemize">The backed up files are stored in a directory /.unison/backup on each
+ host. (The name of this directory can be changed by setting
+ the environment variable <CODE>UNISONBACKUPDIR</CODE>.)
+ <LI CLASS="li-itemize">The predicate <CODE>backup</CODE> controls which files are actually
+ backed up:
+ giving the preference '<CODE>backup = Path *</CODE>' causes backing up
+ of all files.
+ <LI CLASS="li-itemize">Files are added to the backup directory whenever unison updates
+ its archive. This means that
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+ When unison reconstructs its archive from scratch (e.g.,
+ because of an upgrade, or because the archive files have
+ been manually deleted), all files will be backed up.
+ <LI CLASS="li-itemize">Otherwise, each file will be backed up the first time unison
+ propagates an update for it.
+ </UL>
+ <LI CLASS="li-itemize">The preference <CODE>backupversions</CODE> controls how many previous
+ versions of each file are kept. The default is 2 (i.e., the last
+ synchronized version plus one backup).
+ <LI CLASS="li-itemize">For backward compatibility, the <CODE>backups</CODE> preference is also
+ still supported, but <CODE>backup</CODE> is now preferred.
+ <LI CLASS="li-itemize">It is OK to manually delete files from the backup directory (or to throw
+ away the directory itself). Before unison uses any of these files for
+ anything important, it checks that its fingerprint matches the one
+ that it expects.
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">Merging:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+ Both user interfaces offer a new 'merge' command, invoked by pressing
+ 'm' (with a changed file selected).
+ <LI CLASS="li-itemize">The actual merging is performed by an external program.
+ The preferences <CODE>merge</CODE> and <CODE>merge2</CODE> control how this
+ program is invoked. If a backup exists for this file (see the
+ <CODE>backup</CODE> preference), then the <CODE>merge</CODE> preference is used for
+ this purpose; otherwise <CODE>merge2</CODE> is used. In both cases, the
+ value of the preference should be a string representing the command
+ that should be passed to a shell to invoke the
+ merge program. Within this string, the special substrings
+ <CODE>CURRENT1</CODE>, <CODE>CURRENT2</CODE>, <CODE>NEW</CODE>, and <CODE>OLD</CODE> may appear
+ at any point. Unison will substitute these as follows before invoking
+ the command:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+ <CODE>CURRENT1</CODE> is replaced by the name of the local
+ copy of the file;
+ <LI CLASS="li-itemize"><CODE>CURRENT2</CODE> is replaced by the name of a temporary
+ file, into which the contents of the remote copy of the file have
+ been transferred by Unison prior to performing the merge;
+ <LI CLASS="li-itemize"><CODE>NEW</CODE> 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; and
+ <LI CLASS="li-itemize"><CODE>OLD</CODE> 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
+ (applies only to <CODE>merge</CODE>, not <CODE>merge2</CODE>).
+ </UL>
+ For example, on Unix systems setting the <CODE>merge</CODE> preference to
+<PRE CLASS="verbatim">
+ merge = diff3 -m CURRENT1 OLD CURRENT2 > NEW
+</PRE>will tell Unison to use the external <CODE>diff3</CODE> program for merging. <BR>
+<BR>
+A large number of external merging programs are available. For
+ example, <CODE>emacs</CODE> users may find the following convenient:
+<PRE CLASS="verbatim">
+ merge2 = emacs -q --eval '(ediff-merge-files "CURRENT1" "CURRENT2"
+ nil "NEW")'
+ merge = emacs -q --eval '(ediff-merge-files-with-ancestor
+ "CURRENT1" "CURRENT2" "OLD" nil "NEW")'
+</PRE>(These commands are displayed here on two lines to avoid running off the
+edge of the page. In your preference file, each should be written on a
+single line.) <BR>
+<BR>
+<LI CLASS="li-itemize">If the external program exits without leaving any file at the
+ path <CODE>NEW</CODE>,
+ Unison considers the merge to have failed. If the merge program writes
+ a file called <CODE>NEW</CODE> but exits with a non-zero status code,
+ then Unison
+ considers the merge to have succeeded but to have generated conflicts.
+ In this case, it attempts to invoke an external editor so that the
+ user can resolve the conflicts. The value of the <CODE>editor</CODE>
+ preference controls what editor is invoked by Unison. The default
+ is <CODE>emacs</CODE>.<BR>
+<BR>
+<LI CLASS="li-itemize">Please send us suggestions for other useful values of the
+ <CODE>merge2</CODE> and <CODE>merge</CODE> preferences – we'd like to give several
+ examples in the manual.
+</UL>
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">Smaller changes:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+When one preference file includes another, unison no longer adds the
+ suffix '<CODE>.prf</CODE>' to the included file by default. If a file with
+ precisely the given name exists in the .unison directory, it will be used;
+ otherwise Unison will
+ add <CODE>.prf</CODE>, as it did before. (This change means that included
+ preference files can be named <CODE>blah.include</CODE> instead of
+ <CODE>blah.prf</CODE>, so that unison will not offer them in its 'choose
+ a preference file' dialog.)
+<LI CLASS="li-itemize">For Linux systems, we now offer both a statically linked and a dynamically
+ linked executable. The static one is larger, but will probably run on more
+ systems, since it doesn't depend on the same versions of dynamically
+ linked library modules being available.
+<LI CLASS="li-itemize">Fixed the <CODE>force</CODE> and <CODE>prefer</CODE> preferences, which were
+ getting the propagation direction exactly backwards.
+<LI CLASS="li-itemize">Fixed a bug in the startup code that would cause unison to crash
+ when the default profile (<CODE>~/.unison/default.prf</CODE>) does not exist.
+<LI CLASS="li-itemize">Fixed a bug where, on the run when a profile is first created,
+ Unison would confusingly display the roots in reverse order in the user
+ interface.
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">For developers:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+We've added a module dependency diagram to the source distribution, in
+ <CODE>src/DEPENDENCIES.ps</CODE>, to help new prospective developers with
+ navigating the code.
+</UL>
+
+ </UL>
+
+Changes since 2.6.11:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+<B>Incompatible change:</B>
+ Archive format has changed. <BR>
+<BR>
+<LI CLASS="li-itemize"><B>Incompatible change:</B>
+ The startup sequence has been completely rewritten
+and greatly simplified. The main user-visible change is that the
+<CODE>defaultpath</CODE> preference has been removed. Its effect can be
+approximated by using multiple profiles, with <CODE>include</CODE> directives
+to incorporate common settings. All uses of <CODE>defaultpath</CODE> in
+existing profiles should be changed to <CODE>path</CODE>.<BR>
+<BR>
+Another change in startup behavior that will affect some users is that it
+is no longer possible to specify roots <EM>both</EM> in the profile <EM>and</EM> on the command line.<BR>
+<BR>
+You can achieve a similar effect, though, by breaking your profile into
+two:
+<PRE CLASS="verbatim">
+
+ default.prf =
+ root = blah
+ root = foo
+ include common
+
+ common.prf =
+ <everything else>
+</PRE>Now do
+<PRE CLASS="verbatim">
+ unison common root1 root2
+</PRE>when you want to specify roots explicitly.<BR>
+<BR>
+<LI CLASS="li-itemize">The <CODE>-prefer</CODE> and <CODE>-force</CODE> options have been extended to
+allow users to specify that files with more recent modtimes should be
+propagated, writing either <CODE>-prefer newer</CODE> or <CODE>-force newer</CODE>.
+(For symmetry, Unison will also accept <CODE>-prefer older</CODE> or
+<CODE>-force older</CODE>.) The <CODE>-force older/newer</CODE> options can only be
+used when <CODE>-times</CODE> is also set.<BR>
+<BR>
+The graphical user interface provides access to these facilities on a
+one-off basis via the <CODE>Actions</CODE> menu.<BR>
+<BR>
+<LI CLASS="li-itemize">Names of roots can now be “aliased” to allow replicas to be
+relocated without changing the name of the archive file where Unison
+stores information between runs. (This feature is for experts only. See
+the “Archive Files” section of the manual for more information.)<BR>
+<BR>
+<LI CLASS="li-itemize">Graphical user-interface:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+A new command is provided in the Synchronization menu for
+ switching to a new profile without restarting Unison from scratch.
+<LI CLASS="li-itemize">The GUI also supports one-key shortcuts for commonly
+used profiles. If a profile contains a preference of the form
+'<CODE>key = n</CODE>', where <CODE>n</CODE> is a single digit, then pressing this
+key will cause Unison to immediately switch to this profile and begin
+synchronization again from scratch. (Any actions that may have been
+selected for a set of changes currently being displayed will be
+discarded.) <BR>
+<BR>
+<LI CLASS="li-itemize">Each profile may include a preference '<CODE>label = <string></CODE>' giving a
+ descriptive string that described the options selected in this profile.
+ The string is listed along with the profile name in the profile selection
+ dialog, and displayed in the top-right corner of the main Unison window.
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">Minor:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Fixed a bug that would sometimes cause the 'diff' display to order
+ the files backwards relative to the main user interface. (Thanks
+ to Pascal Brisset for this fix.)
+<LI CLASS="li-itemize">On Unix systems, the graphical version of Unison will check the
+ <CODE>DISPLAY</CODE> variable and, if it is not set, automatically fall back
+ to the textual user interface.
+<LI CLASS="li-itemize">Synchronization paths (<CODE>path</CODE> preferences) are now matched
+ against the ignore preferences. So if a path is both specified in a
+ <CODE>path</CODE> preference and ignored, it will be skipped.
+<LI CLASS="li-itemize">Numerous other bugfixes and small improvements.
+</UL>
+
+ </UL>
+
+Changes since 2.6.1:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+The synchronization of modification times has been disabled for
+ directories.<BR>
+<BR>
+<LI CLASS="li-itemize">Preference files may now include lines of the form
+ <CODE>include <name></CODE>, which will cause <CODE>name.prf</CODE> to be read
+ at that point.<BR>
+<BR>
+<LI CLASS="li-itemize">The synchronization of permission between Windows and Unix now
+ works properly.<BR>
+<BR>
+<LI CLASS="li-itemize">A binding <CODE>CYGWIN=binmode</CODE> in now added to the environment
+ so that the Cygwin port of OpenSSH works properly in a non-Cygwin
+ context.<BR>
+<BR>
+<LI CLASS="li-itemize">The <CODE>servercmd</CODE> and <CODE>addversionno</CODE> preferences can now
+ be used together: <CODE>-addversionno</CODE> appends an appropriate
+ <CODE>-NNN</CODE> to the server command, which is found by using the value
+ of the <CODE>-servercmd</CODE> preference if there is one, or else just
+ <CODE>unison</CODE>.<BR>
+<BR>
+<LI CLASS="li-itemize">Both <CODE>'-pref=val'</CODE> and <CODE>'-pref val'</CODE> are now allowed for
+ boolean values. (The former can be used to set a preference to false.)<BR>
+<BR>
+<LI CLASS="li-itemize">Lot of small bugs fixed.
+
+ </UL>
+
+Changes since 2.5.31:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+The <CODE>log</CODE> preference is now set to <CODE>true</CODE> by default,
+ since the log file seems useful for most users.
+<LI CLASS="li-itemize">Several miscellaneous bugfixes (most involving symlinks).
+
+ </UL>
+
+Changes since 2.5.25:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+<B>Incompatible change:</B>
+ Archive format has changed (again). <BR>
+<BR>
+<LI CLASS="li-itemize">Several significant bugs introduced in 2.5.25 have been fixed.
+
+ </UL>
+
+Changes since 2.5.1:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+<B>Incompatible change:</B>
+ Archive format has changed. Make sure you
+synchronize your replicas before upgrading, to avoid spurious
+conflicts. The first sync after upgrading will be slow.<BR>
+<BR>
+<LI CLASS="li-itemize">New functionality:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Unison now synchronizes file modtimes, user-ids, and group-ids. <BR>
+<BR>
+These new features are controlled by a set of new preferences, all of
+which are currently <CODE>false</CODE> by default.
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+When the <CODE>times</CODE> preference is set to <CODE>true</CODE>, file
+modification times are propaged. (Because the representations of time
+may not have the same granularity on both replicas, Unison may not always
+be able to make the modtimes precisely equal, but it will get them as
+close as the operating systems involved allow.)
+<LI CLASS="li-itemize">When the <CODE>owner</CODE> preference is set to <CODE>true</CODE>, file
+ownership information is synchronized.
+<LI CLASS="li-itemize">When the <CODE>group</CODE> preference is set to <CODE>true</CODE>, group
+information is synchronized.
+<LI CLASS="li-itemize">When the <CODE>numericIds</CODE> preference is set to <CODE>true</CODE>, owner
+and group information is synchronized numerically. By default, owner and
+group numbers are converted to names on each replica and these names are
+synchronized. (The special user id 0 and the special group 0 are never
+mapped via user/group names even if this preference is not set.)
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">Added an integer-valued preference <CODE>perms</CODE> that can be used to
+control the propagation of permission bits. The value of this preference
+is a mask indicating which permission bits should be synchronized. It is
+set by default to 0<I>o</I>1777: 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.<BR>
+<BR>
+<LI CLASS="li-itemize">Added a <CODE>log</CODE> preference (default <CODE>false</CODE>), which makes
+Unison keep a complete record of the changes it makes to the replicas.
+By default, this record is written to a file called <CODE>unison.log</CODE> in
+the user's home directory (the value of the <CODE>HOME</CODE> environment
+variable). If you want it someplace else, set the <CODE>logfile</CODE>
+preference to the full pathname you want Unison to use.<BR>
+<BR>
+<LI CLASS="li-itemize">Added an <CODE>ignorenot</CODE> preference that maintains a set of patterns
+ for paths that should definitely <EM>not</EM> be ignored, whether or not
+ they match an <CODE>ignore</CODE> pattern. (That is, a path will now be ignored
+ iff it matches an ignore pattern and does not match any ignorenot patterns.)
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">User-interface improvements:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Roots are now displayed in the user interface in the same order
+as they were given on the command line or in the preferences file.
+<LI CLASS="li-itemize">When the <CODE>batch</CODE> preference is set, the graphical user interface no
+ longer waits for user confirmation when it displays a warning message: it
+ simply pops up an advisory window with a Dismiss button at the bottom and
+ keeps on going.
+<LI CLASS="li-itemize">Added a new preference for controlling how many status messages are
+ printed during update detection: <CODE>statusdepth</CODE> controls the maximum
+ depth for paths on the local machine (longer paths are not displayed, nor
+ are non-directory paths). The value should be an integer; default is 1.
+<LI CLASS="li-itemize">Removed the <CODE>trace</CODE> and <CODE>silent</CODE> preferences. They did
+not seem very useful, and there were too many preferences for controlling
+output in various ways.
+<LI CLASS="li-itemize">The text UI now displays just the default command (the one that
+will be used if the user just types <CODE><return></CODE>) instead of all
+available commands. Typing <CODE>?</CODE> will print the full list of
+possibilities.
+<LI CLASS="li-itemize">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
+<CODE>gethostname</CODE> operating system call. However, if the environment
+variable <CODE>UNISONLOCALHOSTNAME</CODE> is set, its value will now 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).
+<LI CLASS="li-itemize">File owner and group are now displayed in the “detail window” at
+the bottom of the screen, when unison is configured to synchronize them.
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">For hackers:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Updated to Jacques Garrigue's new version of <CODE>lablgtk</CODE>, which
+ means we can throw away our local patched version. <BR>
+<BR>
+If you're compiling the GTK version of unison from sources, you'll need
+ to update your copy of lablgtk to the developers release.
+ (Warning: installing lablgtk under Windows is currently a bit
+ challenging.) <BR>
+<BR>
+<LI CLASS="li-itemize">The TODO.txt file (in the source distribution) has been cleaned up
+and reorganized. The list of pending tasks should be much easier to
+make sense of, for people that may want to contribute their programming
+energies. There is also a separate file BUGS.txt for open bugs.
+<LI CLASS="li-itemize">The Tk user interface has been removed (it was not being maintained
+and no longer compiles).
+<LI CLASS="li-itemize">The <CODE>debug</CODE> preference now prints quite a bit of additional
+information that should be useful for identifying sources of problems.
+<LI CLASS="li-itemize">The version number of the remote server is now checked right away
+ during the connection setup handshake, rather than later. (Somebody
+ sent a bug report of a server crash that turned out to come from using
+ inconsistent versions: better to check this earlier and in a way that
+ can't crash either client or server.)
+<LI CLASS="li-itemize">Unison now runs correctly on 64-bit architectures (e.g. Alpha
+linux). We will not be distributing binaries for these architectures
+ourselves (at least for a while) but if someone would like to make them
+available, we'll be glad to provide a link to them.
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">Bug fixes:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Pattern matching (e.g. for <CODE>ignore</CODE>) is now case-insensitive
+ when Unison is in case-insensitive mode (i.e., when one of the replicas
+ is on a windows machine).
+<LI CLASS="li-itemize">Some people had trouble with mysterious failures during
+ propagation of updates, where files would be falsely reported as having
+ changed during synchronization. This should be fixed.
+<LI CLASS="li-itemize">Numerous smaller fixes.
+</UL>
+
+ </UL>
+
+Changes since 2.4.1:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Added a number of 'sorting modes' for the user interface. By
+default, conflicting changes are displayed at the top, and the rest of
+the entries are sorted in alphabetical order. This behavior can be
+changed in the following ways:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Setting the <CODE>sortnewfirst</CODE> preference to <CODE>true</CODE> causes
+newly created files to be displayed before changed files.
+<LI CLASS="li-itemize">Setting <CODE>sortbysize</CODE> causes files to be displayed in
+increasing order of size.
+<LI CLASS="li-itemize">Giving the preference <CODE>sortfirst=<pattern></CODE> (where
+<CODE><pattern></CODE> is a path descriptor in the same format as 'ignore' and 'follow'
+patterns, causes paths matching this pattern to be displayed first.
+<LI CLASS="li-itemize">Similarly, giving the preference <CODE>sortlast=<pattern></CODE>
+causes paths matching this pattern to be displayed last.
+</UL>
+The sorting preferences are described in more detail in the user manual.
+The <CODE>sortnewfirst</CODE> and <CODE>sortbysize</CODE> flags can also be accessed
+from the 'Sort' menu in the grpahical user interface.<BR>
+<BR>
+<LI CLASS="li-itemize">Added two new preferences that can be used to change unison's
+fundamental behavior to make it more like a mirroring tool instead of
+a synchronizer.
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Giving the preference <CODE>prefer</CODE> with argument <CODE><root></CODE>
+(by adding <CODE>-prefer <root></CODE> to the command line or <CODE>prefer=<root></CODE>)
+to your profile) means that, if there is a conflict, the contents of
+<CODE><root></CODE>
+should be propagated to the other replica (with no questions asked).
+Non-conflicting changes are treated as usual.
+<LI CLASS="li-itemize">Giving the preference <CODE>force</CODE> with argument <CODE><root></CODE>
+will make unison resolve <EM>all</EM> differences in favor of the given
+root, even if it was the other replica that was changed.
+</UL>
+These options should be used with care! (More information is available in
+the manual.)<BR>
+<BR>
+<LI CLASS="li-itemize">Small changes:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Changed default answer to 'Yes' in all two-button dialogs in the
+ graphical interface (this seems more intuitive).<BR>
+<BR>
+<LI CLASS="li-itemize">The <CODE>rsync</CODE> preference has been removed (it was used to
+activate rsync compression for file transfers, but rsync compression is
+now enabled by default).
+<LI CLASS="li-itemize">In the text user interface, the arrows indicating which direction
+changes are being
+ propagated are printed differently when the user has overridded Unison's
+ default recommendation (<CODE>====></CODE> instead of <CODE>----></CODE>). This
+ matches the behavior of the graphical interface, which displays such
+ arrows in a different color.
+<LI CLASS="li-itemize">Carriage returns (Control-M's) are ignored at the ends of lines in
+ profiles, for Windows compatibility.
+<LI CLASS="li-itemize">All preferences are now fully documented in the user manual.
+</UL>
+
+ </UL>
+
+Changes since 2.3.12:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+<B>Incompatible change:</B>
+ Archive format has changed. Make sure you
+synchronize your replicas before upgrading, to avoid spurious
+conflicts. The first sync after upgrading will be slow.<BR>
+<BR>
+<LI CLASS="li-itemize">New/improved functionality:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+A new preference -sortbysize controls the order in which changes
+ are displayed to the user: when it is set to true, the smallest
+ changed files are displayed first. (The default setting is false.)
+<LI CLASS="li-itemize">A new preference -sortnewfirst causes newly created files to be
+ listed before other updates in the user interface.
+<LI CLASS="li-itemize">We now allow the ssh protocol to specify a port.
+<LI CLASS="li-itemize">Incompatible change: The unison: protocol is deprecated, and we added
+ file: and socket:. You may have to modify your profiles in the
+ .unison directory.
+ If a replica is specified without an explicit protocol, we now
+ assume it refers to a file. (Previously "//saul/foo" meant to use
+ SSH to connect to saul, then access the foo directory. Now it means
+ to access saul via a remote file mechanism such as samba; the old
+ effect is now achieved by writing <TT>ssh://saul/foo</TT>.)
+<LI CLASS="li-itemize">Changed the startup sequence for the case where roots are given but
+ no profile is given on the command line. The new behavior is to
+ use the default profile (creating it if it does not exist), and
+ temporarily override its roots. The manual claimed that this case
+ would work by reading no profile at all, but AFAIK this was never
+ true.
+<LI CLASS="li-itemize">In all user interfaces, files with conflicts are always listed first
+<LI CLASS="li-itemize">A new preference 'sshversion' can be used to control which version
+ of ssh should be used to connect to the server. Legal values are 1 and 2.
+ (Default is empty, which will make unison use whatever version of ssh
+ is installed as the default 'ssh' command.)
+<LI CLASS="li-itemize">The situation when the permissions of a file was updated the same on
+ both side is now handled correctly (we used to report a spurious conflict)</UL><BR>
+<BR>
+<LI CLASS="li-itemize">Improvements for the Windows version:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+The fact that filenames are treated case-insensitively under
+Windows should now be handled correctly. The exact behavior is described
+in the cross-platform section of the manual.
+<LI CLASS="li-itemize">It should be possible to synchronize with Windows shares, e.g.,
+ //host/drive/path.
+<LI CLASS="li-itemize">Workarounds to the bug in syncing root directories in Windows.
+The most difficult thing to fix is an ocaml bug: Unix.opendir fails on
+c: in some versions of Windows.
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">Improvements to the GTK user interface (the Tk interface is no
+longer being maintained):
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+The UI now displays actions differently (in blue) when they have been
+ explicitly changed by the user from Unison's default recommendation.
+<LI CLASS="li-itemize">More colorful appearance.
+<LI CLASS="li-itemize">The initial profile selection window works better.
+<LI CLASS="li-itemize">If any transfers failed, a message to this effect is displayed along with
+ 'Synchronization complete' at the end of the transfer phase (in case they
+ may have scrolled off the top).
+<LI CLASS="li-itemize">Added a global progress meter, displaying the percentage of <EM>total</EM>
+ bytes that have been transferred so far.
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">Improvements to the text user interface:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+The file details will be displayed automatically when a
+ conflict is been detected.
+<LI CLASS="li-itemize">when a warning is generated (e.g. for a temporary
+ file left over from a previous run of unison) Unison will no longer
+ wait for a response if it is running in -batch mode.
+<LI CLASS="li-itemize">The UI now displays a short list of possible inputs each time it waits
+ for user interaction.
+<LI CLASS="li-itemize">The UI now quits immediately (rather than looping back and starting
+ the interaction again) if the user presses 'q' when asked whether to
+ propagate changes.
+<LI CLASS="li-itemize">Pressing 'g' in the text user interface will proceed immediately
+ with propagating updates, without asking any more questions.
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">Documentation and installation changes:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+The manual now includes a FAQ, plus sections on common problems and
+on tricks contributed by users.
+<LI CLASS="li-itemize">Both the download page and the download directory explicitly say
+what are the current stable and beta-test version numbers.
+<LI CLASS="li-itemize">The OCaml sources for the up-to-the-minute developers' version (not
+guaranteed to be stable, or even to compile, at any given time!) are now
+available from the download page.
+<LI CLASS="li-itemize">Added a subsection to the manual describing cross-platform
+ issues (case conflicts, illegal filenames)
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">Many small bug fixes and random improvements.<BR>
+<BR>
+
+ </UL>
+
+Changes since 2.3.1:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Several bug fixes. The most important is a bug in the rsync
+module that would occasionally cause change propagation to fail with a
+'rename' error.
+
+ </UL>
+
+Changes since 2.2:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+The multi-threaded transport system is now disabled by default.
+(It is not stable enough yet.)
+<LI CLASS="li-itemize">Various bug fixes.
+<LI CLASS="li-itemize">A new experimental feature: <BR>
+<BR>
+The final component of a -path argument may now be the wildcard
+ specifier <CODE>*</CODE>. When Unison sees such a path, it expands this path on
+ the client into into the corresponding list of paths by listing the
+ contents of that directory. <BR>
+<BR>
+Note that if you use wildcard paths from the command line, you will
+ probably need to use quotes or a backslash to prevent the * from
+ being interpreted by your shell.<BR>
+<BR>
+If both roots are local, the contents of the first one will be used
+ for expanding wildcard paths. (Nb: this is the first one <EM>after</EM> the
+ canonization step – i.e., the one that is listed first in the user
+ interface – not the one listed first on the command line or in the
+ preferences file.)
+
+ </UL>
+
+Changes since 2.1:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+The transport subsystem now includes an implementation by
+Sylvain Gommier and Norman Ramsey of Tridgell and Mackerras's
+<CODE>rsync</CODE> protocol. This protocol achieves much faster
+transfers when only a small part of a large file has been changed by
+sending just diffs. This feature is mainly helpful for transfers over
+slow links—on fast local area networks it can actually degrade
+performance—so we have left it off by default. Start unison with
+the <CODE>-rsync</CODE> option (or put <CODE>rsync=true</CODE> in your preferences
+file) to turn it on.<BR>
+<BR>
+<LI CLASS="li-itemize">“Progress bars” are now diplayed during remote file transfers,
+showing what percentage of each file has been transferred so far.<BR>
+<BR>
+<LI CLASS="li-itemize">The version numbering scheme has changed. New releases will now
+ be have numbers like 2.2.30, where the second component is
+ incremented on every significant public release and the third
+ component is the “patch level.”<BR>
+<BR>
+<LI CLASS="li-itemize">Miscellaneous improvements to the GTK-based user interface.
+<LI CLASS="li-itemize">The manual is now available in PDF format.<BR>
+<BR>
+<LI CLASS="li-itemize">We are experimenting with using a multi-threaded transport
+subsystem to transfer several files at the same time, making
+much more effective use of available network bandwidth. This feature
+is not completely stable yet, so by default it is disabled in the
+release version of Unison.<BR>
+<BR>
+If you want to play with the multi-threaded version, you'll need to
+recompile Unison from sources (as described in the documentation),
+setting the THREADS flag in Makefile.OCaml to true. Make sure that
+your OCaml compiler has been installed with the <CODE>-with-pthreads</CODE>
+configuration option. (You can verify this by checking whether the
+file <CODE>threads/threads.cma</CODE> in the OCaml standard library
+directory contains the string <CODE>-lpthread</CODE> near the end.)
+
+ </UL>
+
+Changes since 1.292:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Reduced memory footprint (this is especially important during
+the first run of unison, where it has to gather information about all
+the files in both repositories).
+<LI CLASS="li-itemize">Fixed a bug that would cause the socket server under NT to fail
+ after the client exits.
+<LI CLASS="li-itemize">Added a SHIFT modifier to the Ignore menu shortcut keys in GTK
+ interface (to avoid hitting them accidentally).
+
+ </UL>
+
+Changes since 1.231:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Tunneling over ssh is now supported in the Windows version. See
+the installation section of the manual for detailed instructions.<BR>
+<BR>
+<LI CLASS="li-itemize">The transport subsystem now includes an implementation of the
+<CODE>rsync</CODE> protocol, built by Sylvain Gommier and Norman Ramsey.
+This protocol achieves much faster transfers when only a small part of
+a large file has been changed by sending just diffs. The rsync
+feature is off by default in the current version. Use the
+<CODE>-rsync</CODE> switch to turn it on. (Nb. We still have a lot of
+tuning to do: you may not notice much speedup yet.)<BR>
+<BR>
+<LI CLASS="li-itemize">We're experimenting with a multi-threaded transport subsystem,
+written by Jerome Vouillon. The downloadable binaries are still
+single-threaded: if you want to try the multi-threaded version, you'll
+need to recompile from sources. (Say <CODE>make THREADS=true</CODE>.)
+Native thread support from the compiler is required. Use the option
+<CODE>-threads N</CODE> to select the maximal number of concurrent
+threads (default is 5). Multi-threaded
+and single-threaded clients/servers can interoperate. <BR>
+<BR>
+<LI CLASS="li-itemize">A new GTK-based user interface is now available, thanks to
+Jacques Garrigue. The Tk user interface still works, but we'll be
+shifting development effort to the GTK interface from now on.
+<LI CLASS="li-itemize">OCaml 3.00 is now required for compiling Unison from sources.
+The modules <CODE>uitk</CODE> and <CODE>myfileselect</CODE> have been changed to
+use labltk instead of camltk. To compile the Tk interface in Windows,
+you must have ocaml-3.00 and tk8.3. When installing tk8.3, put it in
+<CODE>c:\Tcl</CODE> rather than the suggested <CODE>c:\Program Files\Tcl</CODE>,
+and be sure to install the headers and libraries (which are not
+installed by default).<BR>
+<BR>
+<LI CLASS="li-itemize">Added a new <CODE>-addversionno</CODE> switch, which causes unison to
+use <CODE>unison-<currentversionnumber></CODE> instead of just <CODE>unison</CODE>
+as the remote server command. This allows multiple 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.
+
+ </UL>
+
+Changes since 1.219:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+<B>Incompatible change:</B>
+ Archive format has changed. Make sure you
+synchronize your replicas before upgrading, to avoid spurious
+conflicts. The first sync after upgrading will be slow.<BR>
+<BR>
+<LI CLASS="li-itemize">This version fixes several annoying bugs, including:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+Some cases where propagation of file permissions was not
+working.
+<LI CLASS="li-itemize">umask is now ignored when creating directories
+<LI CLASS="li-itemize">directories are create writable, so that a read-only directory and
+ its contents can be propagated.
+<LI CLASS="li-itemize">Handling of warnings generated by the server.
+<LI CLASS="li-itemize">Synchronizing a path whose parent is not a directory on both sides is
+now flagged as erroneous.
+<LI CLASS="li-itemize">Fixed some bugs related to symnbolic links and nonexistant roots.
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+When a change (deletion or new contents) is propagated onto a
+ 'follow'ed symlink, the file pointed to by the link is now changed.
+ (We used to change the link itself, which doesn't fit our assertion
+ that 'follow' means the link is completely invisible)
+ <LI CLASS="li-itemize">When one root did not exist, propagating the other root on top of it
+ used to fail, becuase unison could not calculate the working directory
+ into which to write changes. This should be fixed.
+</UL>
+</UL><BR>
+<BR>
+<LI CLASS="li-itemize">A human-readable timestamp has been added to Unison's archive files.<BR>
+<BR>
+<LI CLASS="li-itemize">The semantics of Path and Name regular expressions now
+correspond better. <BR>
+<BR>
+<LI CLASS="li-itemize">Some minor improvements to the text UI (e.g. a command for going
+back to previous items)<BR>
+<BR>
+<LI CLASS="li-itemize">The organization of the export directory has changed — should
+be easier to find / download things now.
+
+ </UL>
+
+Changes since 1.200:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+<B>Incompatible change:</B>
+ Archive format has changed. Make sure you
+synchronize your replicas before upgrading, to avoid spurious
+conflicts. The first sync after upgrading will be slow.<BR>
+<BR>
+<LI CLASS="li-itemize">This version has not been tested extensively on Windows.<BR>
+<BR>
+<LI CLASS="li-itemize">Major internal changes designed to make unison safer to run
+at the same time as the replicas are being changed by the user.<BR>
+<BR>
+<LI CLASS="li-itemize">Internal performance improvements.
+
+ </UL>
+
+Changes since 1.190:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+<B>Incompatible change:</B>
+ Archive format has changed. Make sure you
+synchronize your replicas before upgrading, to avoid spurious
+conflicts. The first sync after upgrading will be slow.<BR>
+<BR>
+<LI CLASS="li-itemize">A number of internal functions have been changed to reduce the
+amount of memory allocation, especially during the first
+synchronization. This should help power users with very big replicas.<BR>
+<BR>
+<LI CLASS="li-itemize">Reimplementation of low-level remote procedure call stuff, in
+preparation for adding rsync-like smart file transfer in a later
+release. <BR>
+<BR>
+<LI CLASS="li-itemize">Miscellaneous bug fixes.
+
+ </UL>
+
+Changes since 1.180:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+<B>Incompatible change:</B>
+ Archive format has changed. Make sure you
+synchronize your replicas before upgrading, to avoid spurious
+conflicts. The first sync after upgrading will be slow.<BR>
+<BR>
+<LI CLASS="li-itemize">Fixed some small bugs in the interpretation of ignore patterns. <BR>
+<BR>
+<LI CLASS="li-itemize">Fixed some problems that were preventing the Windows version
+from working correctly when click-started.<BR>
+<BR>
+<LI CLASS="li-itemize">Fixes to treatment of file permissions under Windows, which were
+causing spurious reports of different permissions when synchronizing
+between windows and unix systems.<BR>
+<BR>
+<LI CLASS="li-itemize">Fixed one more non-tail-recursive list processing function,
+which was causing stack overflows when synchronizing very large
+replicas.
+
+ </UL>
+
+Changes since 1.169:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+The text user interface now provides commands for ignoring
+ files.
+<LI CLASS="li-itemize">We found and fixed some <EM>more</EM> non-tail-recursive list
+ processing functions. Some power users have reported success with
+ very large replicas.
+<LI CLASS="li-itemize"><B>Incompatible change:</B>
+ Files ending in <CODE>.tmp</CODE> are no longer ignored automatically. If you want
+to ignore such files, put an appropriate ignore pattern in your profile.<BR>
+<BR>
+<LI CLASS="li-itemize"><B>Incompatible change:</B>
+ The syntax of <TT>ignore</TT> and <TT>follow</TT>
+patterns has changed. Instead of putting a line of the form
+<PRE CLASS="verbatim">
+ ignore = <regexp>
+</PRE>in your profile (<TT>.unison/default.prf</TT>), you should put:
+<PRE CLASS="verbatim">
+ ignore = Regexp <regexp>
+</PRE>Moreover, two other styles of pattern are also recognized:
+<PRE CLASS="verbatim">
+ ignore = Name <name>
+</PRE>matches any path in which one component matches <CODE><name></CODE>, while
+<PRE CLASS="verbatim">
+ ignore = Path <path>
+</PRE>matches exactly the path <CODE><path></CODE>.<BR>
+<BR>
+Standard “globbing” conventions can be used in <CODE><name></CODE> and
+<CODE><path></CODE>:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+a <CODE>?</CODE> matches any single character except <CODE>/</CODE>
+<LI CLASS="li-itemize">a <CODE>*</CODE> matches any sequence of characters not including <CODE>/</CODE>
+<LI CLASS="li-itemize"><CODE>[xyz]</CODE> matches any character from the set {<TT><I>x</I></TT>,
+ <TT><I>y</I></TT>, <TT><I>z</I></TT> }
+<LI CLASS="li-itemize"><CODE>{a,bb,ccc}</CODE> matches any one of <CODE>a</CODE>, <CODE>bb</CODE>, or
+ <CODE>ccc</CODE>.
+</UL><BR>
+See the user manual for some examples.
+
+ </UL>
+
+Changes since 1.146:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Some users were reporting stack overflows when synchronizing
+ huge directories. We found and fixed some non-tail-recursive list
+ processing functions, which we hope will solve the problem. Please
+ give it a try and let us know.
+<LI CLASS="li-itemize">Major additions to the documentation.
+
+ </UL>
+
+Changes since 1.142:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+Major internal tidying and many small bugfixes.
+<LI CLASS="li-itemize">Major additions to the user manual.
+<LI CLASS="li-itemize">Unison can now be started with no arguments – it will prompt
+automatically for the name of a profile file containing the roots to
+be synchronized. This makes it possible to start the graphical UI
+from a desktop icon.
+<LI CLASS="li-itemize">Fixed a small bug where the text UI on NT was raising a 'no such
+ signal' exception.
+
+ </UL>
+
+Changes since 1.139:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+The precompiled windows binary in the last release was compiled
+with an old OCaml compiler, causing propagation of permissions not to
+work (and perhaps leading to some other strange behaviors we've heard
+reports about). This has been corrected. If you're using precompiled
+binaries on Windows, please upgrade.
+<LI CLASS="li-itemize">Added a <CODE>-debug</CODE> command line flag, which controls debugging
+of various modules. Say <CODE>-debug XXX</CODE> to enable debug tracing for
+module <CODE>XXX</CODE>, or <CODE>-debug all</CODE> to turn on absolutely everything.
+<LI CLASS="li-itemize">Fixed a small bug where the text UI on NT was raising a 'no such signal'
+exception.
+
+ </UL>
+
+Changes since 1.111:
+ <UL CLASS="itemize"><LI CLASS="li-itemize">
+
+<B>Incompatible change:</B>
+ The names and formats of the preference files in
+the .unison directory have changed. In particular:
+<UL CLASS="itemize"><LI CLASS="li-itemize">
+the file “prefs” should be renamed to default.prf
+<LI CLASS="li-itemize">the contents of the file “ignore” should be merged into
+ default.prf. Each line of the form <CODE>REGEXP</CODE> in ignore should
+ become a line of the form <CODE>ignore = REGEXP</CODE> in default.prf.
+</UL>
+<LI CLASS="li-itemize">Unison now handles permission bits and symbolic links. See the
+manual for details.<BR>
+<BR>
+<LI CLASS="li-itemize">You can now have different preference files in your .unison
+directory. If you start unison like this
+<PRE CLASS="verbatim">
+ unison profilename
+</PRE>(i.e. with just one “anonymous” command-line argument), then the
+file <CODE>~/.unison/profilename.prf</CODE> will be loaded instead of
+<CODE>default.prf</CODE>. <BR>
+<BR>
+<LI CLASS="li-itemize">Some improvements to terminal handling in the text user interface<BR>
+<BR>
+<LI CLASS="li-itemize">Added a switch -killServer that terminates the remote server process
+when the unison client is shutting down, even when using sockets for
+communication. (By default, a remote server created using ssh/rsh is
+terminated automatically, while a socket server is left running.)
+<LI CLASS="li-itemize">When started in 'socket server' mode, unison prints 'server started' on
+ stderr when it is ready to accept connections.
+ (This may be useful for scripts that want to tell when a socket-mode server
+ has finished initalization.)
+<LI CLASS="li-itemize">We now make a nightly mirror of our current internal development
+ tree, in case anyone wants an up-to-the-minute version to hack
+ around with.
+<LI CLASS="li-itemize">Added a file CONTRIB with some suggestions for how to help us
+make Unison better.
+
+ </UL>
+
+</div><BR>
+<BR>
+<!--HTMLFOOT-->
+<!--ENDHTML-->
+<!--FOOTER-->
+<HR SIZE=2><BLOCKQUOTE CLASS="quote"><EM>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
+</EM><A HREF="http://pauillac.inria.fr/~maranget/hevea/index.html"><EM>H<FONT SIZE=2><sup>E</sup></FONT>V<FONT SIZE=2><sup>E</sup></FONT>A</EM></A><EM>.</EM></BLOCKQUOTE></BODY>
+</HTML>
diff --git a/unison240-missing-documentation.patch b/unison240-missing-documentation.patch
new file mode 100644
index 0000000..e70d543
--- /dev/null
+++ b/unison240-missing-documentation.patch
@@ -0,0 +1,4474 @@
+diff -up unison-2.40.63/strings.ml.orig unison-2.40.63/strings.ml
+--- unison-2.40.63/strings.ml.orig 2012-01-22 12:05:03.953273614 +0100
++++ unison-2.40.63/strings.ml 2012-01-22 12:05:39.599904881 +0100
+@@ -1,2 +1,4468 @@
+-(* Dummy strings.ml *)
+-let docs = []
++(* DO NOT MODIFY.
++ This file has been automatically generated, see docs.ml. *)
++
++let docs =
++ ("about", ("About Unison",
++ "Unison File Synchronizer\n\
++ Version 2.40.69\n\
++ \n\
++ "))
++::
++ ("", ("Overview",
++ "\n\
++ \032 Unison is a file-synchronization tool for Unix and Windows. It allows\n\
++ \032 two replicas of a collection of files and directories to be stored on\n\
++ \032 different hosts (or different disks on the same host), modified\n\
++ \032 separately, and then brought up to date by propagating the changes in\n\
++ \032 each replica to the other.\n\
++ \n\
++ \032 Unison shares a number of features with tools such as configuration\n\
++ \032 management packages (CVS (http://www.cyclic.com/), PRCS\n\
++ \032 (http://www.XCF.Berkeley.EDU/~jmacd/prcs.html), etc.), distributed\n\
++ \032 filesystems (Coda (http://www.coda.cs.cmu.edu/), etc.), uni-directional\n\
++ \032 mirroring utilities (rsync (http://samba.anu.edu.au/rsync/), etc.), and\n\
++ \032 other synchronizers (Intellisync (http://www.pumatech.com), Reconcile\n\
++ \032 (http://www.merl.com/reports/TR99-14/), etc). However, there are\n\
++ \032 several points where it differs:\n\
++ \032 * Unison runs on both Windows (95, 98, NT, 2k, and XP) and Unix (OSX,\n\
++ \032 Solaris, Linux, etc.) systems. Moreover, Unison works across\n\
++ \032 platforms, allowing you to synchronize a Windows laptop with a Unix\n\
++ \032 server, for example.\n\
++ \032 * Unlike a distributed filesystem, Unison is a user-level program:\n\
++ \032 there is no need to modify the kernel or to have superuser\n\
++ \032 privileges on either host.\n\
++ \032 * Unlike simple mirroring or backup utilities, Unison can deal with\n\
++ \032 updates to both replicas of a distributed directory structure.\n\
++ \032 Updates that do not conflict are propagated automatically.\n\
++ \032 Conflicting updates are detected and displayed.\n\
++ \032 * Unison works between any pair of machines connected to the\n\
++ \032 internet, communicating over either a direct socket link or\n\
++ \032 tunneling over an encrypted ssh connection. It is careful with\n\
++ \032 network bandwidth, and runs well over slow links such as PPP\n\
++ \032 connections. Transfers of small updates to large files are\n\
++ \032 optimized using a compression protocol similar to rsync.\n\
++ \032 * Unison has a clear and precise specification, described below.\n\
++ \032 * Unison is resilient to failure. It is careful to leave the replicas\n\
++ \032 and its own private structures in a sensible state at all times,\n\
++ \032 even in case of abnormal termination or communication failures.\n\
++ \032 * Unison is free; full source code is available under the GNU Public\n\
++ \032 License.\n\
++ \n\
++ "))
++::
++ ("", ("Preface",
++ "\n\
++ "))
++::
++ ("people", ("People",
++ "People\n\
++ \n\
++ \032 Benjamin Pierce (http://www.cis.upenn.edu/~bcpierce/) leads the Unison\n\
++ \032 project. The current version of Unison was designed and implemented by\n\
++ \032 Trevor Jim (http://www.research.att.com/~trevor/), Benjamin Pierce\n\
++ \032 (http://www.cis.upenn.edu/~bcpierce/), and Jerome Vouillon\n\
++ \032 (http://www.pps.jussieu.fr/~vouillon/), with Alan Schmitt\n\
++ \032 (http://alan.petitepomme.net/), Malo Denielou, Zhe Yang\n\
++ \032 (http://www.brics.dk/~zheyang/), Sylvain Gommier, and Matthieu Goulay.\n\
++ \032 The Mac user interface was started by Trevor Jim and enormously\n\
++ \032 improved by Ben Willmore. Our implementation of the rsync\n\
++ \032 (http://samba.org/rsync/) protocol was built by Norman Ramsey\n\
++ \032 (http://www.eecs.harvard.edu/~nr/) and Sylvain Gommier. It is based on\n\
++ \032 Andrew Tridgell (http://samba.anu.edu.au/~tridge/)'s thesis work\n\
++ \032 (http://samba.anu.edu.au/~tridge/phd_thesis.pdf) and inspired by his\n\
++ \032 rsync (http://samba.org/rsync/) utility. The mirroring and merging\n\
++ \032 functionality was implemented by Sylvain Roy, improved by Malo\n\
++ \032 Denielou, and improved yet further by Stephane Lescuyer. Jacques\n\
++ \032 Garrigue (http://wwwfun.kurims.kyoto-u.ac.jp/~garrigue/) contributed\n\
++ \032 the original Gtk version of the user interface; the Gtk2 version was\n\
++ \032 built by Stephen Tse. Sundar Balasubramaniam helped build a prototype\n\
++ \032 implementation of an earlier synchronizer in Java. Insik Shin\n\
++ \032 (http://www.cis.upenn.edu/~ishin/) and Insup Lee\n\
++ \032 (http://www.cis.upenn.edu/~lee/) contributed design ideas to this\n\
++ \032 implementation. Cedric Fournet\n\
++ \032 (http://research.microsoft.com/~fournet/) contributed to an even\n\
++ \032 earlier prototype.\n\
++ \n\
++ "))
++::
++ ("lists", ("Mailing Lists and Bug Reporting",
++ "Mailing Lists and Bug Reporting\n\
++ \n\
++ Mailing Lists:\n\
++ \n\
++ \032 Moderated mailing lists are available for bug reporting, announcements\n\
++ \032 of new versions, discussions among users, and discussions among\n\
++ \032 developers. See\n\
++ \n\
++ \032 http://www.cis.upenn.edu/~bcpierce/unison/lists.html\n\
++ \n\
++ \032 for more information.\n\
++ \n\
++ "))
++::
++ ("status", ("Development Status",
++ "Development Status\n\
++ \n\
++ \032 Unison is no longer under active development as a research project.\n\
++ \032 (Our research efforts are now focused on a follow-on project called\n\
++ \032 Harmony, described at http://www.cis.upenn.edu/~bcpierce/harmony.) At\n\
++ \032 this point, there is no one whose job it is to maintain Unison, fix\n\
++ \032 bugs, or answer questions.\n\
++ \n\
++ \032 However, the original developers are all still using Unison daily. It\n\
++ \032 will continue to be maintained and supported for the foreseeable\n\
++ \032 future, and we will occasionally release new versions with bug fixes,\n\
++ \032 small improvements, and contributed patches.\n\
++ \n\
++ \032 Reports of bugs affecting correctness or safety are of interest to many\n\
++ \032 people and will generally get high priority. Other bug reports will be\n\
++ \032 looked at as time permits. Bugs should be reported to the users list at\n\
++ \032 unison-users at yahoogroups.com (mailto:unison-users at yahoogroups.com).\n\
++ \n\
++ \032 Feature requests are welcome, but will probably just be added to the\n\
++ \032 ever-growing todo list. They should also be sent to\n\
++ \032 unison-users at yahoogroups.com (mailto:unison-users at yahoogroups.com).\n\
++ \n\
++ \032 Patches are even more welcome. They should be sent to\n\
++ \032 unison-hackers at lists.seas.upenn.edu\n\
++ \032 (mailto:unison-hackers at lists.seas.upenn.edu). (Since safety and\n\
++ \032 robustness are Unison's most important properties, patches will be held\n\
++ \032 to high standards of clear design and clean coding.) If you want to\n\
++ \032 contribute to Unison, start by downloading the developer tarball from\n\
++ \032 the download page. For some details on how the code is organized, etc.,\n\
++ \032 see the file CONTRIB.\n\
++ \n\
++ "))
++::
++ ("copying", ("Copying",
++ "Copying\n\
++ \n\
++ \032 This file is part of Unison.\n\
++ \n\
++ \032 Unison is free software: you can redistribute it and/or modify it under\n\
++ \032 the terms of the GNU General Public License as published by the Free\n\
++ \032 Software Foundation, either version 3 of the License, or (at your\n\
++ \032 option) any later version.\n\
++ \n\
++ \032 Unison is distributed in the hope that it will be useful, but WITHOUT\n\
++ \032 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or\n\
++ \032 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License\n\
++ \032 for more details.\n\
++ \n\
++ \032 The GNU Public License can be found at http://www.gnu.org/licenses. A\n\
++ \032 copy is also included in the Unison source distribution in the file\n\
++ \032 COPYING.\n\
++ \n\
++ "))
++::
++ ("ack", ("Acknowledgements",
++ "Acknowledgements\n\
++ \n\
++ \032 Work on Unison has been supported by the National Science Foundation\n\
++ \032 under grants CCR-9701826 and ITR-0113226, Principles and Practice of\n\
++ \032 Synchronization, and by University of Pennsylvania's Institute for\n\
++ \032 Research in Cognitive Science (IRCS).\n\
++ \n\
++ "))
++::
++ ("install", ("Installation",
++ "Installation\n\
++ \n\
++ \032 Unison is designed to be easy to install. The following sequence of\n\
++ \032 steps should get you a fully working installation in a few minutes. If\n\
++ \032 you run into trouble, you may find the suggestions on the Frequently\n\
++ \032 Asked Questions page\n\
++ \032 (http://www.cis.upenn.edu/~bcpierce/unison/faq.html) helpful. Pre-built\n\
++ \032 binaries are available for a variety of platforms.\n\
++ \n\
++ \032 Unison can be used with either of two user interfaces:\n\
++ \032 1. a simple textual interface, suitable for dumb terminals (and\n\
++ \032 running from scripts), and\n\
++ \032 2. a more sophisticated grapical interface, based on Gtk2 (on\n\
++ \032 Linux/Windows) or the native UI framework (on OSX).\n\
++ \n\
++ \032 You will need to install a copy of Unison on every machine that you\n\
++ \032 want to synchronize. However, you only need the version with a\n\
++ \032 graphical user interface (if you want a GUI at all) on the machine\n\
++ \032 where you're actually going to display the interface (the CLIENT\n\
++ \032 machine). Other machines that you synchronize with can get along just\n\
++ \032 fine with the textual version.\n\
++ \n\
++ Downloading Unison\n\
++ \n\
++ \032 The Unison download site lives under\n\
++ \032 http://www.cis.upenn.edu/~bcpierce/unison.\n\
++ \n\
++ \032 If a pre-built binary of Unison is available for the client machine's\n\
++ \032 architecture, just download it and put it somewhere in your search path\n\
++ \032 (if you're going to invoke it from the command line) or on your desktop\n\
++ \032 (if you'll be click-starting it).\n\
++ \n\
++ \032 The executable file for the graphical version (with a name including\n\
++ \032 gtkui) actually provides both interfaces: the graphical one appears by\n\
++ \032 default, while the textual interface can be selected by including -ui\n\
++ \032 text on the command line. The textui executable provides just the\n\
++ \032 textual interface.\n\
++ \n\
++ \032 If you don't see a pre-built executable for your architecture, you'll\n\
++ \032 need to build it yourself. See the section \"Building Unison\" . There\n\
++ \032 are also a small number of contributed ports to other architectures\n\
++ \032 that are not maintained by us. See the Contributed Ports page\n\
++ \032 (http://www.cis.upenn.edu/~bcpierce/unison/download.html) to check\n\
++ \032 what's available.\n\
++ \n\
++ \032 Check to make sure that what you have downloaded is really executable.\n\
++ \032 Either click-start it, or type \"unison -version\" at the command line.\n\
++ \n\
++ \032 Unison can be used in three different modes: with different directories\n\
++ \032 on a single machine, with a remote machine over a direct socket\n\
++ \032 connection, or with a remote machine using ssh for authentication and\n\
++ \032 secure transfer. If you intend to use the last option, you may need to\n\
++ \032 install ssh; see the section \"Installing Ssh\" .\n\
++ \n\
++ Running Unison\n\
++ \n\
++ \032 Once you've got Unison installed on at least one system, read the\n\
++ \032 section \"Tutorial\" of the user manual (or type \"unison -doc tutorial\")\n\
++ \032 for instructions on how to get started.\n\
++ \n\
++ Upgrading\n\
++ \n\
++ \032 Upgrading to a new version of Unison is as simple as throwing away the\n\
++ \032 old binary and installing the new one.\n\
++ \n\
++ \032 Before upgrading, it is a good idea to run the old version one last\n\
++ \032 time, to make sure all your replicas are completely synchronized. A new\n\
++ \032 version of Unison will sometimes introduce a different format for the\n\
++ \032 archive files used to remember information about the previous state of\n\
++ \032 the replicas. In this case, the old archive will be ignored (not\n\
++ \032 deleted -- if you roll back to the previous version of Unison, you will\n\
++ \032 find the old archives intact), which means that any differences between\n\
++ \032 the replicas will show up as conflicts that need to be resolved\n\
++ \032 manually.\n\
++ \n\
++ Building Unison from Scratch\n\
++ \n\
++ \032 If a pre-built image is not available, you will need to compile it from\n\
++ \032 scratch; the sources are available from the same place as the binaries.\n\
++ \n\
++ \032 In principle, Unison should work on any platform to which OCaml has\n\
++ \032 been ported and on which the Unix module is fully implemented. It has\n\
++ \032 been tested on many flavors of Windows (98, NT, 2000, XP) and Unix (OS\n\
++ \032 X, Solaris, Linux, FreeBSD), and on both 32- and 64-bit architectures.\n\
++ \n\
++ Unix\n\
++ \n\
++ \032 You'll need the Objective Caml compiler (version 3.11.2 or later),\n\
++ \032 which is available from http://caml.inria.fr. Building and installing\n\
++ \032 OCaml on Unix systems is very straightforward; just follow the\n\
++ \032 instructions in the distribution. You'll probably want to build the\n\
++ \032 native-code compiler in addition to the bytecode compiler, as Unison\n\
++ \032 runs much faster when compiled to native code, but this is not\n\
++ \032 absolutely necessary. (Quick start: on many systems, the following\n\
++ \032 sequence of commands will get you a working and installed compiler:\n\
++ \032 first do make world opt, then su to root and do make install.)\n\
++ \n\
++ \032 You'll also need the GNU make utility, standard on many Unix systems.\n\
++ \032 (Type \"make -version\" to check that you've got the GNU version.)\n\
++ \n\
++ \032 Once you've got OCaml installed, grab a copy of the Unison sources,\n\
++ \032 unzip and untar them, change to the new \"unison\" directory, and type\n\
++ \032 \"make UISTYLE=text.\" The result should be an executable file called\n\
++ \032 \"unison\". Type \"./unison\" to make sure the program is executable. You\n\
++ \032 should get back a usage message.\n\
++ \n\
++ \032 If you want to build the graphical user interface, you will need to\n\
++ \032 install two additional things:\n\
++ \032 * The Gtk2 libraries. These areavailable from http://www.gtk.org and\n\
++ \032 are standard on many Unix installations.\n\
++ \032 * The lablgtk2 OCaml library. Grab the developers' tarball from\n\
++ \n\
++ \032 http://wwwfun.kurims.kyoto-u.ac.jp/soft/olabl/lablgtk.html,\n\
++ \032 untar it, and follow the instructions to build and install it.\n\
++ \032 (Quick start: make configure, then make, then make opt, then su and\n\
++ \032 make install.)\n\
++ \n\
++ \032 Now build unison. If your search paths are set up correctly, simply\n\
++ \032 typing make again should build a unison executable with a Gtk2\n\
++ \032 graphical interface. (In previous releases of Unison, it was necessary\n\
++ \032 to add UISTYLE=gtk2 to the 'make' command above. This requirement has\n\
++ \032 been removed: the makefile should detect automatically when lablgtk2 is\n\
++ \032 present and set this flag automatically.)\n\
++ \n\
++ \032 Put the unison executable somewhere in your search path, either by\n\
++ \032 adding the Unison directory to your PATH variable or by copying the\n\
++ \032 executable to some standard directory where executables are stored.\n\
++ \n\
++ Mac OS X\n\
++ \n\
++ \032 To build the text-only user interface, follow the instructions above\n\
++ \032 for building on Unix systems. You should do this first, even if you are\n\
++ \032 also planning on building the GUI, just to make sure it works.\n\
++ \n\
++ \032 To build the basic GUI version, you'll first need to download and\n\
++ \032 install the XCode developer tools from Apple. Once this is done, just\n\
++ \032 type make UISTYLE=macnew in the src directory, and if things go well\n\
++ \032 you should get an application that you can move from\n\
++ \032 uimacnew/build/Default/Unison.app to wherever you want it.\n\
++ \n\
++ \032 There is also an experimental GUI with a somewhat smoother look and\n\
++ \032 feel. To compile this one (once you've got the basic one working),\n\
++ \032 proceed as follows:\n\
++ \032 1. Go to the uimacnew09 directory and double-click the file\n\
++ \032 BWToolkit.ibplugin.\n\
++ \032 2. Go back up to the src directory and type make UISTYLE=macnew09.\n\
++ \032 3. You should get an application built for you at\n\
++ \032 uimacnew09/build/Default/Unison.app.\n\
++ \n\
++ Windows\n\
++ \n\
++ \032 Although the binary distribution should work on any version of Windows,\n\
++ \032 some people may want to build Unison from scratch on those systems too.\n\
++ \n\
++ Bytecode version:\n\
++ \n\
++ \032 The simpler but slower compilation option to build a Unison executable\n\
++ \032 is to build a bytecode version. You need first install Windows version\n\
++ \032 of the OCaml compiler (version 3.07 or later, available from\n\
++ \032 http://caml.inria.fr). Then grab a copy of Unison sources and type\n\
++ \032 make NATIVE=false\n\
++ \n\
++ \032 to compile the bytecode. The result should be an executable file called\n\
++ \032 unison.exe.\n\
++ \n\
++ Native version:\n\
++ \n\
++ \032 Building a more efficient, native version of Unison on Windows requires\n\
++ \032 a little more work. See the file INSTALL.win32 in the source code\n\
++ \032 distribution.\n\
++ \n\
++ Installation Options\n\
++ \n\
++ \032 The Makefile in the distribution includes several switches that can be\n\
++ \032 used to control how Unison is built. Here are the most useful ones:\n\
++ \032 * Building with NATIVE=true uses the native-code OCaml compiler,\n\
++ \032 yielding an executable that will run quite a bit faster. We use\n\
++ \032 this for building distribution versions.\n\
++ \032 * Building with make DEBUGGING=true generates debugging symbols.\n\
++ \032 * Building with make STATIC=true generates a (mostly) statically\n\
++ \032 linked executable. We use this for building distribution versions,\n\
++ \032 for portability.\n\
++ \n\
++ "))
++::
++ ("tutorial", ("Tutorial",
++ "Tutorial\n\
++ \n\
++ Preliminaries\n\
++ \n\
++ \032 Unison can be used with either of two user interfaces:\n\
++ \032 1. a straightforward textual interface and\n\
++ \032 2. a more sophisticated graphical interface\n\
++ \n\
++ \032 The textual interface is more convenient for running from scripts and\n\
++ \032 works on dumb terminals; the graphical interface is better for most\n\
++ \032 interactive use. For this tutorial, you can use either. If you are\n\
++ \032 running Unison from the command line, just typing unison will select\n\
++ \032 either the text or the graphical interface, depending on which has been\n\
++ \032 selected as default when the executable you are running was built. You\n\
++ \032 can force the text interface even if graphical is the default by adding\n\
++ \032 -ui text. The other command-line arguments to both versions are\n\
++ \032 identical.\n\
++ \n\
++ \032 The graphical version can also be run directly by clicking on its icon,\n\
++ \032 but this may require a little set-up (see the section \"Click-starting\n\
++ \032 Unison\" ). For this tutorial, we assume that you're starting it from\n\
++ \032 the command line.\n\
++ \n\
++ \032 Unison can synchronize files and directories on a single machine, or\n\
++ \032 between two machines on a network. (The same program runs on both\n\
++ \032 machines; the only difference is which one is responsible for\n\
++ \032 displaying the user interface.) If you're only interested in a\n\
++ \032 single-machine setup, then let's call that machine the CLIENT . If\n\
++ \032 you're synchronizing two machines, let's call them CLIENT and SERVER .\n\
++ \n\
++ Local Usage\n\
++ \n\
++ \032 Let's get the client machine set up first and see how to synchronize\n\
++ \032 two directories on a single machine.\n\
++ \n\
++ \032 Follow the instructions in the section \"Installation\" to either\n\
++ \032 download or build an executable version of Unison, and install it\n\
++ \032 somewhere on your search path. (If you just want to use the textual\n\
++ \032 user interface, download the appropriate textui binary. If you just\n\
++ \032 want to the graphical interface--or if you will use both interfaces\n\
++ \032 [the gtkui binary actually has both compiled in]--then download the\n\
++ \032 gtkui binary.)\n\
++ \n\
++ \032 Create a small test directory a.tmp containing a couple of files and/or\n\
++ \032 subdirectories, e.g.,\n\
++ \032 mkdir a.tmp\n\
++ \032 touch a.tmp/a a.tmp/b\n\
++ \032 mkdir a.tmp/d\n\
++ \032 touch a.tmp/d/f\n\
++ \n\
++ \032 Copy this directory to b.tmp:\n\
++ \032 cp -r a.tmp b.tmp\n\
++ \n\
++ \032 Now try synchronizing a.tmp and b.tmp. (Since they are identical,\n\
++ \032 synchronizing them won't propagate any changes, but Unison will\n\
++ \032 remember the current state of both directories so that it will be able\n\
++ \032 to tell next time what has changed.) Type:\n\
++ \032 unison a.tmp b.tmp\n\
++ \n\
++ \032 (You may need to add -ui text, depending how your unison binary was\n\
++ \032 built.)\n\
++ \n\
++ \032 Textual Interface:\n\
++ \032 * You should see a message notifying you that all the files are\n\
++ \032 actually equal and then get returned to the command line.\n\
++ \n\
++ \032 Graphical Interface:\n\
++ \032 * You should get a big empty window with a message at the bottom\n\
++ \032 notifying you that all files are identical. Choose the Exit item\n\
++ \032 from the File menu to get back to the command line.\n\
++ \n\
++ \032 Next, make some changes in a.tmp and/or b.tmp. For example:\n\
++ \032 rm a.tmp/a\n\
++ \032 echo \"Hello\" > a.tmp/b\n\
++ \032 echo \"Hello\" > b.tmp/b\n\
++ \032 date > b.tmp/c\n\
++ \032 echo \"Hi there\" > a.tmp/d/h\n\
++ \032 echo \"Hello there\" > b.tmp/d/h\n\
++ \n\
++ \032 Run Unison again:\n\
++ \032 unison a.tmp b.tmp\n\
++ \n\
++ \032 This time, the user interface will display only the files that have\n\
++ \032 changed. If a file has been modified in just one replica, then it will\n\
++ \032 be displayed with an arrow indicating the direction that the change\n\
++ \032 needs to be propagated. For example,\n\
++ \032 <--- new file c [f]\n\
++ \n\
++ \032 indicates that the file c has been modified only in the second replica,\n\
++ \032 and that the default action is therefore to propagate the new version\n\
++ \032 to the first replica. To follow Unison's recommendation, press the \"f\"\n\
++ \032 at the prompt.\n\
++ \n\
++ \032 If both replicas are modified and their contents are different, then\n\
++ \032 the changes are in conflict: <-?-> is displayed to indicate that Unison\n\
++ \032 needs guidance on which replica should override the other.\n\
++ \032 new file <-?-> new file d/h []\n\
++ \n\
++ \032 By default, neither version will be propagated and both replicas will\n\
++ \032 remain as they are.\n\
++ \n\
++ \032 If both replicas have been modified but their new contents are the same\n\
++ \032 (as with the file b), then no propagation is necessary and nothing is\n\
++ \032 shown. Unison simply notes that the file is up to date.\n\
++ \n\
++ \032 These display conventions are used by both versions of the user\n\
++ \032 interface. The only difference lies in the way in which Unison's\n\
++ \032 default actions are either accepted or overridden by the user.\n\
++ \n\
++ \032 Textual Interface:\n\
++ \032 * The status of each modified file is displayed, in turn. When the\n\
++ \032 copies of a file in the two replicas are not identical, the user\n\
++ \032 interface will ask for instructions as to how to propagate the\n\
++ \032 change. If some default action is indicated (by an arrow), you can\n\
++ \032 simply press Return to go on to the next changed file. If you want\n\
++ \032 to do something different with this file, press \"<\" or \">\" to force\n\
++ \032 the change to be propagated from right to left or from left to\n\
++ \032 right, or else press \"/\" to skip this file and leave both replicas\n\
++ \032 alone. When it reaches the end of the list of modified files,\n\
++ \032 Unison will ask you one more time whether it should proceed with\n\
++ \032 the updates that have been selected.\n\
++ \032 When Unison stops to wait for input from the user, pressing \"?\"\n\
++ \032 will always give a list of possible responses and their meanings.\n\
++ \n\
++ \032 Graphical Interface:\n\
++ \032 * The main window shows all the files that have been modified in\n\
++ \032 either a.tmp or b.tmp. To override a default action (or to select\n\
++ \032 an action in the case when there is no default), first select the\n\
++ \032 file, either by clicking on its name or by using the up- and\n\
++ \032 down-arrow keys. Then press either the left-arrow or \"<\" key (to\n\
++ \032 cause the version in b.tmp to propagate to a.tmp) or the\n\
++ \032 right-arrow or \">\" key (which makes the a.tmp version override\n\
++ \032 b.tmp).\n\
++ \032 Every keyboard command can also be invoked from the menus at the\n\
++ \032 top of the user interface. (Conversely, each menu item is annotated\n\
++ \032 with its keyboard equivalent, if it has one.)\n\
++ \032 When you are satisfied with the directions for the propagation of\n\
++ \032 changes as shown in the main window, click the \"Go\" button to set\n\
++ \032 them in motion. A check sign will be displayed next to each\n\
++ \032 filename when the file has been dealt with.\n\
++ \n\
++ Remote Usage\n\
++ \n\
++ \032 Next, we'll get Unison set up to synchronize replicas on two different\n\
++ \032 machines.\n\
++ \n\
++ \032 Follow the instructions in the Installation section to download or\n\
++ \032 build an executable version of Unison on the server machine, and\n\
++ \032 install it somewhere on your search path. (It doesn't matter whether\n\
++ \032 you install the textual or graphical version, since the copy of Unison\n\
++ \032 on the server doesn't need to display any user interface at all.)\n\
++ \n\
++ \032 It is important that the version of Unison installed on the server\n\
++ \032 machine is the same as the version of Unison on the client machine. But\n\
++ \032 some flexibility on the version of Unison at the client side can be\n\
++ \032 achieved by using the -addversionno option; see the section\n\
++ \032 \"Preferences\" .\n\
++ \n\
++ \032 Now there is a decision to be made. Unison provides two methods for\n\
++ \032 communicating between the client and the server:\n\
++ \032 * Remote shell method: To use this method, you must have some way of\n\
++ \032 invoking remote commands on the server from the client's command\n\
++ \032 line, using a facility such as ssh. This method is more convenient\n\
++ \032 (since there is no need to manually start a \"unison server\" process\n\
++ \032 on the server) and also more secure (especially if you use ssh).\n\
++ \032 * Socket method: This method requires only that you can get TCP\n\
++ \032 packets from the client to the server and back. A draconian\n\
++ \032 firewall can prevent this, but otherwise it should work anywhere.\n\
++ \n\
++ \032 Decide which of these you want to try, and continue with the section\n\
++ \032 \"Remote Shell Method\" or the section \"Socket Method\" , as appropriate.\n\
++ \n\
++ Remote Shell Method\n\
++ \n\
++ \032 The standard remote shell facility on Unix systems is ssh, which\n\
++ \032 provides the same functionality as the older rsh but much better\n\
++ \032 security. Ssh is available from http://www.openssh.org. See\n\
++ \032 section [1]A.2 for installation instructions for the Windows version.\n\
++ \n\
++ \032 Running ssh requires some coordination between the client and server\n\
++ \032 machines to establish that the client is allowed to invoke commands on\n\
++ \032 the server; please refer to the ssh documentation for information on\n\
++ \032 how to set this up. The examples in this section use ssh, but you can\n\
++ \032 substitute rsh for ssh if you wish.\n\
++ \n\
++ \032 First, test that we can invoke Unison on the server from the client.\n\
++ \032 Typing\n\
++ \032 ssh remotehostname unison -version\n\
++ \n\
++ \032 should print the same version information as running\n\
++ \032 unison -version\n\
++ \n\
++ \032 locally on the client. If remote execution fails, then either something\n\
++ \032 is wrong with your ssh setup (e.g., \"permission denied\") or else the\n\
++ \032 search path that's being used when executing commands on the server\n\
++ \032 doesn't contain the unison executable (e.g., \"command not found\").\n\
++ \n\
++ \032 Create a test directory a.tmp in your home directory on the client\n\
++ \032 machine.\n\
++ \n\
++ \032 Test that the local unison client can start and connect to the remote\n\
++ \032 server. Type\n\
++ \032 unison -testServer a.tmp ssh://remotehostname/a.tmp\n\
++ \n\
++ \032 Now cd to your home directory and type:\n\
++ \032 unison a.tmp ssh://remotehostname/a.tmp\n\
++ \n\
++ \032 The result should be that the entire directory a.tmp is propagated from\n\
++ \032 the client to your home directory on the server.\n\
++ \n\
++ \032 After finishing the first synchronization, change a few files and try\n\
++ \032 synchronizing again. You should see similar results as in the local\n\
++ \032 case.\n\
++ \n\
++ \032 If your user name on the server is not the same as on the client, you\n\
++ \032 need to specify it on the command line:\n\
++ \032 unison a.tmp ssh://username@remotehostname/a.tmp\n\
++ \n\
++ \032 Notes:\n\
++ \032 * If you want to put a.tmp some place other than your home directory\n\
++ \032 on the remote host, you can give an absolute path for it by adding\n\
++ \032 an extra slash between remotehostname and the beginning of the\n\
++ \032 path:\n\
++ \032 unison a.tmp ssh://remotehostname//absolute/path/to/a.tmp\n\
++ \n\
++ \032 * You can give an explicit path for the unison executable on the\n\
++ \032 server by using the command-line option \"-servercmd\n\
++ \032 /full/path/name/of/unison\" or adding\n\
++ \032 \"servercmd=/full/path/name/of/unison\" to your profile (see the\n\
++ \032 section \"Profile\" ). Similarly, you can specify a explicit path for\n\
++ \032 the ssh program using the \"-sshcmd\" option. Extra arguments can be\n\
++ \032 passed to ssh by setting the -sshargs preference.\n\
++ \n\
++ Socket Method\n\
++ \n\
++ \032 Warning: The socket method is insecure: not only are the texts of\n\
++ \032 your changes transmitted over the network in unprotected form, it is\n\
++ \032 also possible for anyone in the world to connect to the server\n\
++ \032 process and read out the contents of your filesystem! (Of course, to\n\
++ \032 do this they must understand the protocol that Unison uses to\n\
++ \032 communicate between client and server, but all they need for this is\n\
++ \032 a copy of the Unison sources.) The socket method is provided only\n\
++ \032 for expert users with specific needs; everyone else should use the\n\
++ \032 ssh method.\n\
++ \n\
++ \032 To run Unison over a socket connection, you must start a Unison daemon\n\
++ \032 process on the server. This process runs continuously, waiting for\n\
++ \032 connections over a given socket from client machines running Unison and\n\
++ \032 processing their requests in turn.\n\
++ \n\
++ \032 To start the daemon, type\n\
++ \032 unison -socket NNNN\n\
++ \n\
++ \032 on the server machine, where NNNN is the socket number that the daemon\n\
++ \032 should listen on for connections from clients. (NNNN can be any large\n\
++ \032 number that is not being used by some other program; if NNNN is already\n\
++ \032 in use, Unison will exit with an error message.) Note that paths\n\
++ \032 specified by the client will be interpreted relative to the directory\n\
++ \032 in which you start the server process; this behavior is different from\n\
++ \032 the ssh case, where the path is relative to your home directory on the\n\
++ \032 server.\n\
++ \n\
++ \032 Create a test directory a.tmp in your home directory on the client\n\
++ \032 machine. Now type:\n\
++ \032 unison a.tmp socket://remotehostname:NNNN/a.tmp\n\
++ \n\
++ \032 The result should be that the entire directory a.tmp is propagated from\n\
++ \032 the client to the server (a.tmp will be created on the server in the\n\
++ \032 directory that the server was started from). After finishing the first\n\
++ \032 synchronization, change a few files and try synchronizing again. You\n\
++ \032 should see similar results as in the local case.\n\
++ \n\
++ \032 Since the socket method is not used by many people, its functionality\n\
++ \032 is rather limited. For example, the server can only deal with one\n\
++ \032 client at a time.\n\
++ \n\
++ Using Unison for All Your Files\n\
++ \n\
++ \032 Once you are comfortable with the basic operation of Unison, you may\n\
++ \032 find yourself wanting to use it regularly to synchronize your commonly\n\
++ \032 used files. There are several possible ways of going about this:\n\
++ \032 1. Synchronize your whole home directory, using the Ignore facility\n\
++ \032 (see the section \"Ignore\" ) to avoid synchronizing temporary files\n\
++ \032 and things that only belong on one host.\n\
++ \032 2. Create a subdirectory called shared (or current, or whatever) in\n\
++ \032 your home directory on each host, and put all the files you want to\n\
++ \032 synchronize into this directory.\n\
++ \032 3. Create a subdirectory called shared (or current, or whatever) in\n\
++ \032 your home directory on each host, and put links to all the files\n\
++ \032 you want to synchronize into this directory. Use the follow\n\
++ \032 preference (see the section \"Symbolic Links\" ) to make Unison treat\n\
++ \032 these links as transparent.\n\
++ \032 4. Make your home directory the root of the synchronization, but tell\n\
++ \032 Unison to synchronize only some of the files and subdirectories\n\
++ \032 within it on any given run. This can be accomplished by using the\n\
++ \032 -path switch on the command line:\n\
++ \032 unison /home/username ssh://remotehost//home/username -path shared\n\
++ \n\
++ \032 The -path option can be used as many times as needed, to\n\
++ \032 synchronize several files or subdirectories:\n\
++ \032 unison /home/username ssh://remotehost//home/username \\\n\
++ \032 -path shared \\\n\
++ \032 -path pub \\\n\
++ \032 -path .netscape/bookmarks.html\n\
++ \n\
++ \032 These -path arguments can also be put in your preference file. See\n\
++ \032 the section \"Preferences\" for an example.\n\
++ \n\
++ \032 Most people find that they only need to maintain a profile (or\n\
++ \032 profiles) on one of the hosts that they synchronize, since Unison is\n\
++ \032 always initiated from this host. (For example, if you're synchronizing\n\
++ \032 a laptop with a fileserver, you'll probably always run Unison on the\n\
++ \032 laptop.) This is a bit different from the usual situation with\n\
++ \032 asymmetric mirroring programs like rdist, where the mirroring operation\n\
++ \032 typically needs to be initiated from the machine with the most recent\n\
++ \032 changes. the section \"Profile\" covers the syntax of Unison profiles,\n\
++ \032 together with some sample profiles.\n\
++ \n\
++ \032 Some tips on improving Unison's performance can be found on the\n\
++ \032 Frequently Asked Questions page\n\
++ \032 (http://www.cis.upenn.edu/~bcpierce/unison/faq.html).\n\
++ \n\
++ Using Unison to Synchronize More Than Two Machines\n\
++ \n\
++ \032 Unison is designed for synchronizing pairs of replicas. However, it is\n\
++ \032 possible to use it to keep larger groups of machines in sync by\n\
++ \032 performing multiple pairwise synchronizations.\n\
++ \n\
++ \032 If you need to do this, the most reliable way to set things up is to\n\
++ \032 organize the machines into a \"star topology,\" with one machine\n\
++ \032 designated as the \"hub\" and the rest as \"spokes,\" and with each spoke\n\
++ \032 machine synchronizing only with the hub. The big advantage of the star\n\
++ \032 topology is that it eliminates the possibility of confusing \"spurious\n\
++ \032 conflicts\" arising from the fact that a separate archive is maintained\n\
++ \032 by Unison for every pair of hosts that it synchronizes.\n\
++ \n\
++ Going Further\n\
++ \n\
++ \032 On-line documentation for the various features of Unison can be\n\
++ \032 obtained either by typing\n\
++ \032 unison -doc topics\n\
++ \n\
++ \032 at the command line, or by selecting the Help menu in the graphical\n\
++ \032 user interface. The same information is also available in a typeset\n\
++ \032 User's Manual (HTML or PostScript format) through\n\
++ \032 http://www.cis.upenn.edu/~bcpierce/unison.\n\
++ \n\
++ \032 If you use Unison regularly, you should subscribe to one of the mailing\n\
++ \032 lists, to receive announcements of new versions. See the section\n\
++ \032 \"Mailing Lists\" .\n\
++ \n\
++ "))
++::
++ ("basics", ("Basic Concepts",
++ "Basic Concepts\n\
++ \n\
++ \032 To understand how Unison works, it is necessary to discuss a few\n\
++ \032 straightforward concepts. These concepts are developed more rigorously\n\
++ \032 and at more length in a number of papers, available at\n\
++ \032 http://www.cis.upenn.edu/~bcpierce/papers. But the informal\n\
++ \032 presentation here should be enough for most users.\n\
++ \n\
++ Roots\n\
++ \n\
++ \032 A replica's root tells Unison where to find a set of files to be\n\
++ \032 synchronized, either on the local machine or on a remote host. For\n\
++ \032 example,\n\
++ \032 relative/path/of/root\n\
++ \n\
++ \032 specifies a local root relative to the directory where Unison is\n\
++ \032 started, while\n\
++ \032 /absolute/path/of/root\n\
++ \n\
++ \032 specifies a root relative to the top of the local filesystem,\n\
++ \032 independent of where Unison is running. Remote roots can begin with\n\
++ \032 ssh://, rsh:// to indicate that the remote server should be started\n\
++ \032 with rsh or ssh:\n\
++ \032 ssh://remotehost//absolute/path/of/root\n\
++ \032 rsh://user@remotehost/relative/path/of/root\n\
++ \n\
++ \032 If the remote server is already running (in the socket mode), then the\n\
++ \032 syntax\n\
++ \032 socket://remotehost:portnum//absolute/path/of/root\n\
++ \032 socket://remotehost:portnum/relative/path/of/root\n\
++ \n\
++ \032 is used to specify the hostname and the port that the client Unison\n\
++ \032 should use to contact it.\n\
++ \n\
++ \032 The syntax for roots is based on that of URIs (described in RFC 2396).\n\
++ \032 The full grammar is:\n\
++ \032 replica ::= [protocol:]//[user@][host][:port][/path]\n\
++ \032 | path\n\
++ \n\
++ \032 protocol ::= file\n\
++ \032 | socket\n\
++ \032 | ssh\n\
++ \032 | rsh\n\
++ \n\
++ \032 user ::= [-_a-zA-Z0-9]+\n\
++ \n\
++ \032 host ::= [-_a-zA-Z0-9.]+\n\
++ \n\
++ \032 port ::= [0-9]+\n\
++ \n\
++ \032 When path is given without any protocol prefix, the protocol is assumed\n\
++ \032 to be file:. Under Windows, it is possible to synchronize with a remote\n\
++ \032 directory using the file: protocol over the Windows Network\n\
++ \032 Neighborhood. For example,\n\
++ \032 unison foo //host/drive/bar\n\
++ \n\
++ \032 synchronizes the local directory foo with the directory drive:\\bar on\n\
++ \032 the machine host, provided that host is accessible via Network\n\
++ \032 Neighborhood. When the file: protocol is used in this way, there is no\n\
++ \032 need for a Unison server to be running on the remote host. However,\n\
++ \032 running Unison this way is only a good idea if the remote host is\n\
++ \032 reached by a very fast network connection, since the full contents of\n\
++ \032 every file in the remote replica will have to be transferred to the\n\
++ \032 local machine to detect updates.\n\
++ \n\
++ \032 The names of roots are canonized by Unison before it uses them to\n\
++ \032 compute the names of the corresponding archive files, so\n\
++ \032 //saul//home/bcpierce/common and //saul.cis.upenn.edu/common will be\n\
++ \032 recognized as the same replica under different names.\n\
++ \n\
++ Paths\n\
++ \n\
++ \032 A path refers to a point within a set of files being synchronized; it\n\
++ \032 is specified relative to the root of the replica.\n\
++ \n\
++ \032 Formally, a path is just a sequence of names, separated by /. Note that\n\
++ \032 the path separator character is always a forward slash, no matter what\n\
++ \032 operating system Unison is running on. Forward slashes are converted to\n\
++ \032 backslashes as necessary when paths are converted to filenames in the\n\
++ \032 local filesystem on a particular host. (For example, suppose that we\n\
++ \032 run Unison on a Windows system, synchronizing the local root c:\\pierce\n\
++ \032 with the root ssh://saul.cis.upenn.edu/home/bcpierce on a Unix server.\n\
++ \032 Then the path current/todo.txt refers to the file\n\
++ \032 c:\\pierce\\current\\todo.txt on the client and\n\
++ \032 /home/bcpierce/current/todo.txt on the server.)\n\
++ \n\
++ \032 The empty path (i.e., the empty sequence of names) denotes the whole\n\
++ \032 replica. Unison displays the empty path as \"[root].\"\n\
++ \n\
++ \032 If p is a path and q is a path beginning with p, then q is said to be a\n\
++ \032 descendant of p. (Each path is also a descendant of itself.)\n\
++ \n\
++ What is an Update?\n\
++ \n\
++ \032 The contents of a path p in a particular replica could be a file, a\n\
++ \032 directory, a symbolic link, or absent (if p does not refer to anything\n\
++ \032 at all in that replica). More specifically:\n\
++ \032 * If p refers to an ordinary file, then the contents of p are the\n\
++ \032 actual contents of this file (a string of bytes) plus the current\n\
++ \032 permission bits of the file.\n\
++ \032 * If p refers to a symbolic link, then the contents of p are just the\n\
++ \032 string specifying where the link points.\n\
++ \032 * If p refers to a directory, then the contents of p are just the\n\
++ \032 token \"DIRECTORY\" plus the current permission bits of the\n\
++ \032 directory.\n\
++ \032 * If p does not refer to anything in this replica, then the contents\n\
++ \032 of p are the token \"ABSENT.\"\n\
++ \n\
++ \032 Unison keeps a record of the contents of each path after each\n\
++ \032 successful synchronization of that path (i.e., it remembers the\n\
++ \032 contents at the last moment when they were the same in the two\n\
++ \032 replicas).\n\
++ \n\
++ \032 We say that a path is updated (in some replica) if its current contents\n\
++ \032 are different from its contents the last time it was successfully\n\
++ \032 synchronized. Note that whether a path is updated has nothing to do\n\
++ \032 with its last modification time--Unison considers only the contents\n\
++ \032 when determining whether an update has occurred. This means that\n\
++ \032 touching a file without changing its contents will not be recognized as\n\
++ \032 an update. A file can even be changed several times and then changed\n\
++ \032 back to its original contents; as long as Unison is only run at the end\n\
++ \032 of this process, no update will be recognized.\n\
++ \n\
++ \032 What Unison actually calculates is a close approximation to this\n\
++ \032 definition; see the section \"Caveats and Shortcomings\" .\n\
++ \n\
++ What is a Conflict?\n\
++ \n\
++ \032 A path is said to be conflicting if the following conditions all hold:\n\
++ \032 1. it has been updated in one replica,\n\
++ \032 2. it or any of its descendants has been updated in the other replica,\n\
++ \032 and\n\
++ \032 3. its contents in the two replicas are not identical.\n\
++ \n\
++ Reconciliation\n\
++ \n\
++ \032 Unison operates in several distinct stages:\n\
++ \032 1. On each host, it compares its archive file (which records the state\n\
++ \032 of each path in the replica when it was last synchronized) with the\n\
++ \032 current contents of the replica, to determine which paths have been\n\
++ \032 updated.\n\
++ \032 2. It checks for \"false conflicts\" -- paths that have been updated on\n\
++ \032 both replicas, but whose current values are identical. These paths\n\
++ \032 are silently marked as synchronized in the archive files in both\n\
++ \032 replicas.\n\
++ \032 3. It displays all the updated paths to the user. For updates that do\n\
++ \032 not conflict, it suggests a default action (propagating the new\n\
++ \032 contents from the updated replica to the other). Conflicting\n\
++ \032 updates are just displayed. The user is given an opportunity to\n\
++ \032 examine the current state of affairs, change the default actions\n\
++ \032 for nonconflicting updates, and choose actions for conflicting\n\
++ \032 updates.\n\
++ \032 4. It performs the selected actions, one at a time. Each action is\n\
++ \032 performed by first transferring the new contents to a temporary\n\
++ \032 file on the receiving host, then atomically moving them into place.\n\
++ \032 5. It updates its archive files to reflect the new state of the\n\
++ \032 replicas.\n\
++ \n\
++ "))
++::
++ ("failures", ("Invariants",
++ "Invariants\n\
++ \n\
++ \032 Given the importance and delicacy of the job that it performs, it is\n\
++ \032 important to understand both what a synchronizer does under normal\n\
++ \032 conditions and what can happen under unusual conditions such as system\n\
++ \032 crashes and communication failures.\n\
++ \n\
++ \032 Unison is careful to protect both its internal state and the state of\n\
++ \032 the replicas at every point in this process. Specifically, the\n\
++ \032 following guarantees are enforced:\n\
++ \032 * At every moment, each path in each replica has either (1) its\n\
++ \032 original contents (i.e., no change at all has been made to this\n\
++ \032 path), or (2) its correct final contents (i.e., the value that the\n\
++ \032 user expected to be propagated from the other replica).\n\
++ \032 * At every moment, the information stored on disk about Unison's\n\
++ \032 private state can be either (1) unchanged, or (2) updated to\n\
++ \032 reflect those paths that have been successfully synchronized.\n\
++ \n\
++ \032 The upshot is that it is safe to interrupt Unison at any time, either\n\
++ \032 manually or accidentally. [Caveat: the above is almost true there are\n\
++ \032 occasionally brief periods where it is not (and, because of shortcoming\n\
++ \032 of the Posix filesystem API, cannot be); in particular, when it is\n\
++ \032 copying a file onto a directory or vice versa, it must first move the\n\
++ \032 original contents out of the way. If Unison gets interrupted during one\n\
++ \032 of these periods, some manual cleanup may be required. In this case, a\n\
++ \032 file called DANGER.README will be left in your home directory,\n\
++ \032 containing information about the operation that was interrupted. The\n\
++ \032 next time you try to run Unison, it will notice this file and warn you\n\
++ \032 about it.]\n\
++ \n\
++ \032 If an interruption happens while it is propagating updates, then there\n\
++ \032 may be some paths for which an update has been propagated but which\n\
++ \032 have not been marked as synchronized in Unison's archives. This is no\n\
++ \032 problem: the next time Unison runs, it will detect changes to these\n\
++ \032 paths in both replicas, notice that the contents are now equal, and\n\
++ \032 mark the paths as successfully updated when it writes back its private\n\
++ \032 state at the end of this run.\n\
++ \n\
++ \032 If Unison is interrupted, it may sometimes leave temporary working\n\
++ \032 files (with suffix .tmp) in the replicas. It is safe to delete these\n\
++ \032 files. Also, if the backups flag is set, Unison will leave around old\n\
++ \032 versions of files that it overwrites, with names like\n\
++ \032 file.0.unison.bak. These can be deleted safely when they are no longer\n\
++ \032 wanted.\n\
++ \n\
++ \032 Unison is not bothered by clock skew between the different hosts on\n\
++ \032 which it is running. It only performs comparisons between timestamps\n\
++ \032 obtained from the same host, and the only assumption it makes about\n\
++ \032 them is that the clock on each system always runs forward.\n\
++ \n\
++ \032 If Unison finds that its archive files have been deleted (or that the\n\
++ \032 archive format has changed and they cannot be read, or that they don't\n\
++ \032 exist because this is the first run of Unison on these particular\n\
++ \032 roots), it takes a conservative approach: it behaves as though the\n\
++ \032 replicas had both been completely empty at the point of the last\n\
++ \032 synchronization. The effect of this is that, on the first run, files\n\
++ \032 that exist in only one replica will be propagated to the other, while\n\
++ \032 files that exist in both replicas but are unequal will be marked as\n\
++ \032 conflicting.\n\
++ \n\
++ \032 Touching a file without changing its contents should never affect\n\
++ \032 whether or not Unison does an update. (When running with the fastcheck\n\
++ \032 preference set to true--the default on Unix systems--Unison uses file\n\
++ \032 modtimes for a quick first pass to tell which files have definitely not\n\
++ \032 changed; then, for each file that might have changed, it computes a\n\
++ \032 fingerprint of the file's contents and compares it against the\n\
++ \032 last-synchronized contents. Also, the -times option allows you to\n\
++ \032 synchronize file times, but it does not cause identical files to be\n\
++ \032 changed; Unison will only modify the file times.)\n\
++ \n\
++ \032 It is safe to \"brainwash\" Unison by deleting its archive files on both\n\
++ \032 replicas. The next time it runs, it will assume that all the files it\n\
++ \032 sees in the replicas are new.\n\
++ \n\
++ \032 It is safe to modify files while Unison is working. If Unison discovers\n\
++ \032 that it has propagated an out-of-date change, or that the file it is\n\
++ \032 updating has changed on the target replica, it will signal a failure\n\
++ \032 for that file. Run Unison again to propagate the latest change.\n\
++ \n\
++ \032 Changes to the ignore patterns from the user interface (e.g., using the\n\
++ \032 `i' key) are immediately reflected in the current profile.\n\
++ \n\
++ Caveats and Shortcomings\n\
++ \n\
++ \032 Here are some things to be careful of when using Unison.\n\
++ \032 * In the interests of speed, the update detection algorithm may\n\
++ \032 (depending on which OS architecture that you run Unison on)\n\
++ \032 actually use an approximation to the definition given in the\n\
++ \032 section \"What is an Update?\" .\n\
++ \032 In particular, the Unix implementation does not compare the actual\n\
++ \032 contents of files to their previous contents, but simply looks at\n\
++ \032 each file's inode number and modtime; if neither of these have\n\
++ \032 changed, then it concludes that the file has not been changed.\n\
++ \032 Under normal circumstances, this approximation is safe, in the\n\
++ \032 sense that it may sometimes detect \"false updates\" but will never\n\
++ \032 miss a real one. However, it is possible to fool it, for example by\n\
++ \032 using retouch to change a file's modtime back to a time in the\n\
++ \032 past.\n\
++ \032 * If you synchronize between a single-user filesystem and a shared\n\
++ \032 Unix server, you should pay attention to your permission bits: by\n\
++ \032 default, Unison will synchronize permissions verbatim, which may\n\
++ \032 leave group-writable files on the server that could be written over\n\
++ \032 by a lot of people.\n\
++ \032 You can control this by setting your umask on both computers to\n\
++ \032 something like 022, masking out the \"world write\" and \"group write\"\n\
++ \032 permission bits.\n\
++ \032 Unison does not synchronize the setuid and setgid bits, for\n\
++ \032 security.\n\
++ \032 * The graphical user interface is single-threaded. This means that if\n\
++ \032 Unison is performing some long-running operation, the display will\n\
++ \032 not be repainted until it finishes. We recommend not trying to do\n\
++ \032 anything with the user interface while Unison is in the middle of\n\
++ \032 detecting changes or propagating files.\n\
++ \032 * Unison does not understand hard links.\n\
++ \032 * It is important to be a little careful when renaming directories\n\
++ \032 containing ignored files.\n\
++ \032 For example, suppose Unison is synchronizing directory A between\n\
++ \032 the two machines called the \"local\" and the \"remote\" machine;\n\
++ \032 suppose directory A contains a subdirectory D; and suppose D on the\n\
++ \032 local machine contains a file or subdirectory P that matches an\n\
++ \032 ignore directive in the profile used to synchronize. Thus path\n\
++ \032 A/D/P exists on the local machine but not on the remote machine.\n\
++ \032 If D is renamed to D' on the remote machine, and this change is\n\
++ \032 propagated to the local machine, all such files or subdirectories P\n\
++ \032 will be deleted. This is because Unison sees the rename as a delete\n\
++ \032 and a separate create: it deletes the old directory (including the\n\
++ \032 ignored files) and creates a new one (not including the ignored\n\
++ \032 files, since they are completely invisible to it).\n\
++ \n\
++ "))
++::
++ ("", ("Reference Guide",
++ "\n\
++ \032 This section covers the features of Unison in detail.\n\
++ \n\
++ "))
++::
++ ("running", ("Running Unison",
++ "Running Unison\n\
++ \n\
++ \032 There are several ways to start Unison.\n\
++ \032 * Typing \"unison profile\" on the command line. Unison will look for a\n\
++ \032 file profile.prf in the .unison directory. If this file does not\n\
++ \032 specify a pair of roots, Unison will prompt for them and add them\n\
++ \032 to the information specified by the profile.\n\
++ \032 * Typing \"unison profile root1 root2\" on the command line. In this\n\
++ \032 case, Unison will use profile, which should not contain any root\n\
++ \032 directives.\n\
++ \032 * Typing \"unison root1 root2\" on the command line. This has the same\n\
++ \032 effect as typing \"unison default root1 root2.\"\n\
++ \032 * Typing just \"unison\" (or invoking Unison by clicking on a desktop\n\
++ \032 icon). In this case, Unison will ask for the profile to use for\n\
++ \032 synchronization (or create a new one, if necessary).\n\
++ \n\
++ The .unison Directory\n\
++ \n\
++ \032 Unison stores a variety of information in a private directory on each\n\
++ \032 host. If the environment variable UNISON is defined, then its value\n\
++ \032 will be used as the name of this directory. If UNISON is not defined,\n\
++ \032 then the name of the directory depends on which operating system you\n\
++ \032 are using. In Unix, the default is to use $HOME/.unison. In Windows, if\n\
++ \032 the environment variable USERPROFILE is defined, then the directory\n\
++ \032 will be $USERPROFILE\\.unison; otherwise if HOME is defined, it will be\n\
++ \032 $HOME\\.unison; otherwise, it will be c:\\.unison.\n\
++ \n\
++ \032 The archive file for each replica is found in the .unison directory on\n\
++ \032 that replica's host. Profiles (described below) are always taken from\n\
++ \032 the .unison directory on the client host.\n\
++ \n\
++ \032 Note that Unison maintains a completely different set of archive files\n\
++ \032 for each pair of roots.\n\
++ \n\
++ \032 We do not recommend synchronizing the whole .unison directory, as this\n\
++ \032 will involve frequent propagation of large archive files. It should be\n\
++ \032 safe to do it, though, if you really want to. Synchronizing just the\n\
++ \032 profile files in the .unison directory is definitely OK.\n\
++ \n\
++ Archive Files\n\
++ \n\
++ \032 The name of the archive file on each replica is calculated from\n\
++ \032 * the canonical names of all the hosts (short names like saul are\n\
++ \032 converted into full addresses like saul.cis.upenn.edu),\n\
++ \032 * the paths to the replicas on all the hosts (again, relative\n\
++ \032 pathnames, symbolic links, etc. are converted into full, absolute\n\
++ \032 paths), and\n\
++ \032 * an internal version number that is changed whenever a new Unison\n\
++ \032 release changes the format of the information stored in the\n\
++ \032 archive.\n\
++ \n\
++ \032 This method should work well for most users. However, it is\n\
++ \032 occasionally useful to change the way archive names are generated.\n\
++ \032 Unison provides two ways of doing this.\n\
++ \n\
++ \032 The function that finds the canonical hostname of the local host (which\n\
++ \032 is used, for example, in calculating the name of the archive file used\n\
++ \032 to remember which files have been synchronized) normally uses the\n\
++ \032 gethostname operating system call. However, if the environment variable\n\
++ \032 UNISONLOCALHOSTNAME is set, its value will be used instead. This makes\n\
++ \032 it easier to use Unison in situations where a machine's name changes\n\
++ \032 frequently (e.g., because it is a laptop and gets moved around a lot).\n\
++ \n\
++ \032 A more powerful way of changing archive names is provided by the\n\
++ \032 rootalias preference. The preference file may contain any number of\n\
++ \032 lines of the form:\n\
++ \032 rootalias = //hostnameA//path-to-replicaA -> //hostnameB/path-to-replicaB\n\
++ \n\
++ \032 When calculating the name of the archive files for a given pair of\n\
++ \032 roots, Unison replaces any root that matches the left-hand side of any\n\
++ \032 rootalias rule by the corresponding right-hand side.\n\
++ \n\
++ \032 So, if you need to relocate a root on one of the hosts, you can add a\n\
++ \032 rule of the form:\n\
++ \032 rootalias = //new-hostname//new-path -> //old-hostname/old-path\n\
++ \n\
++ \032 Note that root aliases are case-sensitive, even on case-insensitive\n\
++ \032 file systems.\n\
++ \n\
++ \032 Warning: The rootalias option is dangerous and should only be used if\n\
++ \032 you are sure you know what you're doing. In particular, it should only\n\
++ \032 be used if you are positive that either (1) both the original root and\n\
++ \032 the new alias refer to the same set of files, or (2) the files have\n\
++ \032 been relocated so that the original name is now invalid and will never\n\
++ \032 be used again. (If the original root and the alias refer to different\n\
++ \032 sets of files, Unison's update detector could get confused.) After\n\
++ \032 introducing a new rootalias, it is a good idea to run Unison a few\n\
++ \032 times interactively (with the batch flag off, etc.) and carefully check\n\
++ \032 that things look reasonable--in particular, that update detection is\n\
++ \032 working as expected.\n\
++ \n\
++ Preferences\n\
++ \n\
++ \032 Many details of Unison's behavior are configurable by user-settable\n\
++ \032 \"preferences.\"\n\
++ \n\
++ \032 Some preferences are boolean-valued; these are often called flags.\n\
++ \032 Others take numeric or string arguments, indicated in the preferences\n\
++ \032 list by n or xxx. Most of the string preferences can be given several\n\
++ \032 times; the arguments are accumulated into a list internally.\n\
++ \n\
++ \032 There are two ways to set the values of preferences: temporarily, by\n\
++ \032 providing command-line arguments to a particular run of Unison, or\n\
++ \032 permanently, by adding commands to a profile in the .unison directory\n\
++ \032 on the client host. The order of preferences (either on the command\n\
++ \032 line or in preference files) is not significant. On the command line,\n\
++ \032 preferences and other arguments (the profile name and roots) can be\n\
++ \032 intermixed in any order.\n\
++ \n\
++ \032 To set the value of a preference p from the command line, add an\n\
++ \032 argument -p (for a boolean flag) or -p n or -p xxx (for a numeric or\n\
++ \032 string preference) anywhere on the command line. To set a boolean flag\n\
++ \032 to false on the command line, use -p=false.\n\
++ \n\
++ \032 Here are all the preferences supported by Unison. This list can be\n\
++ \032 obtained by typing unison -help.\n\
++ \n\
++ Usage: unison [options]\n\
++ \032 or unison root1 root2 [options]\n\
++ \032 or unison profilename [options]\n\
++ \n\
++ Basic options:\n\
++ \032-auto automatically accept default (nonconflicting) actions\n\
++ \032-batch batch mode: ask no questions at all\n\
++ \032-doc xxx show documentation ('-doc topics' lists topics)\n\
++ \032-fat use appropriate options for FAT filesystems\n\
++ \032-group synchronize group attributes\n\
++ \032-ignore xxx add a pattern to the ignore list\n\
++ \032-ignorenot xxx add a pattern to the ignorenot list\n\
++ \032-nocreation xxx prevent file creations on one replica\n\
++ \032-nodeletion xxx prevent file deletions on one replica\n\
++ \032-noupdate xxx prevent file updates and deletions on one replica\n\
++ \032-owner synchronize owner\n\
++ \032-path xxx path to synchronize\n\
++ \032-perms n part of the permissions which is synchronized\n\
++ \032-root xxx root of a replica (should be used exactly twice)\n\
++ \032-silent print nothing except error messages\n\
++ \032-terse suppress status messages\n\
++ \032-testserver exit immediately after the connection to the server\n\
++ \032-times synchronize modification times\n\
++ \032-version print version and exit\n\
++ \n\
++ Advanced options:\n\
++ \032-addprefsto xxx file to add new prefs to\n\
++ \032-addversionno add version number to name of unison on server\n\
++ \032-backup xxx add a pattern to the backup list\n\
++ \032-backupcurr xxx add a pattern to the backupcurr list\n\
++ \032-backupcurrnot xxx add a pattern to the backupcurrnot list\n\
++ \032-backupdir xxx directory for storing centralized backups\n\
++ \032-backuploc xxx where backups are stored ('local' or 'central')\n\
++ \032-backupnot xxx add a pattern to the backupnot list\n\
++ \032-backupprefix xxx prefix for the names of backup files\n\
++ \032-backups keep backup copies of all files (see also 'backup')\n\
++ \032-backupsuffix xxx a suffix to be added to names of backup files\n\
++ \032-confirmbigdel ask about whole-replica (or path) deletes (default true)\n\
++ \032-confirmmerge ask for confirmation before commiting results of a merge\n\
++ \032-contactquietly suppress the 'contacting server' message during startup\n\
++ \032-copymax n maximum number of simultaneous copyprog transfers\n\
++ \032-copyprog xxx external program for copying large files\n\
++ \032-copyprogrest xxx variant of copyprog for resuming partial transfers\n\
++ \032-copyquoterem xxx add quotes to remote file name for copyprog (true/false/defa\n\
++ ult)\n\
++ \032-copythreshold n use copyprog on files bigger than this (if >=0, in Kb)\n\
++ \032-debug xxx debug module xxx ('all' -> everything, 'verbose' -> more)\n\
++ \032-diff xxx set command for showing differences between files\n\
++ \032-dontchmod when set, never use the chmod system call\n\
++ \032-dumbtty do not change terminal settings in text UI\n\
++ \032-fastcheck xxx do fast update detection (true/false/default)\n\
++ \032-follow xxx add a pattern to the follow list\n\
++ \032-force xxx force changes from this replica to the other\n\
++ \032-forcepartial xxx add a pattern to the forcepartial list\n\
++ \032-halfduplex force half-duplex communication with the server\n\
++ \032-height n height (in lines) of main window in graphical interface\n\
++ \032-host xxx bind the socket to this host name in server socket mode\n\
++ \032-ignorearchives ignore existing archive files\n\
++ \032-ignorecase xxx identify upper/lowercase filenames (true/false/default)\n\
++ \032-ignoreinodenumbers ignore inode number changes when detecting updates\n\
++ \032-ignorelocks ignore locks left over from previous run (dangerous!)\n\
++ \032-immutable xxx add a pattern to the immutable list\n\
++ \032-immutablenot xxx add a pattern to the immutablenot list\n\
++ \032-key xxx define a keyboard shortcut for this profile (in some UIs)\n\
++ \032-killserver kill server when done (even when using sockets)\n\
++ \032-label xxx provide a descriptive string label for this profile\n\
++ \032-links xxx allow the synchronization of symbolic links (true/false/defa\n\
++ ult)\n\
++ \032-log record actions in logfile (default true)\n\
++ \032-logfile xxx logfile name\n\
++ \032-maxbackups n number of backed up versions of a file\n\
++ \032-maxerrors n maximum number of errors before a directory transfer is abor\n\
++ ted\n\
++ \032-maxthreads n maximum number of simultaneous file transfers\n\
++ \032-merge xxx add a pattern to the merge list\n\
++ \032-mountpoint xxx abort if this path does not exist\n\
++ \032-nocreationpartial xxx add a pattern to the nocreationpartial list\n\
++ \032-nodeletionpartial xxx add a pattern to the nodeletionpartial list\n\
++ \032-noupdatepartial xxx add a pattern to the noupdatepartial list\n\
++ \032-numericids don't map uid/gid values by user/group names\n\
++ \032-prefer xxx choose this replica's version for conflicting changes\n\
++ \032-preferpartial xxx add a pattern to the preferpartial list\n\
++ \032-repeat xxx synchronize repeatedly (text interface only)\n\
++ \032-retry n re-try failed synchronizations N times (text ui only)\n\
++ \032-rootalias xxx register alias for canonical root names\n\
++ \032-rsrc xxx synchronize resource forks (true/false/default)\n\
++ \032-rsync activate the rsync transfer mode (default true)\n\
++ \032-selftest run internal tests and exit\n\
++ \032-servercmd xxx name of unison executable on remote server\n\
++ \032-showarchive show 'true names' (for rootalias) of roots and archive\n\
++ \032-socket xxx act as a server on a socket\n\
++ \032-sortbysize list changed files by size, not name\n\
++ \032-sortfirst xxx add a pattern to the sortfirst list\n\
++ \032-sortlast xxx add a pattern to the sortlast list\n\
++ \032-sortnewfirst list new before changed files\n\
++ \032-sshargs xxx other arguments (if any) for remote shell command\n\
++ \032-sshcmd xxx path to the ssh executable\n\
++ \032-stream use a streaming protocol for transferring file contents (def\n\
++ ault true)\n\
++ \032-ui xxx select UI ('text' or 'graphic'); command-line only\n\
++ \032-unicode xxx assume Unicode encoding in case insensitive mode\n\
++ \032-xferbycopying optimize transfers using local copies (default true)\n\
++ \n\
++ \n\
++ \032 Here, in more detail, is what they do. Many are discussed in greater\n\
++ \032 detail in other sections of the manual.\n\
++ \n\
++ \032 addprefsto xxx\n\
++ \032 By default, new preferences added by Unison (e.g., new ignore\n\
++ \032 clauses) will be appended to whatever preference file Unison was\n\
++ \032 told to load at the beginning of the run. Setting the preference\n\
++ \032 addprefsto filename makes Unison add new preferences to the file\n\
++ \032 named filename instead.\n\
++ \n\
++ \032 addversionno\n\
++ \032 When this flag is set to true, Unison will use\n\
++ \032 unison-currentversionnumber instead of just unison as the remote\n\
++ \032 server command. This allows multiple binaries for different\n\
++ \032 versions of unison to coexist conveniently on the same server:\n\
++ \032 whichever version is run on the client, the same version will be\n\
++ \032 selected on the server.\n\
++ \n\
++ \032 auto\n\
++ \032 When set to true, this flag causes the user interface to skip\n\
++ \032 asking for confirmations on non-conflicting changes. (More\n\
++ \032 precisely, when the user interface is done setting the\n\
++ \032 propagation direction for one entry and is about to move to the\n\
++ \032 next, it will skip over all non-conflicting entries and go\n\
++ \032 directly to the next conflict.)\n\
++ \n\
++ \032 backup xxx\n\
++ \032 Including the preference -backup pathspec causes Unison to keep\n\
++ \032 backup files for each path that matches pathspec. These backup\n\
++ \032 files are kept in the directory specified by the backuplocation\n\
++ \032 preference. The backups are named according to the backupprefix\n\
++ \032 and backupsuffix preferences. The number of versions that are\n\
++ \032 kept is determined by the maxbackups preference.\n\
++ \n\
++ \032 The syntax of pathspec is described in the section \"Path\n\
++ \032 Specification\" .\n\
++ \n\
++ \032 backupcurr xxx\n\
++ \032 Including the preference -backupcurr pathspec causes Unison to\n\
++ \032 keep a backup of the current version of every file matching\n\
++ \032 pathspec. This file will be saved as a backup with version\n\
++ \032 number 000. Such backups can be used as inputs to external\n\
++ \032 merging programs, for instance. See the documentatation for the\n\
++ \032 merge preference. For more details, see the section \"Merging\n\
++ \032 Conflicting Versions\" .\n\
++ \n\
++ \032 The syntax of pathspec is described in the section \"Path\n\
++ \032 Specification\" .\n\
++ \n\
++ \032 backupcurrnot xxx\n\
++ \032 Exceptions to backupcurr, like the ignorenot preference.\n\
++ \n\
++ \032 backupdir xxx\n\
++ \032 If this preference is set, Unison will use it as the name of the\n\
++ \032 directory used to store backup files specified by the backup\n\
++ \032 preference, when backuplocation is set to central. It is checked\n\
++ \032 after the UNISONBACKUPDIR environment variable.\n\
++ \n\
++ \032 backuploc xxx\n\
++ \032 This preference determines whether backups should be kept\n\
++ \032 locally, near the original files, or in a central directory\n\
++ \032 specified by the backupdir preference. If set to local, backups\n\
++ \032 will be kept in the same directory as the original files, and if\n\
++ \032 set to central, backupdir will be used instead.\n\
++ \n\
++ \032 backupnot xxx\n\
++ \032 The values of this preference specify paths or individual files\n\
++ \032 or regular expressions that should not be backed up, even if the\n\
++ \032 backup preference selects them--i.e., it selectively overrides\n\
++ \032 backup. The same caveats apply here as with ignore and\n\
++ \032 ignorenot.\n\
++ \n\
++ \032 backupprefix xxx\n\
++ \032 When a backup for a file NAME is created, it is stored in a\n\
++ \032 directory specified by backuplocation, in a file called\n\
++ \032 backupprefixNAMEbackupsuffix. backupprefix can include a\n\
++ \032 directory name (causing Unison to keep all backup files for a\n\
++ \032 given directory in a subdirectory with this name), and both\n\
++ \032 backupprefix and backupsuffix can contain the string$VERSION,\n\
++ \032 which will be replaced by the age of the backup (1 for the most\n\
++ \032 recent, 2 for the second most recent, and so on...). This\n\
++ \032 keyword is ignored if it appears in a directory name in the\n\
++ \032 prefix; if it does not appear anywhere in the prefix or the\n\
++ \032 suffix, it will be automatically placed at the beginning of the\n\
++ \032 suffix.\n\
++ \n\
++ \032 One thing to be careful of: If the backuploc preference is set\n\
++ \032 to local, Unison will automatically ignore all files whose\n\
++ \032 prefix and suffix match backupprefix and backupsuffix. So be\n\
++ \032 careful to choose values for these preferences that are\n\
++ \032 sufficiently different from the names of your real files.\n\
++ \n\
++ \032 backups\n\
++ \032 Setting this flag to true is equivalent to setting\n\
++ \032 backuplocation to local and backup to Name *.\n\
++ \n\
++ \032 backupsuffix xxx\n\
++ \032 See backupprefix for full documentation.\n\
++ \n\
++ \032 batch\n\
++ \032 When this is set to true, the user interface will ask no\n\
++ \032 questions at all. Non-conflicting changes will be propagated;\n\
++ \032 conflicts will be skipped.\n\
++ \n\
++ \032 confirmbigdel\n\
++ \032 When this is set to true, Unison will request an extra\n\
++ \032 confirmation if it appears that the entire replica has been\n\
++ \032 deleted, before propagating the change. If the batch flag is\n\
++ \032 also set, synchronization will be aborted. When the path\n\
++ \032 preference is used, the same confirmation will be requested for\n\
++ \032 top-level paths. (At the moment, this flag only affects the text\n\
++ \032 user interface.) See also the mountpoint preference.\n\
++ \n\
++ \032 confirmmerge\n\
++ \032 Setting this preference causes both the text and graphical\n\
++ \032 interfaces to ask the user if the results of a merge command may\n\
++ \032 be commited to the replica or not. Since the merge command works\n\
++ \032 on temporary files, the user can then cancel all the effects of\n\
++ \032 applying the merge if it turns out that the result is not\n\
++ \032 satisfactory. In batch-mode, this preference has no effect.\n\
++ \032 Default is false.\n\
++ \n\
++ \032 contactquietly\n\
++ \032 If this flag is set, Unison will skip displaying the `Contacting\n\
++ \032 server' message (which some users find annoying) during startup.\n\
++ \n\
++ \032 copymax n\n\
++ \032 A number indicating how many instances of the external copying\n\
++ \032 utility Unison is allowed to run simultaneously (default to 1).\n\
++ \n\
++ \032 copyprog xxx\n\
++ \032 A string giving the name of an external program that can be used\n\
++ \032 to copy large files efficiently (plus command-line switches\n\
++ \032 telling it to copy files in-place). The default setting invokes\n\
++ \032 rsync with appropriate options--most users should not need to\n\
++ \032 change it.\n\
++ \n\
++ \032 copyprogrest xxx\n\
++ \032 A variant of copyprog that names an external program that should\n\
++ \032 be used to continue the transfer of a large file that has\n\
++ \032 already been partially transferred. Typically, copyprogrest will\n\
++ \032 just be copyprog with one extra option (e.g., --partial, for\n\
++ \032 rsync). The default setting invokes rsync with appropriate\n\
++ \032 options--most users should not need to change it.\n\
++ \n\
++ \032 copyquoterem xxx\n\
++ \032 When set to true, this flag causes Unison to add an extra layer\n\
++ \032 of quotes to the remote path passed to the external copy\n\
++ \032 program. This is needed by rsync, for example, which internally\n\
++ \032 uses an ssh connection requiring an extra level of quoting for\n\
++ \032 paths containing spaces. When this flag is set to default, extra\n\
++ \032 quotes are added if the value of copyprog contains the string\n\
++ \032 rsync.\n\
++ \n\
++ \032 copythreshold n\n\
++ \032 A number indicating above what filesize (in kilobytes) Unison\n\
++ \032 should use the external copying utility specified by copyprog.\n\
++ \032 Specifying 0 will cause all copies to use the external program;\n\
++ \032 a negative number will prevent any files from using it. The\n\
++ \032 default is -1. See the section \"Making Unison Faster on Large\n\
++ \032 Files\" for more information.\n\
++ \n\
++ \032 debug xxx\n\
++ \032 This preference is used to make Unison print various sorts of\n\
++ \032 information about what it is doing internally on the standard\n\
++ \032 error stream. It can be used many times, each time with the name\n\
++ \032 of a module for which debugging information should be printed.\n\
++ \032 Possible arguments for debug can be found by looking for calls\n\
++ \032 to Util.debug in the sources (using, e.g., grep). Setting -debug\n\
++ \032 all causes information from all modules to be printed (this mode\n\
++ \032 of usage is the first one to try, if you are trying to\n\
++ \032 understand something that Unison seems to be doing wrong);\n\
++ \032 -debug verbose turns on some additional debugging output from\n\
++ \032 some modules (e.g., it will show exactly what bytes are being\n\
++ \032 sent across the network).\n\
++ \n\
++ \032 diff xxx\n\
++ \032 This preference can be used to control the name and command-line\n\
++ \032 arguments of the system utility used to generate displays of\n\
++ \032 file differences. The default is `diff -u CURRENT2 CURRENT1'. If\n\
++ \032 the value of this preference contains the substrings CURRENT1\n\
++ \032 and CURRENT2, these will be replaced by the names of the files\n\
++ \032 to be diffed. If not, the two filenames will be appended to the\n\
++ \032 command. In both cases, the filenames are suitably quoted.\n\
++ \n\
++ \032 doc xxx\n\
++ \032 The command-line argument -doc secname causes unison to display\n\
++ \032 section secname of the manual on the standard output and then\n\
++ \032 exit. Use -doc all to display the whole manual, which includes\n\
++ \032 exactly the same information as the printed and HTML manuals,\n\
++ \032 modulo formatting. Use -doc topics to obtain a list of the names\n\
++ \032 of the various sections that can be printed.\n\
++ \n\
++ \032 dontchmod\n\
++ \032 By default, Unison uses the 'chmod' system call to set the\n\
++ \032 permission bits of files after it has copied them. But in some\n\
++ \032 circumstances (and under some operating systems), the chmod call\n\
++ \032 always fails. Setting this preference completely prevents Unison\n\
++ \032 from ever calling chmod.\n\
++ \n\
++ \032 dumbtty\n\
++ \032 When set to true, this flag makes the text mode user interface\n\
++ \032 avoid trying to change any of the terminal settings. (Normally,\n\
++ \032 Unison puts the terminal in `raw mode', so that it can do things\n\
++ \032 like overwriting the current line.) This is useful, for example,\n\
++ \032 when Unison runs in a shell inside of Emacs.\n\
++ \n\
++ \032 When dumbtty is set, commands to the user interface need to be\n\
++ \032 followed by a carriage return before Unison will execute them.\n\
++ \032 (When it is off, Unison recognizes keystrokes as soon as they\n\
++ \032 are typed.)\n\
++ \n\
++ \032 This preference has no effect on the graphical user interface.\n\
++ \n\
++ \032 dumparchives\n\
++ \032 When this preference is set, Unison will create a file\n\
++ \032 unison.dump on each host, containing a text summary of the\n\
++ \032 archive, immediately after loading it.\n\
++ \n\
++ \032 fastcheck xxx\n\
++ \032 When this preference is set to true, Unison will use the\n\
++ \032 modification time and length of a file as a `pseudo inode\n\
++ \032 number' when scanning replicas for updates, instead of reading\n\
++ \032 the full contents of every file. Under Windows, this may cause\n\
++ \032 Unison to miss propagating an update if the modification time\n\
++ \032 and length of the file are both unchanged by the update.\n\
++ \032 However, Unison will never overwrite such an update with a\n\
++ \032 change from the other replica, since it always does a safe check\n\
++ \032 for updates just before propagating a change. Thus, it is\n\
++ \032 reasonable to use this switch under Windows most of the time and\n\
++ \032 occasionally run Unison once with fastcheck set to false, if you\n\
++ \032 are worried that Unison may have overlooked an update. For\n\
++ \032 backward compatibility, yes, no, and default can be used in\n\
++ \032 place of true, false, and auto. See the section \"Fast Checking\"\n\
++ \032 for more information.\n\
++ \n\
++ \032 fat\n\
++ \032 When this is set to true, Unison will use appropriate options to\n\
++ \032 synchronize efficiently and without error a replica located on a\n\
++ \032 FAT filesystem on a non-Windows machine: do not synchronize\n\
++ \032 permissions (perms = 0); never use chmod ( t dontchmod = true);\n\
++ \032 treat filenames as case insensitive (ignorecase = true); do not\n\
++ \032 attempt to synchronize symbolic links (links = false); ignore\n\
++ \032 inode number changes when detecting updates (ignoreinodenumbers\n\
++ \032 = true). Any of these change can be overridden by explicitely\n\
++ \032 setting the corresponding preference in the profile.\n\
++ \n\
++ \032 follow xxx\n\
++ \032 Including the preference -follow pathspec causes Unison to treat\n\
++ \032 symbolic links matching pathspec as `invisible' and behave as if\n\
++ \032 the object pointed to by the link had appeared literally at this\n\
++ \032 position in the replica. See the section \"Symbolic Links\" for\n\
++ \032 more details. The syntax of pathspec is described in the section\n\
++ \032 \"Path Specification\" .\n\
++ \n\
++ \032 force xxx\n\
++ \032 Including the preference -force root causes Unison to resolve\n\
++ \032 all differences (even non-conflicting changes) in favor of root.\n\
++ \032 This effectively changes Unison from a synchronizer into a\n\
++ \032 mirroring utility.\n\
++ \n\
++ \032 You can also specify -force newer (or -force older) to force\n\
++ \032 Unison to choose the file with the later (earlier) modtime. In\n\
++ \032 this case, the -times preference must also be enabled.\n\
++ \n\
++ \032 This preference is overridden by the forcepartial preference.\n\
++ \n\
++ \032 This preference should be used only if you are sure you know\n\
++ \032 what you are doing!\n\
++ \n\
++ \032 forcepartial xxx\n\
++ \032 Including the preference forcepartial = PATHSPEC -> root causes\n\
++ \032 Unison to resolve all differences (even non-conflicting changes)\n\
++ \032 in favor of root for the files in PATHSPEC (see the section\n\
++ \032 \"Path Specification\" for more information). This effectively\n\
++ \032 changes Unison from a synchronizer into a mirroring utility.\n\
++ \n\
++ \032 You can also specify forcepartial PATHSPEC -> newer (or\n\
++ \032 forcepartial PATHSPEC older) to force Unison to choose the file\n\
++ \032 with the later (earlier) modtime. In this case, the -times\n\
++ \032 preference must also be enabled.\n\
++ \n\
++ \032 This preference should be used only if you are sure you know\n\
++ \032 what you are doing!\n\
++ \n\
++ \032 group\n\
++ \032 When this flag is set to true, the group attributes of the files\n\
++ \032 are synchronized. Whether the group names or the group\n\
++ \032 identifiers are synchronized depends on the preference numerids.\n\
++ \n\
++ \032 halfduplex\n\
++ \032 When this flag is set to true, Unison network communication is\n\
++ \032 forced to be half duplex (the client and the server never\n\
++ \032 simultaneously emit data). If you experience unstabilities with\n\
++ \032 your network link, this may help. The communication is always\n\
++ \032 half-duplex when synchronizing with a Windows machine due to a\n\
++ \032 limitation of Unison current implementation that could result in\n\
++ \032 a deadlock.\n\
++ \n\
++ \032 height n\n\
++ \032 Used to set the height (in lines) of the main window in the\n\
++ \032 graphical user interface.\n\
++ \n\
++ \032 ignore xxx\n\
++ \032 Including the preference -ignore pathspec causes Unison to\n\
++ \032 completely ignore paths that match pathspec (as well as their\n\
++ \032 children). This is useful for avoiding synchronizing temporary\n\
++ \032 files, object files, etc. The syntax of pathspec is described in\n\
++ \032 the section \"Path Specification\" , and further details on\n\
++ \032 ignoring paths is found in the section \"Ignoring Paths\" .\n\
++ \n\
++ \032 ignorearchives\n\
++ \032 When this preference is set, Unison will ignore any existing\n\
++ \032 archive files and behave as though it were being run for the\n\
++ \032 first time on these replicas. It is not a good idea to set this\n\
++ \032 option in a profile: it is intended for command-line use.\n\
++ \n\
++ \032 ignorecase xxx\n\
++ \032 When set to true, this flag causes Unison to treat filenames as\n\
++ \032 case insensitive--i.e., files in the two replicas whose names\n\
++ \032 differ in (upper- and lower-case) `spelling' are treated as the\n\
++ \032 same file. When the flag is set to false, Unison will treat all\n\
++ \032 filenames as case sensitive. Ordinarily, when the flag is set to\n\
++ \032 default, filenames are automatically taken to be\n\
++ \032 case-insensitive if either host is running Windows or OSX. In\n\
++ \032 rare circumstances it may be useful to set the flag manually.\n\
++ \n\
++ \032 ignoreinodenumbers\n\
++ \032 When set to true, this preference makes Unison not take\n\
++ \032 advantage of inode numbers during fast update detection. This\n\
++ \032 switch should be used with care, as it is less safe than the\n\
++ \032 standard update detection method, but it can be useful with\n\
++ \032 filesystems which do not support inode numbers.\n\
++ \n\
++ \032 ignorelocks\n\
++ \032 When this preference is set, Unison will ignore any lock files\n\
++ \032 that may have been left over from a previous run of Unison that\n\
++ \032 was interrupted while reading or writing archive files; by\n\
++ \032 default, when Unison sees these lock files it will stop and\n\
++ \032 request manual intervention. This option should be set only if\n\
++ \032 you are positive that no other instance of Unison might be\n\
++ \032 concurrently accessing the same archive files (e.g., because\n\
++ \032 there was only one instance of unison running and it has just\n\
++ \032 crashed or you have just killed it). It is probably not a good\n\
++ \032 idea to set this option in a profile: it is intended for\n\
++ \032 command-line use.\n\
++ \n\
++ \032 ignorenot xxx\n\
++ \032 This preference overrides the preference ignore. It gives a list\n\
++ \032 of patterns (in the same format as ignore) for paths that should\n\
++ \032 definitely not be ignored, whether or not they happen to match\n\
++ \032 one of the ignore patterns.\n\
++ \n\
++ \032 Note that the semantics of ignore and ignorenot is a little\n\
++ \032 counter-intuitive. When detecting updates, Unison examines paths\n\
++ \032 in depth-first order, starting from the roots of the replicas\n\
++ \032 and working downwards. Before examining each path, it checks\n\
++ \032 whether it matches ignore and does not match ignorenot; in this\n\
++ \032 case it skips this path and all its descendants. This means\n\
++ \032 that, if some parent of a given path matches an ignore pattern,\n\
++ \032 then it will be skipped even if the path itself matches an\n\
++ \032 ignorenot pattern. In particular, putting ignore = Path * in\n\
++ \032 your profile and then using ignorenot to select particular paths\n\
++ \032 to be synchronized will not work. Instead, you should use the\n\
++ \032 path preference to choose particular paths to synchronize.\n\
++ \n\
++ \032 immutable xxx\n\
++ \032 This preference specifies paths for directories whose immediate\n\
++ \032 children are all immutable files -- i.e., once a file has been\n\
++ \032 created, its contents never changes. When scanning for updates,\n\
++ \032 Unison does not check whether these files have been modified;\n\
++ \032 this can speed update detection significantly (in particular,\n\
++ \032 for mail directories).\n\
++ \n\
++ \032 immutablenot xxx\n\
++ \032 This preference overrides immutable.\n\
++ \n\
++ \032 key xxx\n\
++ \032 Used in a profile to define a numeric key (0-9) that can be used\n\
++ \032 in the graphical user interface to switch immediately to this\n\
++ \032 profile.\n\
++ \n\
++ \032 killserver\n\
++ \032 When set to true, this flag causes Unison to kill the remote\n\
++ \032 server process when the synchronization is finished. This\n\
++ \032 behavior is the default for ssh connections, so this preference\n\
++ \032 is not normally needed when running over ssh; it is provided so\n\
++ \032 that socket-mode servers can be killed off after a single run of\n\
++ \032 Unison, rather than waiting to accept future connections. (Some\n\
++ \032 users prefer to start a remote socket server for each run of\n\
++ \032 Unison, rather than leaving one running all the time.)\n\
++ \n\
++ \032 label xxx\n\
++ \032 Used in a profile to provide a descriptive string documenting\n\
++ \032 its settings. (This is useful for users that switch between\n\
++ \032 several profiles, especially using the `fast switch' feature of\n\
++ \032 the graphical user interface.)\n\
++ \n\
++ \032 links xxx\n\
++ \032 When set to true, this flag causes Unison to synchronize\n\
++ \032 symbolic links. When the flag is set to false, symbolic links\n\
++ \032 will result in an error during update detection. Ordinarily,\n\
++ \032 when the flag is set to default, symbolic links are synchronized\n\
++ \032 except when one of the hosts is running Windows. In rare\n\
++ \032 circumstances it may be useful to set the flag manually.\n\
++ \n\
++ \032 log\n\
++ \032 When this flag is set, Unison will log all changes to the\n\
++ \032 filesystems on a file.\n\
++ \n\
++ \032 logfile xxx\n\
++ \032 By default, logging messages will be appended to the file\n\
++ \032 unison.log in your HOME directory. Set this preference if you\n\
++ \032 prefer another file.\n\
++ \n\
++ \032 maxbackups n\n\
++ \032 This preference specifies the number of backup versions that\n\
++ \032 will be kept by unison, for each path that matches the predicate\n\
++ \032 backup. The default is 2.\n\
++ \n\
++ \032 maxerrors n\n\
++ \032 This preference controls after how many errors Unison aborts a\n\
++ \032 directory transfer. Setting it to a large number allows Unison\n\
++ \032 to transfer most of a directory even when some files fail to be\n\
++ \032 copied. The default is 1. If the preference is set too high,\n\
++ \032 Unison may take a long time to abort in case of repeated\n\
++ \032 failures (for instance, when the disk is full).\n\
++ \n\
++ \032 maxthreads n\n\
++ \032 This preference controls how much concurrency is allowed during\n\
++ \032 the transport phase. Normally, it should be set reasonably high\n\
++ \032 to maximize performance, but when Unison is used over a\n\
++ \032 low-bandwidth link it may be helpful to set it lower (e.g. to 1)\n\
++ \032 so that Unison doesn't soak up all the available bandwidth. The\n\
++ \032 default is the special value 0, which mean 20 threads when file\n\
++ \032 content streaming is desactivated and 1000 threads when it is\n\
++ \032 activated.\n\
++ \n\
++ \032 merge xxx\n\
++ \032 This preference can be used to run a merge program which will\n\
++ \032 create a new version for each of the files and the backup, with\n\
++ \032 the last backup and the both replicas. Setting the merge\n\
++ \032 preference for a path will also cause this path to be backed up,\n\
++ \032 just like t backup. The syntax of pathspec>cmd is described in\n\
++ \032 the section \"Path Specification\" , and further details on\n\
++ \032 Merging functions are present in the section \"Merging files\" .\n\
++ \n\
++ \032 mountpoint xxx\n\
++ \032 Including the preference -mountpoint PATH causes Unison to\n\
++ \032 double-check, at the end of update detection, that PATH exists\n\
++ \032 and abort if it does not. This is useful when Unison is used to\n\
++ \032 synchronize removable media. This preference can be given more\n\
++ \032 than once. See the section \"Mount Points\" .\n\
++ \n\
++ \032 nocreation xxx\n\
++ \032 Including the preference -nocreation root prevents Unison from\n\
++ \032 performing any file creation on root root.\n\
++ \n\
++ \032 This preference can be included twice, once for each root, if\n\
++ \032 you want to prevent any creation.\n\
++ \n\
++ \032 nocreationpartial xxx\n\
++ \032 Including the preference nocreationpartial = PATHSPEC -> root\n\
++ \032 prevents Unison from performing any file creation in PATHSPEC on\n\
++ \032 root root (see the section \"Path Specification\" for more\n\
++ \032 information). It is recommended to use BelowPath patterns when\n\
++ \032 selecting a directory and all its contents.\n\
++ \n\
++ \032 nodeletion xxx\n\
++ \032 Including the preference -nodeletion root prevents Unison from\n\
++ \032 performing any file deletion on root root.\n\
++ \n\
++ \032 This preference can be included twice, once for each root, if\n\
++ \032 you want to prevent any deletion.\n\
++ \n\
++ \032 nodeletionpartial xxx\n\
++ \032 Including the preference nodeletionpartial = PATHSPEC -> root\n\
++ \032 prevents Unison from performing any file deletion in PATHSPEC on\n\
++ \032 root root (see the section \"Path Specification\" for more\n\
++ \032 information). It is recommended to use BelowPath patterns when\n\
++ \032 selecting a directory and all its contents.\n\
++ \n\
++ \032 noupdate xxx\n\
++ \032 Including the preference -noupdate root prevents Unison from\n\
++ \032 performing any file update or deletion on root root.\n\
++ \n\
++ \032 This preference can be included twice, once for each root, if\n\
++ \032 you want to prevent any update.\n\
++ \n\
++ \032 noupdatepartial xxx\n\
++ \032 Including the preference noupdatepartial = PATHSPEC -> root\n\
++ \032 prevents Unison from performing any file update or deletion in\n\
++ \032 PATHSPEC on root root (see the section \"Path Specification\" for\n\
++ \032 more information). It is recommended to use BelowPath patterns\n\
++ \032 when selecting a directory and all its contents.\n\
++ \n\
++ \032 numericids\n\
++ \032 When this flag is set to true, groups and users are synchronized\n\
++ \032 numerically, rather than by name.\n\
++ \n\
++ \032 The special uid 0 and the special group 0 are never mapped via\n\
++ \032 user/group names even if this preference is not set.\n\
++ \n\
++ \032 owner\n\
++ \032 When this flag is set to true, the owner attributes of the files\n\
++ \032 are synchronized. Whether the owner names or the owner\n\
++ \032 identifiers are synchronizeddepends on the preference numerids.\n\
++ \n\
++ \032 path xxx\n\
++ \032 When no path preference is given, Unison will simply synchronize\n\
++ \032 the two entire replicas, beginning from the given pair of roots.\n\
++ \032 If one or more path preferences are given, then Unison will\n\
++ \032 synchronize only these paths and their children. (This is useful\n\
++ \032 for doing a fast sync of just one directory, for example.) Note\n\
++ \032 that path preferences are intepreted literally--they are not\n\
++ \032 regular expressions.\n\
++ \n\
++ \032 perms n\n\
++ \032 The integer value of this preference is a mask indicating which\n\
++ \032 permission bits should be synchronized. It is set by default to\n\
++ \032 0o1777: all bits but the set-uid and set-gid bits are\n\
++ \032 synchronised (synchronizing theses latter bits can be a security\n\
++ \032 hazard). If you want to synchronize all bits, you can set the\n\
++ \032 value of this preference to -1. If one of the replica is on a\n\
++ \032 FAT [Windows] filesystem, you should consider using the t fat\n\
++ \032 preference instead of this preference. If you need Unison not to\n\
++ \032 set permissions at all, set the value of this preference to 0\n\
++ \032 and set the preference t dontchmod to t true.\n\
++ \n\
++ \032 prefer xxx\n\
++ \032 Including the preference -prefer root causes Unison always to\n\
++ \032 resolve conflicts in favor of root, rather than asking for\n\
++ \032 guidance from the user. (The syntax of root is the same as for\n\
++ \032 the root preference, plus the special values newer and older.)\n\
++ \n\
++ \032 This preference is overridden by the preferpartial preference.\n\
++ \n\
++ \032 This preference should be used only if you are sure you know\n\
++ \032 what you are doing!\n\
++ \n\
++ \032 preferpartial xxx\n\
++ \032 Including the preference preferpartial = PATHSPEC -> root causes\n\
++ \032 Unison always to resolve conflicts in favor of root, rather than\n\
++ \032 asking for guidance from the user, for the files in PATHSPEC\n\
++ \032 (see the section \"Path Specification\" for more information).\n\
++ \032 (The syntax of root is the same as for the root preference, plus\n\
++ \032 the special values newer and older.)\n\
++ \n\
++ \032 This preference should be used only if you are sure you know\n\
++ \032 what you are doing!\n\
++ \n\
++ \032 repeat xxx\n\
++ \032 Setting this preference causes the text-mode interface to\n\
++ \032 synchronize repeatedly, rather than doing it just once and\n\
++ \032 stopping. If the argument is a number, Unison will pause for\n\
++ \032 that many seconds before beginning again.\n\
++ \n\
++ \032 retry n\n\
++ \032 Setting this preference causes the text-mode interface to try\n\
++ \032 again to synchronize updated paths where synchronization fails.\n\
++ \032 Each such path will be tried N times.\n\
++ \n\
++ \032 root xxx\n\
++ \032 Each use of this preference names the root of one of the\n\
++ \032 replicas for Unison to synchronize. Exactly two roots are\n\
++ \032 needed, so normal modes of usage are either to give two values\n\
++ \032 for root in the profile, or to give no values in the profile and\n\
++ \032 provide two on the command line. Details of the syntax of roots\n\
++ \032 can be found in the section \"Roots\" .\n\
++ \n\
++ \032 The two roots can be given in either order; Unison will sort\n\
++ \032 them into a canonical order before doing anything else. It also\n\
++ \032 tries to `canonize' the machine names and paths that appear in\n\
++ \032 the roots, so that, if Unison is invoked later with a slightly\n\
++ \032 different name for the same root, it will be able to locate the\n\
++ \032 correct archives.\n\
++ \n\
++ \032 rootalias xxx\n\
++ \032 When calculating the name of the archive files for a given pair\n\
++ \032 of roots, Unison replaces any roots matching the left-hand side\n\
++ \032 of any rootalias rule by the corresponding right-hand side.\n\
++ \n\
++ \032 rshargs xxx\n\
++ \032 The string value of this preference will be passed as additional\n\
++ \032 arguments (besides the host name and the name of the Unison\n\
++ \032 executable on the remote system) to the rsh command used to\n\
++ \032 invoke the remote server.\n\
++ \n\
++ \032 rshcmd xxx\n\
++ \032 This preference can be used to explicitly set the name of the\n\
++ \032 rsh executable (e.g., giving a full path name), if necessary.\n\
++ \n\
++ \032 rsrc xxx\n\
++ \032 When set to true, this flag causes Unison to synchronize\n\
++ \032 resource forks and HFS meta-data. On filesystems that do not\n\
++ \032 natively support resource forks, this data is stored in\n\
++ \032 Carbon-compatible ._ AppleDouble files. When the flag is set to\n\
++ \032 false, Unison will not synchronize these data. Ordinarily, the\n\
++ \032 flag is set to default, and these data are automatically\n\
++ \032 synchronized if either host is running OSX. In rare\n\
++ \032 circumstances it is useful to set the flag manually.\n\
++ \n\
++ \032 rsync\n\
++ \032 Unison uses the 'rsync algorithm' for 'diffs-only' transfer of\n\
++ \032 updates to large files. Setting this flag to false makes Unison\n\
++ \032 use whole-file transfers instead. Under normal circumstances,\n\
++ \032 there is no reason to do this, but if you are having trouble\n\
++ \032 with repeated 'rsync failure' errors, setting it to false should\n\
++ \032 permit you to synchronize the offending files.\n\
++ \n\
++ \032 selftest\n\
++ \032 Run internal tests and exit. This option is mostly for\n\
++ \032 developers and must be used carefully: in particular, it will\n\
++ \032 delete the contents of both roots, so that it can install its\n\
++ \032 own files for testing. This flag only makes sense on the command\n\
++ \032 line. When it is provided, no preference file is read: all\n\
++ \032 preferences must be specified on thecommand line. Also, since\n\
++ \032 the self-test procedure involves overwriting the roots and\n\
++ \032 backup directory, the names of the roots and of the backupdir\n\
++ \032 preference must include the string \"test\" or else the tests will\n\
++ \032 be aborted. (If these are not given on the command line, dummy\n\
++ \032 subdirectories in the current directory will be created\n\
++ \032 automatically.)\n\
++ \n\
++ \032 servercmd xxx\n\
++ \032 This preference can be used to explicitly set the name of the\n\
++ \032 Unison executable on the remote server (e.g., giving a full path\n\
++ \032 name), if necessary.\n\
++ \n\
++ \032 showarchive\n\
++ \032 When this preference is set, Unison will print out the 'true\n\
++ \032 names'of the roots, in the same form as is expected by the\n\
++ \032 rootaliaspreference.\n\
++ \n\
++ \032 silent\n\
++ \032 When this preference is set to true, the textual user interface\n\
++ \032 will print nothing at all, except in the case of errors. Setting\n\
++ \032 silent to true automatically sets the batch preference to true.\n\
++ \n\
++ \032 sortbysize\n\
++ \032 When this flag is set, the user interface will list changed\n\
++ \032 files by size (smallest first) rather than by name. This is\n\
++ \032 useful, for example, for synchronizing over slow links, since it\n\
++ \032 puts very large files at the end of the list where they will not\n\
++ \032 prevent smaller files from being transferred quickly.\n\
++ \n\
++ \032 This preference (as well as the other sorting flags, but not the\n\
++ \032 sorting preferences that require patterns as arguments) can be\n\
++ \032 set interactively and temporarily using the 'Sort' menu in the\n\
++ \032 graphical user interface.\n\
++ \n\
++ \032 sortfirst xxx\n\
++ \032 Each argument to sortfirst is a pattern pathspec, which\n\
++ \032 describes a set of paths. Files matching any of these patterns\n\
++ \032 will be listed first in the user interface. The syntax of\n\
++ \032 pathspec is described in the section \"Path Specification\" .\n\
++ \n\
++ \032 sortlast xxx\n\
++ \032 Similar to sortfirst, except that files matching one of these\n\
++ \032 patterns will be listed at the very end.\n\
++ \n\
++ \032 sortnewfirst\n\
++ \032 When this flag is set, the user interface will list newly\n\
++ \032 created files before all others. This is useful, for example,\n\
++ \032 for checking that newly created files are not `junk', i.e., ones\n\
++ \032 that should be ignored or deleted rather than synchronized.\n\
++ \n\
++ \032 sshargs xxx\n\
++ \032 The string value of this preference will be passed as additional\n\
++ \032 arguments (besides the host name and the name of the Unison\n\
++ \032 executable on the remote system) to the ssh command used to\n\
++ \032 invoke the remote server.\n\
++ \n\
++ \032 sshcmd xxx\n\
++ \032 This preference can be used to explicitly set the name of the\n\
++ \032 ssh executable (e.g., giving a full path name), if necessary.\n\
++ \n\
++ \032 sshversion xxx\n\
++ \032 This preference can be used to control which version of ssh\n\
++ \032 should be used to connect to the server. Legal values are 1 and\n\
++ \032 2, which will cause unison to try to use ssh1 orssh2 instead of\n\
++ \032 just ssh to invoke ssh. The default value is empty, which will\n\
++ \032 make unison use whatever version of ssh is installed as the\n\
++ \032 default `ssh' command.\n\
++ \n\
++ \032 stream\n\
++ \032 When this preference is set, Unison will use an experimental\n\
++ \032 streaming protocol for transferring file contents more\n\
++ \032 efficiently. The default value is true.\n\
++ \n\
++ \032 terse\n\
++ \032 When this preference is set to true, the user interface will not\n\
++ \032 print status messages.\n\
++ \n\
++ \032 testserver\n\
++ \032 Setting this flag on the command line causes Unison to attempt\n\
++ \032 to connect to the remote server and, if successful, print a\n\
++ \032 message and immediately exit. Useful for debugging installation\n\
++ \032 problems. Should not be set in preference files.\n\
++ \n\
++ \032 times\n\
++ \032 When this flag is set to true, file modification times (but not\n\
++ \032 directory modtimes) are propagated.\n\
++ \n\
++ \032 ui xxx\n\
++ \032 This preference selects either the graphical or the textual user\n\
++ \032 interface. Legal values are graphic or text.\n\
++ \n\
++ \032 Because this option is processed specially during Unison's\n\
++ \032 start-up sequence, it can only be used on the command line. In\n\
++ \032 preference files it has no effect.\n\
++ \n\
++ \032 If the Unison executable was compiled with only a textual\n\
++ \032 interface, this option has no effect. (The pre-compiled binaries\n\
++ \032 are all compiled with both interfaces available.)\n\
++ \n\
++ \032 unicode xxx\n\
++ \032 When set to true, this flag causes Unison to perform case\n\
++ \032 insensitive file comparisons assuming Unicode encoding. This is\n\
++ \032 the default. When the flag is set to false, a Latin 1 encoding\n\
++ \032 is assumed. When Unison runs in case sensitive mode, this flag\n\
++ \032 only makes a difference if one host is running Windows or Mac OS\n\
++ \032 X. Under Windows, the flag selects between using the Unicode or\n\
++ \032 8bit Windows API for accessing the filesystem. Under Mac OS X,\n\
++ \032 it selects whether comparing the filenames up to decomposition,\n\
++ \032 or byte-for-byte.\n\
++ \n\
++ \032 version\n\
++ \032 Print the current version number and exit. (This option only\n\
++ \032 makes sense on the command line.)\n\
++ \n\
++ \032 xferbycopying\n\
++ \032 When this preference is set, Unison will try to avoid\n\
++ \032 transferring file contents across the network by recognizing\n\
++ \032 when a file with the required contents already exists in the\n\
++ \032 target replica. This usually allows file moves to be propagated\n\
++ \032 very quickly. The default value istrue.\n\
++ \n\
++ Profiles\n\
++ \n\
++ \032 A profile is a text file that specifies permanent settings for roots,\n\
++ \032 paths, ignore patterns, and other preferences, so that they do not need\n\
++ \032 to be typed at the command line every time Unison is run. Profiles\n\
++ \032 should reside in the .unison directory on the client machine. If Unison\n\
++ \032 is started with just one argument name on the command line, it looks\n\
++ \032 for a profile called name.prf in the .unison directory. If it is\n\
++ \032 started with no arguments, it scans the .unison directory for files\n\
++ \032 whose names end in .prf and offers a menu (provided that the Unison\n\
++ \032 executable is compiled with the graphical user interface). If a file\n\
++ \032 named default.prf is found, its settings will be offered as the default\n\
++ \032 choices.\n\
++ \n\
++ \032 To set the value of a preference p permanently, add to the appropriate\n\
++ \032 profile a line of the form\n\
++ \032 p = true\n\
++ \n\
++ \032 for a boolean flag or\n\
++ \032 p = <value>\n\
++ \n\
++ \032 for a preference of any other type.\n\
++ \n\
++ \032 Whitespaces around p and xxx are ignored. A profile may also include\n\
++ \032 blank lines and lines beginning with #; both are ignored.\n\
++ \n\
++ \032 When Unison starts, it first reads the profile and then the command\n\
++ \032 line, so command-line options will override settings from the profile.\n\
++ \n\
++ \032 Profiles may also include lines of the form include name, which will\n\
++ \032 cause the file name (or name.prf, if name does not exist in the .unison\n\
++ \032 directory) to be read at the point, and included as if its contents,\n\
++ \032 instead of the include line, was part of the profile. Include lines\n\
++ \032 allows settings common to several profiles to be stored in one place.\n\
++ \n\
++ \032 A profile may include a preference `label = desc' to provide a\n\
++ \032 description of the options selected in this profile. The string desc is\n\
++ \032 listed along with the profile name in the profile selection dialog, and\n\
++ \032 displayed in the top-right corner of the main Unison window in the\n\
++ \032 graphical user interface.\n\
++ \n\
++ \032 The graphical user-interface also supports one-key shortcuts for\n\
++ \032 commonly used profiles. If a profile contains a preference of the form\n\
++ \032 `key = n', where n is a single digit, then pressing this digit key will\n\
++ \032 cause Unison to immediately switch to this profile and begin\n\
++ \032 synchronization again from scratch. In this case, all actions that have\n\
++ \032 been selected for a set of changes currently being displayed will be\n\
++ \032 discarded.\n\
++ \n\
++ Sample Profiles\n\
++ \n\
++ A Minimal Profile\n\
++ \n\
++ \032 Here is a very minimal profile file, such as might be found in\n\
++ \032 .unison/default.prf:\n\
++ \032 # Roots of the synchronization\n\
++ \032 root = /home/bcpierce\n\
++ \032 root = ssh://saul//home/bcpierce\n\
++ \n\
++ \032 # Paths to synchronize\n\
++ \032 path = current\n\
++ \032 path = common\n\
++ \032 path = .netscape/bookmarks.html\n\
++ \n\
++ A Basic Profile\n\
++ \n\
++ \032 Here is a more sophisticated profile, illustrating some other useful\n\
++ \032 features.\n\
++ \032 # Roots of the synchronization\n\
++ \032 root = /home/bcpierce\n\
++ \032 root = ssh://saul//home/bcpierce\n\
++ \n\
++ \032 # Paths to synchronize\n\
++ \032 path = current\n\
++ \032 path = common\n\
++ \032 path = .netscape/bookmarks.html\n\
++ \n\
++ \032 # Some regexps specifying names and paths to ignore\n\
++ \032 ignore = Name temp.*\n\
++ \032 ignore = Name *~\n\
++ \032 ignore = Name .*~\n\
++ \032 ignore = Path */pilot/backup/Archive_*\n\
++ \032 ignore = Name *.o\n\
++ \032 ignore = Name *.tmp\n\
++ \n\
++ \032 # Window height\n\
++ \032 height = 37\n\
++ \n\
++ \032 # Keep a backup copy of every file in a central location\n\
++ \032 backuplocation = central\n\
++ \032 backupdir = /home/bcpierce/backups\n\
++ \032 backup = Name *\n\
++ \032 backupprefix = $VERSION.\n\
++ \032 backupsuffix =\n\
++ \n\
++ \032 # Use this command for displaying diffs\n\
++ \032 diff = diff -y -W 79 --suppress-common-lines\n\
++ \n\
++ \032 # Log actions to the terminal\n\
++ \032 log = true\n\
++ \n\
++ A Power-User Profile\n\
++ \n\
++ \032 When Unison is used with large replicas, it is often convenient to be\n\
++ \032 able to synchronize just a part of the replicas on a given run (this\n\
++ \032 saves the time of detecting updates in the other parts). This can be\n\
++ \032 accomplished by splitting up the profile into several parts -- a common\n\
++ \032 part containing most of the preference settings, plus one \"top-level\"\n\
++ \032 file for each set of paths that need to be synchronized. (The include\n\
++ \032 mechanism can also be used to allow the same set of preference settings\n\
++ \032 to be used with different roots.)\n\
++ \n\
++ \032 The collection of profiles implementing this scheme might look as\n\
++ \032 follows. The file default.prf is empty except for an include directive:\n\
++ \032 # Include the contents of the file common\n\
++ \032 include common\n\
++ \n\
++ \032 Note that the name of the common file is common, not common.prf; this\n\
++ \032 prevents Unison from offering common as one of the list of profiles in\n\
++ \032 the opening dialog (in the graphical UI).\n\
++ \n\
++ \032 The file common contains the real preferences:\n\
++ \032 # Roots of the synchronization\n\
++ \032 root = /home/bcpierce\n\
++ \032 root = ssh://saul//home/bcpierce\n\
++ \n\
++ \032 # (... other preferences ...)\n\
++ \n\
++ \032 # If any new preferences are added by Unison (e.g. 'ignore'\n\
++ \032 # preferences added via the graphical UI), then store them in the\n\
++ \032 # file 'common' rathen than in the top-level preference file\n\
++ \032 addprefsto = common\n\
++ \n\
++ \032 # Names and paths to ignore:\n\
++ \032 ignore = Name temp.*\n\
++ \032 ignore = Name *~\n\
++ \032 ignore = Name .*~\n\
++ \032 ignore = Path */pilot/backup/Archive_*\n\
++ \032 ignore = Name *.o\n\
++ \032 ignore = Name *.tmp\n\
++ \n\
++ \032 Note that there are no path preferences in common. This means that,\n\
++ \032 when we invoke Unison with the default profile (e.g., by typing 'unison\n\
++ \032 default' or just 'unison' on the command line), the whole replicas will\n\
++ \032 be synchronized. (If we never want to synchronize the whole replicas,\n\
++ \032 then default.prf would instead include settings for all the paths that\n\
++ \032 are usually synchronized.)\n\
++ \n\
++ \032 To synchronize just part of the replicas, Unison is invoked with an\n\
++ \032 alternate preference file--e.g., doing 'unison workingset', where the\n\
++ \032 preference file workingset.prf contains\n\
++ \032 path = current/papers\n\
++ \032 path = Mail/inbox\n\
++ \032 path = Mail/drafts\n\
++ \032 include common\n\
++ \n\
++ \032 causes Unison to synchronize just the listed subdirectories.\n\
++ \n\
++ \032 The key preference can be used in combination with the graphical UI to\n\
++ \032 quickly switch between different sets of paths. For example, if the\n\
++ \032 file mail.prf contains\n\
++ \032 path = Mail\n\
++ \032 batch = true\n\
++ \032 key = 2\n\
++ \032 include common\n\
++ \n\
++ \032 then pressing 2 will cause Unison to look for updates in the Mail\n\
++ \032 subdirectory and (because the batch flag is set) immediately propagate\n\
++ \032 any that it finds.\n\
++ \n\
++ Keeping Backups\n\
++ \n\
++ \032 When Unison overwrites a file or directory by propagating a new version\n\
++ \032 from the other replica, it can keep the old version around as a backup.\n\
++ \032 There are several preferences that control precisely where these\n\
++ \032 backups are stored and how they are named.\n\
++ \n\
++ \032 To enable backups, you must give one or more backup preferences. Each\n\
++ \032 of these has the form\n\
++ \032 backup = <pathspec>\n\
++ \n\
++ \032 where <pathspec> has the same form as for the ignore preference. For\n\
++ \032 example,\n\
++ \032 backup = Name *\n\
++ \n\
++ \032 causes Unison to keep backups of all files and directories. The\n\
++ \032 backupnot preference can be used to give a few exceptions: it specifies\n\
++ \032 which files and directories should not be backed up, even if they match\n\
++ \032 the backup pathspec.\n\
++ \n\
++ \032 It is important to note that the pathspec is matched against the path\n\
++ \032 that is being updated by Unison, not its descendants. For example, if\n\
++ \032 you set backup = Name *.txt and then delete a whole directory named foo\n\
++ \032 containing some text files, these files will not be backed up because\n\
++ \032 Unison will just check that foo does not match *.txt. Similarly, if the\n\
++ \032 directory itself happened to be called foo.txt, then the whole\n\
++ \032 directory and all the files in it will be backed up, regardless of\n\
++ \032 their names.\n\
++ \n\
++ \032 Backup files can be stored either centrally or locally. This behavior\n\
++ \032 is controlled by the preference backuplocation, whose value must be\n\
++ \032 either central or local. (The default is central.)\n\
++ \n\
++ \032 When backups are stored locally, they are kept in the same directory as\n\
++ \032 the original.\n\
++ \n\
++ \032 When backups are stored centrally, the directory used to hold them is\n\
++ \032 controlled by the preference backupdir and the environment variable\n\
++ \032 UNISONBACKUPDIR. (The environment variable is checked first.) If\n\
++ \032 neither of these are set, then the directory .unison/backup in the\n\
++ \032 user's home directory is used.\n\
++ \n\
++ \032 The preference maxbackups controls how many previous versions of each\n\
++ \032 file are kept (including the current version).\n\
++ \n\
++ \032 By default, backup files are named .bak.VERSION.FILENAME, where\n\
++ \032 FILENAME is the original filename and VERSION is the backup number (1\n\
++ \032 for the most recent, 2 for the next most recent, etc.). This can be\n\
++ \032 changed by setting the preferences backupprefix and/or backupsuffix. If\n\
++ \032 desired, backupprefix may include a directory prefix; this can be used\n\
++ \032 with backuplocation = local to put all backup files for each directory\n\
++ \032 into a single subdirectory. For example, setting\n\
++ \032 backuplocation = local\n\
++ \032 backupprefix = .unison/$VERSION.\n\
++ \032 backupsuffix =\n\
++ \n\
++ \032 will put all backups in a local subdirectory named .unison. Also, note\n\
++ \032 that the string $VERSION in either backupprefix or backupsuffix (it\n\
++ \032 must appear in one or the other) is replaced by the version number.\n\
++ \032 This can be used, for example, to ensure that backup files retain the\n\
++ \032 same extension as the originals.\n\
++ \n\
++ \032 For backward compatibility, the backups preference is also supported.\n\
++ \032 It simply means backup = Name * and backuplocation = local.\n\
++ \n\
++ Merging Conflicting Versions\n\
++ \n\
++ \032 Unison can invoke external programs to merge conflicting versions of a\n\
++ \032 file. The preference merge controls this process.\n\
++ \n\
++ \032 The merge preference may be given once or several times in a preference\n\
++ \032 file (it can also be given on the command line, of course, but this\n\
++ \032 tends to be awkward because of the spaces and special characters\n\
++ \032 involved). Each instance of the preference looks like this:\n\
++ \032 merge = <PATHSPEC> -> <MERGECMD>\n\
++ \n\
++ \032 The <PATHSPEC> here has exactly the same format as for the ignore\n\
++ \032 preference (see the section \"Path specification\" ). For example, using\n\
++ \032 \"Name *.txt\" as the <PATHSPEC> tells Unison that this command should be\n\
++ \032 used whenever a file with extension .txt needs to be merged.\n\
++ \n\
++ \032 Many external merging programs require as inputs not just the two files\n\
++ \032 that need to be merged, but also a file containing the last\n\
++ \032 synchronized version. You can ask Unison to keep a copy of the last\n\
++ \032 synchronized version for some files using the backupcurrent preference.\n\
++ \032 This preference is used in exactly the same way as backup and its\n\
++ \032 meaning is similar, except that it causes backups to be kept of the\n\
++ \032 current contents of each file after it has been synchronized by Unison,\n\
++ \032 rather than the previous contents that Unison overwrote. These backups\n\
++ \032 are kept on both replicas in the same place as ordinary backup\n\
++ \032 files--i.e. according to the backuplocation and backupdir preferences.\n\
++ \032 They are named like the original files if backupslocation is set to\n\
++ \032 'central' and otherwise, Unison uses the backupprefix and backupsuffix\n\
++ \032 preferences and assumes a version number 000 for these backups.\n\
++ \n\
++ \032 The <MERGECMD> part of the preference specifies what external command\n\
++ \032 should be invoked to merge files at paths matching the <PATHSPEC>.\n\
++ \032 Within this string, several special substrings are recognized; these\n\
++ \032 will be substituted with appropriate values before invoking a sub-shell\n\
++ \032 to execute the command.\n\
++ \032 * CURRENT1 is replaced by the name of (a temporary copy of) the local\n\
++ \032 variant of the file.\n\
++ \032 * CURRENT2 is replaced by the name of a temporary file, into which\n\
++ \032 the contents of the remote variant of the file have been\n\
++ \032 transferred by Unison prior to performing the merge.\n\
++ \032 * CURRENTARCH is replaced by the name of the backed up copy of the\n\
++ \032 original version of the file (i.e., the file saved by Unison if the\n\
++ \032 current filename matches the path specifications for the\n\
++ \032 backupcurrent preference, as explained above), if one exists. If no\n\
++ \032 archive exists and CURRENTARCH appears in the merge command, then\n\
++ \032 an error is signalled.\n\
++ \032 * CURRENTARCHOPT is replaced by the name of the backed up copy of the\n\
++ \032 original version of the file (i.e., its state at the end of the\n\
++ \032 last successful run of Unison), if one exists, or the empty string\n\
++ \032 if no archive exists.\n\
++ \032 * NEW is replaced by the name of a temporary file that Unison expects\n\
++ \032 to be written by the merge program when it finishes, giving the\n\
++ \032 desired new contents of the file.\n\
++ \032 * PATH is replaced by the path (relative to the roots of the\n\
++ \032 replicas) of the file being merged.\n\
++ \032 * NEW1 and NEW2 are replaced by the names of temporary files that\n\
++ \032 Unison expects to be written by the merge program when it is only\n\
++ \032 able to partially merge the originals; in this case, NEW1 will be\n\
++ \032 written back to the local replica and NEW2 to the remote replica;\n\
++ \032 NEWARCH, if present, will be used as the \"last common state\" of the\n\
++ \032 replicas. (These three options are provided for later compatibility\n\
++ \032 with the Harmony data synchronizer.)\n\
++ \n\
++ \032 To accommodate the wide variety of programs that users might want to\n\
++ \032 use for merging, Unison checks for several possible situations when the\n\
++ \032 merge program exits:\n\
++ \032 * If the merge program exits with a non-zero status, then merge is\n\
++ \032 considered to have failed and the replicas are not changed.\n\
++ \032 * If the file NEW has been created, it is written back to both\n\
++ \032 replicas (and stored in the backup directory). Similarly, if just\n\
++ \032 the file NEW1 has been created, it is written back to both\n\
++ \032 replicas.\n\
++ \032 * If neither NEW nor NEW1 have been created, then Unison examines the\n\
++ \032 temporary files CURRENT1 and CURRENT2 that were given as inputs to\n\
++ \032 the merge program. If either has been changed (or both have been\n\
++ \032 changed in identical ways), then its new contents are written back\n\
++ \032 to both replicas. If either CURRENT1 or CURRENT2 has been deleted,\n\
++ \032 then the contents of the other are written back to both replicas.\n\
++ \032 * If the files NEW1, NEW2, and NEWARCH have all been created, they\n\
++ \032 are written back to the local replica, remote replica, and backup\n\
++ \032 directory, respectively. If the files NEW1, NEW2 have been created,\n\
++ \032 but NEWARCH has not, then these files are written back to the local\n\
++ \032 replica and remote replica, respectively. Also, if NEW1 and NEW2\n\
++ \032 have identical contents, then the same contents are stored as a\n\
++ \032 backup (if the backupcurrent preference is set for this path) to\n\
++ \032 reflect the fact that the path is currently in sync.\n\
++ \032 * If NEW1 and NEW2 (resp. CURRENT1 and CURRENT2) are created (resp.\n\
++ \032 overwritten) with different contents but the merge command did not\n\
++ \032 fail (i.e., it exited with status code 0), then we copy NEW1 (resp.\n\
++ \032 CURRENT1) to the other replica and to the archive.\n\
++ \032 This behavior is a design choice made to handle the case where a\n\
++ \032 merge command only synchronizes some specific contents between two\n\
++ \032 files, skipping some irrelevant information (order between entries,\n\
++ \032 for instance). We assume that, if the merge command exits normally,\n\
++ \032 then the two resulting files are \"as good as equal.\" (The reason we\n\
++ \032 copy one on top of the other is to avoid Unison detecting that the\n\
++ \032 files are unequal the next time it is run and trying again to merge\n\
++ \032 them when, in fact, the merge program has already made them as\n\
++ \032 similar as it is able to.)\n\
++ \n\
++ \032 If the confirmmerge preference is set and Unison is not run in batch\n\
++ \032 mode, then Unison will always ask for confirmation before actually\n\
++ \032 committing the results of the merge to the replicas.\n\
++ \n\
++ \032 A large number of external merging programs are available. For example,\n\
++ \032 on Unix systems setting the merge preference to\n\
++ \032 merge = Name *.txt -> diff3 -m CURRENT1 CURRENTARCH CURRENT2\n\
++ \032 > NEW || echo \"differences detected\"\n\
++ \n\
++ \032 will tell Unison to use the external diff3 program for merging.\n\
++ \032 Alternatively, users of emacs may find the following settings\n\
++ \032 convenient:\n\
++ \032 merge = Name *.txt -> emacs -q --eval '(ediff-merge-files-with-ancestor\n\
++ \032 \"CURRENT1\" \"CURRENT2\" \"CURRENTARCH\" nil \"NEW\")'\n\
++ \n\
++ \032 (These commands are displayed here on two lines to avoid running off\n\
++ \032 the edge of the page. In your preference file, each command should be\n\
++ \032 written on a single line.)\n\
++ \n\
++ \032 Users running emacs under windows may find something like this useful:\n\
++ \032 merge = Name * -> C:\\Progra~1\\Emacs\\emacs\\bin\\emacs.exe -q --eval\n\
++ \032 \"(ediff-files \"\"\"CURRENT1\"\"\" \"\"\"CURRENT2\"\"\")\"\n\
++ \n\
++ \032 Users running Mac OS X (you may need the Developer Tools installed to\n\
++ \032 get the opendiff utility) may prefer\n\
++ \032 merge = Name *.txt -> opendiff CURRENT1 CURRENT2 -ancestor CURRENTARCH -merg\n\
++ e NEW\n\
++ \n\
++ \032 Here is a slightly more involved hack. The opendiff program can operate\n\
++ \032 either with or without an archive file. A merge command of this form\n\
++ \032 merge = Name *.txt ->\n\
++ \032 if [ CURRENTARCHOPTx = x ];\n\
++ \032 then opendiff CURRENT1 CURRENT2 -merge NEW;\n\
++ \032 else opendiff CURRENT1 CURRENT2 -ancestor CURRENTARCHOPT -merge NE\n\
++ W;\n\
++ \032 fi\n\
++ \n\
++ \032 (still all on one line in the preference file!) will test whether an\n\
++ \032 archive file exists and use the appropriate variant of the arguments to\n\
++ \032 opendiff.\n\
++ \n\
++ \032 Ordinarily, external merge programs are only invoked when Unison is not\n\
++ \032 running in batch mode. To specify an external merge program that should\n\
++ \032 be used no matter the setting of the batch flag, use the mergebatch\n\
++ \032 preference instead of merge.\n\
++ \n\
++ \032 Please post suggestions for other useful values of the merge\n\
++ \032 preference to the unison-users mailing list--we'd like to give\n\
++ \032 several examples here.\n\
++ \n\
++ The User Interface\n\
++ \n\
++ \032 Both the textual and the graphical user interfaces are intended to be\n\
++ \032 mostly self-explanatory. Here are just a few tricks:\n\
++ \032 * By default, when running on Unix the textual user interface will\n\
++ \032 try to put the terminal into the \"raw mode\" so that it reads the\n\
++ \032 input a character at a time rather than a line at a time. (This\n\
++ \032 means you can type just the single keystroke \">\" to tell Unison to\n\
++ \032 propagate a file from left to right, rather than \"> Enter.\")\n\
++ \032 There are some situations, though, where this will not work -- for\n\
++ \032 example, when Unison is running in a shell window inside Emacs.\n\
++ \032 Setting the dumbtty preference will force Unison to leave the\n\
++ \032 terminal alone and process input a line at a time.\n\
++ \n\
++ Exit code\n\
++ \n\
++ \032 When running in the textual mode, Unison returns an exit status, which\n\
++ \032 describes whether, and at which level, the synchronization was\n\
++ \032 successful. The exit status could be useful when Unison is invoked from\n\
++ \032 a script. Currently, there are four possible values for the exit\n\
++ \032 status:\n\
++ \032 * 0: successful synchronization; everything is up-to-date now.\n\
++ \032 * 1: some files were skipped, but all file transfers were successful.\n\
++ \032 * 2: non-fatal failures occurred during file transfer.\n\
++ \032 * 3: a fatal error occurred, or the execution was interrupted.\n\
++ \n\
++ \032 The graphical interface does not return any useful information through\n\
++ \032 the exit status.\n\
++ \n\
++ Path specification\n\
++ \n\
++ \032 Several Unison preferences (e.g., ignore/ignorenot, follow,\n\
++ \032 sortfirst/sortlast, backup, merge, etc.) specify individual paths or\n\
++ \032 sets of paths. These preferences share a common syntax based on\n\
++ \032 regular-expressions. Each preference is associated with a list of path\n\
++ \032 patterns; the paths specified are those that match any one of the path\n\
++ \032 pattern.\n\
++ \032 * Pattern preferences can be given on the command line, or, more\n\
++ \032 often, stored in profiles, using the same syntax as other\n\
++ \032 preferences. For example, a profile line of the form\n\
++ \032 ignore = pattern\n\
++ \n\
++ \032 adds pattern to the list of patterns to be ignored.\n\
++ \032 * Each pattern can have one of three forms. The most general form is\n\
++ \032 a Posix extended regular expression introduced by the keyword\n\
++ \032 Regex. (The collating sequences and character classes of full Posix\n\
++ \032 regexps are not currently supported).\n\
++ \032 Regex regexp\n\
++ \n\
++ \032 For convenience, three other styles of pattern are also recognized:\n\
++ \032 Name name\n\
++ \n\
++ \032 matches any path in which the last component matches name,\n\
++ \032 Path path\n\
++ \n\
++ \032 matches exactly the path path, and\n\
++ \032 BelowPath path\n\
++ \n\
++ \032 matches the path path and any path below. The name and path\n\
++ \032 arguments of the latter forms of patterns are not regular\n\
++ \032 expressions. Instead, standard \"globbing\" conventions can be used\n\
++ \032 in name and path:\n\
++ \032 + a * matches any sequence of characters not including / (and\n\
++ \032 not beginning with ., when used at the beginning of a name)\n\
++ \032 + a ? matches any single character except / (and leading .)\n\
++ \032 + [xyz] matches any character from the set {x, y, z }\n\
++ \032 + {a,bb,ccc} matches any one of a, bb, or ccc.\n\
++ \032 * The path separator in path patterns is always the forward-slash\n\
++ \032 character \"/\" -- even when the client or server is running under\n\
++ \032 Windows, where the normal separator character is a backslash. This\n\
++ \032 makes it possible to use the same set of path patterns for both\n\
++ \032 Unix and Windows file systems.\n\
++ \n\
++ \032 Some examples of path patterns appear in the section \"Ignoring Paths\" .\n\
++ \n\
++ Ignoring Paths\n\
++ \n\
++ \032 Most users of Unison will find that their replicas contain lots of\n\
++ \032 files that they don't ever want to synchronize -- temporary files, very\n\
++ \032 large files, old stuff, architecture-specific binaries, etc. They can\n\
++ \032 instruct Unison to ignore these paths using patterns introduced in the\n\
++ \032 section \"Path Patterns\" .\n\
++ \n\
++ \032 For example, the following pattern will make Unison ignore any path\n\
++ \032 containing the name CVS or a name ending in .cmo:\n\
++ \032 ignore = Name {CVS,*.cmo}\n\
++ \n\
++ \032 The next pattern makes Unison ignore the path a/b:\n\
++ \032 ignore = Path a/b\n\
++ \n\
++ \032 Path patterns do not skip filesnames beginning with . (as Name patterns\n\
++ \032 do). For example,\n\
++ \032 ignore = Path */tmp\n\
++ \n\
++ \032 will include .foo/tmp in the set of ignore directories, as it is a\n\
++ \032 path, not a name, that is ignored.\n\
++ \n\
++ \032 The following pattern makes Unison ignore any path beginning with a/b\n\
++ \032 and ending with a name ending by .ml.\n\
++ \032 ignore = Regex a/b/.*\\.ml\n\
++ \n\
++ \032 Note that regular expression patterns are \"anchored\": they must match\n\
++ \032 the whole path, not just a substring of the path.\n\
++ \n\
++ \032 Here are a few extra points regarding the ignore preference.\n\
++ \032 * If a directory is ignored, all its descendents will be too.\n\
++ \032 * The user interface provides some convenient commands for adding new\n\
++ \032 patterns to be ignored. To ignore a particular file, select it and\n\
++ \032 press \"i\". To ignore all files with the same extension, select it\n\
++ \032 and press \"E\" (with the shift key). To ignore all files with the\n\
++ \032 same name, no matter what directory they appear in, select it and\n\
++ \032 press \"N\". These new patterns become permanent: they are\n\
++ \032 immediately added to the current profile on disk.\n\
++ \032 * If you use the include directive to include a common collection of\n\
++ \032 preferences in several top-level preference files, you will\n\
++ \032 probably also want to set the addprefsto preference to the name of\n\
++ \032 this file. This will cause any new ignore patterns that you add\n\
++ \032 from inside Unison to be appended to this file, instead of\n\
++ \032 whichever top-level preference file you started Unison with.\n\
++ \032 * Ignore patterns can also be specified on the command line, if you\n\
++ \032 like (this is probably not very useful), using an option like\n\
++ \032 -ignore 'Name temp.txt'.\n\
++ \032 * Be careful about renaming directories containing ignored files.\n\
++ \032 Because Unison understands the rename as a delete plus a create,\n\
++ \032 any ignored files in the directory will be lost (since they are\n\
++ \032 invisible to Unison and therefore they do not get recreated in the\n\
++ \032 new version of the directory).\n\
++ \032 * There is also an ignorenot preference, which specifies a set of\n\
++ \032 patterns for paths that should not be ignored, even if they match\n\
++ \032 an ignore pattern. However, the interaction of these two sets of\n\
++ \032 patterns can be a little tricky. Here is exactly how it works:\n\
++ \032 + Unison starts detecting updates from the root of the\n\
++ \032 replicas--i.e., from the empty path. If the empty path matches\n\
++ \032 an ignore pattern and does not match an ignorenot pattern,\n\
++ \032 then the whole replica will be ignored. (For this reason, it\n\
++ \032 is not a good idea to include Name * as an ignore pattern. If\n\
++ \032 you want to ignore everything except a certain set of files,\n\
++ \032 use Name ?*.)\n\
++ \032 + If the root is a directory, Unison continues looking for\n\
++ \032 updates in all the immediate children of the root. Again, if\n\
++ \032 the name of some child matches an ignore pattern and does not\n\
++ \032 match an ignorenot pattern, then this whole path including\n\
++ \032 everything below it will be ignored.\n\
++ \032 + If any of the non-ignored children are directories, then the\n\
++ \032 process continues recursively.\n\
++ \n\
++ Symbolic Links\n\
++ \n\
++ \032 Ordinarily, Unison treats symbolic links in Unix replicas as \"opaque\":\n\
++ \032 it considers the contents of the link to be just the string specifying\n\
++ \032 where the link points, and it will propagate changes in this string to\n\
++ \032 the other replica.\n\
++ \n\
++ \032 It is sometimes useful to treat a symbolic link \"transparently,\" acting\n\
++ \032 as though whatever it points to were physically in the replica at the\n\
++ \032 point where the symbolic link appears. To tell Unison to treat a link\n\
++ \032 in this manner, add a line of the form\n\
++ \032 follow = pathspec\n\
++ \n\
++ \032 to the profile, where pathspec is a path pattern as described in the\n\
++ \032 section \"Path Patterns\" .\n\
++ \n\
++ \032 Windows file systems do not support symbolic links; Unison will refuse\n\
++ \032 to propagate an opaque symbolic link from Unix to Windows and flag the\n\
++ \032 path as erroneous. When a Unix replica is to be synchronized with a\n\
++ \032 Windows system, all symbolic links should match either an ignore\n\
++ \032 pattern or a follow pattern.\n\
++ \n\
++ Permissions\n\
++ \n\
++ \032 Synchronizing the permission bits of files is slightly tricky when two\n\
++ \032 different filesytems are involved (e.g., when synchronizing a Windows\n\
++ \032 client and a Unix server). In detail, here's how it works:\n\
++ \032 * When the permission bits of an existing file or directory are\n\
++ \032 changed, the values of those bits that make sense on both operating\n\
++ \032 systems will be propagated to the other replica. The other bits\n\
++ \032 will not be changed.\n\
++ \032 * When a newly created file is propagated to a remote replica, the\n\
++ \032 permission bits that make sense in both operating systems are also\n\
++ \032 propagated. The values of the other bits are set to default values\n\
++ \032 (they are taken from the current umask, if the receiving host is a\n\
++ \032 Unix system).\n\
++ \032 * For security reasons, the Unix setuid and setgid bits are not\n\
++ \032 propagated.\n\
++ \032 * The Unix owner and group ids are not propagated. (What would this\n\
++ \032 mean, in general?) All files are created with the owner and group\n\
++ \032 of the server process.\n\
++ \n\
++ Cross-Platform Synchronization\n\
++ \n\
++ \032 If you use Unison to synchronize files between Windows and Unix\n\
++ \032 systems, there are a few special issues to be aware of.\n\
++ \n\
++ \032 Case conflicts. In Unix, filenames are case sensitive: foo and FOO can\n\
++ \032 refer to different files. In Windows, on the other hand, filenames are\n\
++ \032 not case sensitive: foo and FOO can only refer to the same file. This\n\
++ \032 means that a Unix foo and FOO cannot be synchronized onto a Windows\n\
++ \032 system -- Windows won't allow two different files to have the \"same\"\n\
++ \032 name. Unison detects this situation for you, and reports that it cannot\n\
++ \032 synchronize the files.\n\
++ \n\
++ \032 You can deal with a case conflict in a couple of ways. If you need to\n\
++ \032 have both files on the Windows system, your only choice is to rename\n\
++ \032 one of the Unix files to avoid the case conflict, and re-synchronize.\n\
++ \032 If you don't need the files on the Windows system, you can simply\n\
++ \032 disregard Unison's warning message, and go ahead with the\n\
++ \032 synchronization; Unison won't touch those files. If you don't want to\n\
++ \032 see the warning on each synchronization, you can tell Unison to ignore\n\
++ \032 the files (see the section \"Ignore\" ).\n\
++ \n\
++ \032 Illegal filenames. Unix allows some filenames that are illegal in\n\
++ \032 Windows. For example, colons (`:') are not allowed in Windows\n\
++ \032 filenames, but they are legal in Unix filenames. This means that a Unix\n\
++ \032 file foo:bar can't be synchronized to a Windows system. As with case\n\
++ \032 conflicts, Unison detects this situation for you, and you have the same\n\
++ \032 options: you can either rename the Unix file and re-synchronize, or you\n\
++ \032 can ignore it.\n\
++ \n\
++ Slow Links\n\
++ \n\
++ \032 Unison is built to run well even over relatively slow links such as\n\
++ \032 modems and DSL connections.\n\
++ \n\
++ \032 Unison uses the \"rsync protocol\" designed by Andrew Tridgell and Paul\n\
++ \032 Mackerras to greatly speed up transfers of large files in which only\n\
++ \032 small changes have been made. More information about the rsync protocol\n\
++ \032 can be found at the rsync web site (http://samba.anu.edu.au/rsync/).\n\
++ \n\
++ \032 If you are using Unison with ssh, you may get some speed improvement by\n\
++ \032 enabling ssh's compression feature. Do this by adding the option\n\
++ \032 \"-sshargs -C\" to the command line or \"sshargs = -C\" to your profile.\n\
++ \n\
++ Making Unison Faster on Large Files\n\
++ \n\
++ \032 Unison's built-in implementation of the rsync algorithm makes\n\
++ \032 transferring updates to existing files pretty fast. However, for\n\
++ \032 whole-file copies of newly created files, the built-in transfer method\n\
++ \032 is not highly optimized. Also, if Unison is interrupted in the middle\n\
++ \032 of transferring a large file, it will attempt to retransfer the whole\n\
++ \032 thing on the next run.\n\
++ \n\
++ \032 These shortcomings can be addressed with a little extra work by telling\n\
++ \032 Unison to use an external file copying utility for whole-file\n\
++ \032 transfers. The recommended one is the standalone rsync tool, which is\n\
++ \032 available by default on most Unix systems and can easily be installed\n\
++ \032 on Windows systems using Cygwin.\n\
++ \n\
++ \032 If you have rsync installed on both hosts, you can make Unison use it\n\
++ \032 simply by setting the copythreshold flag to something non-negative. If\n\
++ \032 you set it to 0, Unison will use the external copy utility for all\n\
++ \032 whole-file transfers. (This is probably slower than letting Unison copy\n\
++ \032 small files by itself, but can be useful for testing.) If you set it to\n\
++ \032 a larger value, Unison will use the external utility for all files\n\
++ \032 larger than this size (which is given in kilobytes, so setting it to\n\
++ \032 1000 will cause the external tool to be used for all transfers larger\n\
++ \032 than a megabyte).\n\
++ \n\
++ \032 If you want to use a different external copy utility, set both the\n\
++ \032 copyprog and copyprogpartial preferences--the former is used for the\n\
++ \032 first transfer of a file, while the latter is used when Unison sees a\n\
++ \032 partially transferred temp file on the receiving host. Be careful here:\n\
++ \032 Your external tool needs to be instructed to copy files in place\n\
++ \032 (otherwise if the transfer is interrupted Unison will not notice that\n\
++ \032 some of the data has already been transferred, the next time it tries).\n\
++ \032 The default values are:\n\
++ \032 copyprog = rsync --inplace --compress\n\
++ \032 copyprogrest = rsync --partial --inplace --compress\n\
++ \n\
++ \032 You may also need to set the copyquoterem preference. When it is set to\n\
++ \032 true, this causes Unison to add an extra layer of quotes to the remote\n\
++ \032 path passed to the external copy program. This is is needed by rsync,\n\
++ \032 for example, which internally uses an ssh connection, requiring an\n\
++ \032 extra level of quoting for paths containing spaces. When this flag is\n\
++ \032 set to default, extra quotes are added if the value of copyprog\n\
++ \032 contains the string rsync. The default value is default, naturally.\n\
++ \n\
++ \032 If a directory transfer is interrupted, the next run of Unison will\n\
++ \032 automatically skip any files that were completely transferred before\n\
++ \032 the interruption. (This behavior is always on: it does not depend on\n\
++ \032 the setting of the copythreshold preference.) Note, though, that the\n\
++ \032 new directory will not appear in the destination filesystem until\n\
++ \032 everything has been transferred--partially transferred directories are\n\
++ \032 kept in a temporary location (with names like .unison.DIRNAME....)\n\
++ \032 until the transfer is complete.\n\
++ \n\
++ Fast Update Detection\n\
++ \n\
++ \032 If your replicas are large and at least one of them is on a Windows\n\
++ \032 system, you may find that Unison's default method for detecting changes\n\
++ \032 (which involves scanning the full contents of every file on every\n\
++ \032 sync--the only completely safe way to do it under Windows) is too slow.\n\
++ \032 Unison provides a preference fastcheck that, when set to true, causes\n\
++ \032 it to use file creation times as 'pseudo inode numbers' when scanning\n\
++ \032 replicas for updates, instead of reading the full contents of every\n\
++ \032 file.\n\
++ \n\
++ \032 When fastcheck is set to no, Unison will perform slow\n\
++ \032 checking--re-scanning the contents of each file on each\n\
++ \032 synchronization--on all replicas. When fastcheck is set to default\n\
++ \032 (which, naturally, is the default), Unison will use fast checks on Unix\n\
++ \032 replicas and slow checks on Windows replicas.\n\
++ \n\
++ \032 This strategy may cause Unison to miss propagating an update if the\n\
++ \032 modification time and length of the file are both unchanged by the\n\
++ \032 update. However, Unison will never overwrite such an update with a\n\
++ \032 change from the other replica, since it always does a safe check for\n\
++ \032 updates just before propagating a change. Thus, it is reasonable to use\n\
++ \032 this switch most of the time and occasionally run Unison once with\n\
++ \032 fastcheck set to no, if you are worried that Unison may have overlooked\n\
++ \032 an update.\n\
++ \n\
++ \032 Fastcheck is (always) automatically disabled for files with extension\n\
++ \032 .xls or .mpp, to prevent Unison from being confused by the habits of\n\
++ \032 certain programs (Excel, in particular) of updating files without\n\
++ \032 changing their modification times.\n\
++ \n\
++ Mount Points and Removable Media\n\
++ \n\
++ \032 Using Unison removable media such as USB drives can be dangerous unless\n\
++ \032 you are careful. If you synchronize a directory that is stored on\n\
++ \032 removable media when the media is not present, it will look to Unison\n\
++ \032 as though the whole directory has been deleted, and it will proceed to\n\
++ \032 delete the directory from the other replica--probably not what you\n\
++ \032 want!\n\
++ \n\
++ \032 To prevent accidents, Unison provides a preference called mountpoint.\n\
++ \032 Including a line like\n\
++ \032 mountpoint = foo\n\
++ \n\
++ \032 in your preference file will cause Unison to check, after it finishes\n\
++ \032 detecting updates, that something actually exists at the path foo on\n\
++ \032 both replicas; if it does not, the Unison run will abort.\n\
++ \n\
++ Click-starting Unison\n\
++ \n\
++ \032 On Windows NT/2k/XP systems, the graphical version of Unison can be\n\
++ \032 invoked directly by clicking on its icon. On Windows 95/98 systems,\n\
++ \032 click-starting also works, as long as you are not using ssh. Due to an\n\
++ \032 incompatibility with ocaml and Windows 95/98 that is not under our\n\
++ \032 control, you must start Unison from a DOS window in Windows 95/98 if\n\
++ \032 you want to use ssh.\n\
++ \n\
++ \032 When you click on the Unison icon, two windows will be created:\n\
++ \032 Unison's regular window, plus a console window, which is used only for\n\
++ \032 giving your password to ssh (if you do not use ssh to connect, you can\n\
++ \032 ignore this window). When your password is requested, you'll need to\n\
++ \032 activate the console window (e.g., by clicking in it) before typing. If\n\
++ \032 you start Unison from a DOS window, Unison's regular window will appear\n\
++ \032 and you will type your password in the DOS window you were using.\n\
++ \n\
++ \032 To use Unison in this mode, you must first create a profile (see the\n\
++ \032 section \"Profile\" ). Use your favorite editor for this.\n\
++ \n\
++ "))
++::
++ ("ssh", ("Installing Ssh",
++ "Installing Ssh\n\
++ \n\
++ \032 Warning: These instructions may be out of date. More current\n\
++ \032 information can be found the Unison Wiki\n\
++ \032 (http://alliance.seas.upenn.edu/ bcpierce/wiki/index.php?n=Main.UnisonF\n\
++ \032 AQOSSpecific).\n\
++ \n\
++ \032 Your local host will need just an ssh client; the remote host needs an\n\
++ \032 ssh server (or daemon), which is available on Unix systems. Unison is\n\
++ \032 known to work with ssh version 1.2.27 (Unix) and version 1.2.14\n\
++ \032 (Windows); other versions may or may not work.\n\
++ \n\
++ Unix\n\
++ \n\
++ \032 Most modern Unix installations come with ssh pre-installed.\n\
++ \n\
++ Windows\n\
++ \n\
++ \032 Many Windows implementations of ssh only provide graphical interfaces,\n\
++ \032 but Unison requires an ssh client that it can invoke with a\n\
++ \032 command-line interface. A suitable version of ssh can be installed as\n\
++ \032 follows.\n\
++ \032 1. Download an ssh executable.\n\
++ \032 Warning: there are many implementations and ports of ssh for\n\
++ \032 Windows, and not all of them will work with Unison. We have gotten\n\
++ \032 Unison to work with Cygwin's port of openssh, and we suggest you\n\
++ \032 try that one first. Here's how to install it:\n\
++ \032 a. First, create a new folder on your desktop to hold temporary\n\
++ \032 installation files. It can have any name you like, but in\n\
++ \032 these instructions we'll assume that you call it Foo.\n\
++ \032 b. Direct your web browser to www.cygwin.com, and click on the\n\
++ \032 \"Install now!\" link. This will download a file, setup.exe;\n\
++ \032 save it in the directory Foo. The file setup.exe is a small\n\
++ \032 program that will download the actual install files from the\n\
++ \032 Internet when you run it.\n\
++ \032 c. Start setup.exe (by double-clicking). This brings up a series\n\
++ \032 of dialogs that you will have to go through. Select \"Install\n\
++ \032 from Internet.\" For \"Local Package Directory\" select the\n\
++ \032 directory Foo. For \"Select install root directory\" we\n\
++ \032 recommend that you use the default, C:\\cygwin. The next dialog\n\
++ \032 asks you to select the way that you want to connect to the\n\
++ \032 network to download the installation files; we have used \"Use\n\
++ \032 IE5 Settings\" successfully, but you may need to make a\n\
++ \032 different selection depending on your networking setup. The\n\
++ \032 next dialog gives a list of mirrors; select one close to you.\n\
++ \032 Next you are asked to select which packages to install. The\n\
++ \032 default settings in this dialog download a lot of packages\n\
++ \032 that are not strictly necessary to run Unison with ssh. If you\n\
++ \032 don't want to install a package, click on it until \"skip\" is\n\
++ \032 shown. For a minimum installation, select only the packages\n\
++ \032 \"cygwin\" and \"openssh,\" which come to about 1900KB; the full\n\
++ \032 installation is much larger.\n\
++ \n\
++ \032 Note that you are plan to build unison using the free CygWin GNU C\n\
++ \032 compiler, you need to install essential development packages such as\n\
++ \032 \"gcc\", \"make\", \"fileutil\", etc; we refer to the file\n\
++ \032 \"INSTALL.win32-cygwin-gnuc\" in the source distribution for further\n\
++ \032 details.\n\
++ \032 After the packages are downloaded and installed, the next\n\
++ \032 dialog allows you to choose whether to \"Create Desktop Icon\"\n\
++ \032 and \"Add to Start Menu.\" You make the call.\n\
++ \032 d. You can now delete the directory Foo and its contents.\n\
++ \032 Some people have reported problems using Cygwin's ssh with Unison.\n\
++ \032 If you have trouble, you might try other ones instead:\n\
++ \032 http://linuxmafia.com/ssh/win32.html\n\
++ \n\
++ \032 2. You must set the environment variables HOME and PATH. Ssh will\n\
++ \032 create a directory .ssh in the directory given by HOME, so that it\n\
++ \032 has a place to keep data like your public and private keys. PATH\n\
++ \032 must be set to include the Cygwin bin directory, so that Unison can\n\
++ \032 find the ssh executable.\n\
++ \032 + On Windows 95/98, add the lines\n\
++ \032 set PATH=%PATH%;<SSHDIR>\n\
++ \032 set HOME=<HOMEDIR>\n\
++ \n\
++ \032 to the file C:\\AUTOEXEC.BAT, where <HOMEDIR> is the directory\n\
++ \032 where you want ssh to create its .ssh directory, and <SSHDIR>\n\
++ \032 is the directory where the executable ssh.exe is stored; if\n\
++ \032 you've installed Cygwin in the default location, this is\n\
++ \032 C:\\cygwin\\bin. You will have to reboot your computer to take\n\
++ \032 the changes into account.\n\
++ \032 + On Windows NT/2k/XP, open the environment variables dialog\n\
++ \032 box:\n\
++ \032 o Windows NT: My Computer/Properties/Environment\n\
++ \032 o Windows 2k: My Computer/Properties/Advanced/Environment\n\
++ \032 variables\n\
++ \032 then select Path and edit its value by appending ;<SSHDIR> to\n\
++ \032 it, where <SSHDIR> is the full name of the directory that\n\
++ \032 includes the ssh executable; if you've installed Cygwin in the\n\
++ \032 default location, this is C:\\cygwin\\bin.\n\
++ \032 3. Test ssh from a DOS shell by typing\n\
++ \032 ssh <remote host> -l <login name>\n\
++ \n\
++ \032 You should get a prompt for your password on <remote host>,\n\
++ \032 followed by a working connection.\n\
++ \032 4. Note that ssh-keygen may not work (fails with \"gethostname: no such\n\
++ \032 file or directory\") on some systems. This is OK: you can use ssh\n\
++ \032 with your regular password for the remote system.\n\
++ \032 5. You should now be able to use Unison with an ssh connection. If you\n\
++ \032 are logged in with a different user name on the local and remote\n\
++ \032 hosts, provide your remote user name when providing the remote root\n\
++ \032 (i.e., //username at host/path...).\n\
++ \n\
++ "))
++::
++ ("news", ("Changes in Version 2.40.69",
++ "Changes in Version 2.40.69\n\
++ \n\
++ \032 Changes since 2.40.1:\n\
++ \032 * Added \"BelowPath\" patterns, that match a path as well as all paths\n\
++ \032 below (convenient to use with nodeletion,update,creationpartial\n\
++ \032 preferences)\n\
++ \032 * Added a \"fat\" preference that makes Unison use the right options\n\
++ \032 when one of the replica is on a FAT filesystem.\n\
++ \032 * Allow \"prefer/force=newer\" even when not synchronizing modification\n\
++ \032 times. (The reconciler will not be aware of the modification time\n\
++ \032 of unchanged files, so the synchronization choices of Unison can be\n\
++ \032 different from when \"times=true\", but the behavior remains sane:\n\
++ \032 changed files with the most recent modification time will be\n\
++ \032 propagated.)\n\
++ \032 * Minor fixes and improvements:\n\
++ \032 + Compare filenames up to decomposition in case sensitive mode\n\
++ \032 when one host is running MacOSX and the unicode preference is\n\
++ \032 set to true.\n\
++ \032 + Rsync: somewhat faster compressor\n\
++ \032 + Make Unicode the default on all architectures (it was only the\n\
++ \032 default when a Mac OS X or Windows machine was involved).\n\
++ \n\
++ \032 Changes since 2.32:\n\
++ \032 * Major enhancement: Unicode support.\n\
++ \032 + Unison should now handle unicode filenames correctly on all\n\
++ \032 platforms.\n\
++ \032 + This functionality is controlled by a new preference unicode.\n\
++ \032 + Unicode mode is now the default when one of the hosts is under\n\
++ \032 Windows or MacOS. This may make upgrades a bit more painful\n\
++ \032 (the archives cannot be reused), but this is a much saner\n\
++ \032 default.\n\
++ \032 * Partial transfer of directories. If an error occurs while\n\
++ \032 transferring a directory, the part transferred so far is copied\n\
++ \032 into place (and the archives are updated accordingly). The\n\
++ \032 \"maxerrors\" preference controls how many transfer error Unison will\n\
++ \032 accept before stopping the transfer of a directory (by default,\n\
++ \032 only one). This makes it possible to transfer most of a directory\n\
++ \032 even if there are some errors. Currently, only the first error is\n\
++ \032 reported by the GUIs.\n\
++ \032 Also, allow partial transfer of a directory when there was an error\n\
++ \032 deep inside this directory during update detection. At the moment,\n\
++ \032 this is only activated with the text and GTK UIs, which have been\n\
++ \032 modified so that they show that the transfer is going to be partial\n\
++ \032 and so that they can display all errors.\n\
++ \032 * Improvement to the code for resuming directory transfers:\n\
++ \032 + if a file was not correctly transferred (or the source has\n\
++ \032 been modified since, with unchanged size), Unison performs a\n\
++ \032 new transfer rather than failing\n\
++ \032 + spurious files are deleted (this can happen if a file is\n\
++ \032 deleted on the source replica before resuming the transfer;\n\
++ \032 not deleting the file would result in it reappearing on the\n\
++ \032 target replica)\n\
++ \032 * Experimental streaming protocol for transferring file contents (can\n\
++ \032 be disabled by setting the directive \"stream\" to false): file\n\
++ \032 contents is transfered asynchronously (without waiting for a\n\
++ \032 response from the destination after each chunk sent) rather than\n\
++ \032 using the synchronous RPC mechanism. As a consequence:\n\
++ \032 + Unison now transfers the contents of a single file at a time\n\
++ \032 (Unison used to transfer several contents simultaneously in\n\
++ \032 order to hide the connection latency.)\n\
++ \032 + the transfer of large files uses the full available bandwidth\n\
++ \032 and is not slowed done due to the connection latency anymore\n\
++ \032 + we get performance improvement for small files as well by\n\
++ \032 scheduling many files simultaneously (as scheduling a file for\n\
++ \032 transfer consume little ressource: it does not mean allocating\n\
++ \032 a large buffer anymore)\n\
++ \032 * Changes to the internal implementation of the rsync algorithm:\n\
++ \032 + use longer blocks for large files (the size of a block is the\n\
++ \032 square root of the size of the file for large files);\n\
++ \032 + transmit less checksum information per block (we still have\n\
++ \032 less than one chance in a hundred million of transferring a\n\
++ \032 file incorrectly, and Unison will catch any transfer error\n\
++ \032 when fingerprinting the whole file)\n\
++ \032 + avoid transfer overhead (which was 4 bytes per block)\n\
++ \032 For a 1G file, the first optimization saves a factor 50 on the\n\
++ \032 amount of data transferred from the target to the source (blocks\n\
++ \032 are 32768 bytes rather than just 700 bytes). The two other\n\
++ \032 optimizations save another factor of 2 (from 24 bytes per block\n\
++ \032 down to 10).\n\
++ \032 * Implemented an on-disk file fingerprint cache to speed-up update\n\
++ \032 detection after a crash: this way, Unison does not have do\n\
++ \032 recompute all the file fingerprints from scratch.\n\
++ \032 + When Unison detects that the archive case-sensitivity mode\n\
++ \032 does not match the current settings, it populates the\n\
++ \032 fingerprint cache using the archive contents. This way,\n\
++ \032 changing the case-sensitivity mode should be reasonably fast.\n\
++ \032 * New preferences \"noupdate=root\", \"nodeletion=root\",\n\
++ \032 \"nocreation=root\" that prevent Unison from performing files\n\
++ \032 updates, deletions or creations on the given root. Also 'partial'\n\
++ \032 versions of 'noupdate', 'nodeletion' and 'nocreation'\n\
++ \032 * Limit the number of simultaneous external copy program (\"copymax\"\n\
++ \032 preference)\n\
++ \032 * New \"links\" preference. When set to false, Unison will report an\n\
++ \032 error on symlinks during update detection. (This is the default\n\
++ \032 when one host is running Windows but not Cygwin.) This is better\n\
++ \032 than failing during propagation.\n\
++ \032 * Added a preference \"halfduplex\" to force half-duplex communication\n\
++ \032 with the server. This may be useful on unreliable links (as a more\n\
++ \032 efficient alternative to \"maxthreads = 1\").\n\
++ \032 * Renamed preference \"pretendwin\" to \"ignoreinodenumbers\" (an alias\n\
++ \032 is kept for backwards compatibility).\n\
++ \032 * Ignore one-second differences when synchronizing modification time.\n\
++ \032 (Technically, this is an incompatible archive format change, but it\n\
++ \032 is backward compatible. To trigger a problem, a user would have to\n\
++ \032 synchronize modification times on a filesystem with a two-second\n\
++ \032 granularity and then downgrade to a previous version of Unison,\n\
++ \032 which does not work well in such a case. Thus, it does not seem\n\
++ \032 worthwhile to increment the archive format number, which would\n\
++ \032 impact all users.)\n\
++ \032 * Do not keep many files simultaneously opened anymore when the rsync\n\
++ \032 algorithm is in use.\n\
++ \032 * Add \"ignorearchives\" preference to ignore existing archives (to\n\
++ \032 avoid forcing users to delete them manually, in situations where\n\
++ \032 one archive has gotten deleted or corrupted).\n\
++ \032 * Mac OS\n\
++ \032 + fixed rsync bug which could result in an \"index out of bounds\"\n\
++ \032 error when transferring resource forks.\n\
++ \032 + Fixed bug which made Unison ignore finder information and\n\
++ \032 resource fork when compiled to 64bit on Mac OSX.\n\
++ \032 + should now be 64 bit clean (the Growl framework is not up to\n\
++ \032 date, though)\n\
++ \032 + Made the bridge between Objective C and Ocaml code GC friendly\n\
++ \032 (it was allocating ML values and putting them in an array\n\
++ \032 which was not registered with the GC)\n\
++ \032 + use darker grey arrows (patch contributed by Eric Y. Kow)\n\
++ \032 * GTK user interface\n\
++ \032 + assistant for creating profiles\n\
++ \032 + profile editor\n\
++ \032 + pop up a summary window when the replicas are not fully\n\
++ \032 synchronized after transport\n\
++ \032 + display estimated remaining time and transfer rate on the\n\
++ \032 progress bar\n\
++ \032 + allow simultaneous selection of several items\n\
++ \032 + Do not reload the preference file before a new update\n\
++ \032 detection if it is unchanged\n\
++ \032 + disabled scrolling to the first unfinished item during\n\
++ \032 transport. It goes way too fast when lot of small files are\n\
++ \032 synchronized, and it makes it impossible to browse the file\n\
++ \032 list during transport.\n\
++ \032 + take into account the \"height\" preference again\n\
++ \032 + the internal list of selected reconciler item was not always\n\
++ \032 in sync with what was displayed (GTK bug?); workaround\n\
++ \032 implemented\n\
++ \032 + Do not display \"Looking for change\" messages during\n\
++ \032 propagation (when checking the targe is unchanged) but only\n\
++ \032 during update detection\n\
++ \032 + Apply patch to fix some crashes in the OSX GUI, thanks to Onne\n\
++ \032 Gorter.\n\
++ \032 * Text UI\n\
++ \032 + During update detection, display status by updating a single\n\
++ \032 line rather than generating a new line of output every so\n\
++ \032 often. Should be less confusing.\n\
++ \032 * Windows\n\
++ \032 + Fastcheck is now the default under Windows. People mostly use\n\
++ \032 NTFS nowadays and the Unicode API provides an equivalent to\n\
++ \032 inode numbers for this filesystem.\n\
++ \032 + Only use long UNC path for accessing replicas (as '..' is not\n\
++ \032 handled with this format of paths, but can be useful)\n\
++ \032 + Windows text UI: now put the console into UTF-8 output mode.\n\
++ \032 This is the right thing to do when in Unicode mode, and is no\n\
++ \032 worse than what we had previously otherwise (the console use\n\
++ \032 some esoteric encoding by default). This only works when using\n\
++ \032 a Unicode font instead of the default raster font.\n\
++ \032 + Don't get the home directory from environment variable HOME\n\
++ \032 under Windows (except for Cygwin binaries): we don't want the\n\
++ \032 behavior of Unison to depends on whether it is run from a\n\
++ \032 Cygwin shell (where HOME is set) or in any other way (where\n\
++ \032 HOME is usually not set).\n\
++ \032 * Miscellaneous fixes and improvements\n\
++ \032 + Made a server waiting on a socket more resilient to unexpected\n\
++ \032 lost connections from the client.\n\
++ \032 + Small patch to property setting code suggested by Ulrich\n\
++ \032 Gernkow.\n\
++ \032 + Several fixes to the change transfer functions (both the\n\
++ \032 internal ones and external transfers using rsync). In\n\
++ \032 particular, limit the number of simultaneous transfer using an\n\
++ \032 rsync (as the rsync algorithm can use a large amount of memory\n\
++ \032 when processing huge files)\n\
++ \032 + Keep track of which file contents are being transferred, and\n\
++ \032 delay the transfer of a file when another file with the same\n\
++ \032 contents is currently being transferred. This way, the second\n\
++ \032 transfer can be skipped and replaced by a local copy.\n\
++ \032 + Experimental update detection optimization: do not read the\n\
++ \032 contents of unchanged directories\n\
++ \032 + When a file transfer fails, turn off fastcheck for this file\n\
++ \032 on the next sync.\n\
++ \032 + Fixed bug with case insensitive mode on a case sensitive\n\
++ \032 filesystem:\n\
++ \032 o if file \"a/a\" is created on one replica and directory \"A\"\n\
++ \032 is created on the other, the file failed to be\n\
++ \032 synchronized the first time Unison is run afterwards, as\n\
++ \032 Unison uses the wrong path \"a/a\" (if Unison is run again,\n\
++ \032 the directories are in the archive, so the right path is\n\
++ \032 used);\n\
++ \032 o if file \"a\" appears on one replica and file \"A\" appears\n\
++ \032 on the other with different contents, Unison was unable\n\
++ \032 to synchronize them.\n\
++ \032 + Improved error reporting when the destination is updated\n\
++ \032 during synchronization: Unison now tells which file has been\n\
++ \032 updated, and how.\n\
++ \032 + Limit the length of temporary file names\n\
++ \032 + Case sensitivity information put in the archive (in a backward\n\
++ \032 compatible way) and checked when the archive is loaded\n\
++ \032 + Got rid of the 16mb marshalling limit by marshalling to a\n\
++ \032 bigarray.\n\
++ \032 + Resume copy of partially transferred files.\n\
++ \n\
++ \032 Changes since 2.31:\n\
++ \032 * Small user interface changes\n\
++ \032 + Small change to text UI \"scanning...\" messages, to print just\n\
++ \032 directories (hopefully making it clearer that individual files\n\
++ \032 are not necessarily being fingerprinted).\n\
++ \032 * Minor fixes and improvements:\n\
++ \032 + Ignore one hour differences when deciding whether a file may\n\
++ \032 have been updated. This avoids slow update detection after\n\
++ \032 daylight saving time changes under Windows. This makes Unison\n\
++ \032 slightly more likely to miss an update, but it should be safe\n\
++ \032 enough.\n\
++ \032 + Fix a small bug that was affecting mainly windows users. We\n\
++ \032 need to commit the archives at the end of the sync even if\n\
++ \032 there are no updates to propagate because some files (in fact,\n\
++ \032 if we've just switched to DST on windows, a LOT of files)\n\
++ \032 might have new modtimes in the archive. (Changed the text UI\n\
++ \032 only. It's less clear where to change the GUI.)\n\
++ \032 + Don't delete the temp file when a transfer fails due to a\n\
++ \032 fingerprint mismatch (so that we can have a look and see why!)\n\
++ \032 We've also added more debugging code togive more informative\n\
++ \032 error messages when we encounter the dreaded and longstanding\n\
++ \032 \"assert failed during file transfer\" bug\n\
++ \032 + Incorrect paths (\"path\" directive) now result in an error\n\
++ \032 update item rather than a fatal error.\n\
++ \032 + Create parent directories (with correct permissions) during\n\
++ \032 transport for paths which point to non-existent locations in\n\
++ \032 the destination replica.\n\
++ \n\
++ \032 Changes since 2.27:\n\
++ \032 * If Unison is interrupted during a directory transfer, it will now\n\
++ \032 leave the partially transferred directory intact in a temporary\n\
++ \032 location. (This maintains the invariant that new files/directories\n\
++ \032 are transferred either completely or not at all.) The next time\n\
++ \032 Unison is run, it will continue filling in this temporary\n\
++ \032 directory, skipping transferring files that it finds are already\n\
++ \032 there.\n\
++ \032 * We've added experimental support for invoking an external file\n\
++ \032 transfer tool for whole-file copies instead of Unison's built-in\n\
++ \032 transfer protocol. Three new preferences have been added:\n\
++ \032 + copyprog is a string giving the name (and command-line\n\
++ \032 switches, if needed) of an external program that can be used\n\
++ \032 to copy large files efficiently. By default, rsync is invoked,\n\
++ \032 but other tools such as scp can be used instead by changing\n\
++ \032 the value of this preference. (Although this is not its\n\
++ \032 primary purpose, rsync is actually a pretty fast way of\n\
++ \032 copying files that don't already exist on the receiving host.)\n\
++ \032 For files that do already exist on (but that have been changed\n\
++ \032 in one replica), Unison will always use its built-in\n\
++ \032 implementation of the rsync algorithm.\n\
++ \032 + Added a \"copyprogrest\" preference, so that we can give\n\
++ \032 different command lines for invoking the external copy utility\n\
++ \032 depending on whether a partially transferred file already\n\
++ \032 exists or not. (Rsync doesn't seem to care about this, but\n\
++ \032 other utilities may.)\n\
++ \032 + copythreshold is an integer (-1 by default), indicating above\n\
++ \032 what filesize (in megabytes) Unison should use the external\n\
++ \032 copying utility specified by copyprog. Specifying 0 will cause\n\
++ \032 ALL copies to use the external program; a negative number will\n\
++ \032 prevent any files from using it. (Default is -1.)\n\
++ \032 Thanks to Alan Schmitt for a huge amount of hacking and to an\n\
++ \032 anonymous sponsor for suggesting and underwriting this extension.\n\
++ \032 * Small improvements:\n\
++ \032 + Added a new preference, dontchmod. By default, Unison uses the\n\
++ \032 chmod system call to set the permission bits of files after it\n\
++ \032 has copied them. But in some circumstances (and under some\n\
++ \032 operating systems), the chmod call always fails. Setting this\n\
++ \032 preference completely prevents Unison from ever calling chmod.\n\
++ \032 + Don't ignore files that look like backup files if the\n\
++ \032 backuplocation preference is set to central\n\
++ \032 + Shortened the names of several preferences. The old names are\n\
++ \032 also still supported, for backwards compatibility, but they do\n\
++ \032 not appear in the documentation.\n\
++ \032 + Lots of little documentation tidying. (In particular,\n\
++ \032 preferences are separated into Basic and Advanced! This should\n\
++ \032 hopefully make Unison a little more approachable for new\n\
++ \032 users.\n\
++ \032 + Unison can sometimes fail to transfer a file, giving the\n\
++ \032 unhelpful message \"Destination updated during synchronization\"\n\
++ \032 even though the file has not been changed. This can be caused\n\
++ \032 by programs that change either the file's contents or the\n\
++ \032 file's extended attributes without changing its modification\n\
++ \032 time. It's not clear what is the best fix for this - it is not\n\
++ \032 Unison's fault, but it makes Unison's behavior puzzling - but\n\
++ \032 at least Unison can be more helpful about suggesting a\n\
++ \032 workaround (running once with fastcheck set to false). The\n\
++ \032 failure message has been changed to give this advice.\n\
++ \032 + Further improvements to the OS X GUI (thanks to Alan Schmitt\n\
++ \032 and Craig Federighi).\n\
++ \032 * Very preliminary support for triggering Unison from an external\n\
++ \032 filesystem-watching utility. The current implementation is very\n\
++ \032 simple, not efficient, and almost completely untested--not ready\n\
++ \032 for real users. But if someone wants to help improve it (e.g., by\n\
++ \032 writing a filesystem watcher for your favorite OS), please make\n\
++ \032 yourself known!\n\
++ \032 On the Unison side, the new behavior is very simple:\n\
++ \032 + use the text UI\n\
++ \032 + start Unison with the command-line flag \"-repeat FOO\", where\n\
++ \032 FOO is name of a file where Unison should look for\n\
++ \032 notifications of changes\n\
++ \032 + when it starts up, Unison will read the whole contents of this\n\
++ \032 file (on both hosts), which should be a newline-separated list\n\
++ \032 of paths (relative to the root of the synchronization) and\n\
++ \032 synchronize just these paths, as if it had been started with\n\
++ \032 the \"-path=xxx\" option for each one of them\n\
++ \032 + when it finishes, it will sleep for a few seconds and then\n\
++ \032 examine the watchfile again; if anything has been added, it\n\
++ \032 will read the new paths, synchronize them, and go back to\n\
++ \032 sleep\n\
++ \032 + that's it!\n\
++ \032 To use this to drive Unison \"incrementally,\" just start it in this\n\
++ \032 mode and start up a tool (on each host) to watch for new changes to\n\
++ \032 the filesystem and append the appropriate paths to the watchfile.\n\
++ \032 Hopefully such tools should not be too hard to write.\n\
++ \032 * Bug fixes:\n\
++ \032 + Fixed a bug that was causing new files to be created with\n\
++ \032 permissions 0x600 instead of using a reasonable default (like\n\
++ \032 0x644), if the 'perms' flag was set to 0. (Bug reported by Ben\n\
++ \032 Crowell.)\n\
++ \032 + Follow maxthreads preference when transferring directories.\n\
++ \n\
++ \032 Changes since 2.17:\n\
++ \032 * Major rewrite and cleanup of the whole Mac OS X graphical user\n\
++ \032 interface by Craig Federighi. Thanks, Craig!!!\n\
++ \032 * Small fix to ctime (non-)handling in update detection under windows\n\
++ \032 with fastcheck.\n\
++ \032 * Several small fixes to the GTK2 UI to make it work better under\n\
++ \032 Windows [thanks to Karl M for these].\n\
++ \032 * The backup functionality has been completely rewritten. The\n\
++ \032 external interface has not changed, but numerous bugs, irregular\n\
++ \032 behaviors, and cross-platform inconsistencies have been corrected.\n\
++ \032 * The Unison project now accepts donations via PayPal. If you'd like\n\
++ \032 to donate, you can find a link to the donation page on the Unison\n\
++ \032 home page (http://www.cis.upenn.edu/ bcpierce/unison/lists.html).\n\
++ \032 * Some important safety improvements:\n\
++ \032 + Added a new mountpoint preference, which can be used to\n\
++ \032 specify a path that must exist in both replicas at the end of\n\
++ \032 update detection (otherwise Unison aborts). This can be used\n\
++ \032 to avoid potentially dangerous situations when Unison is used\n\
++ \032 with removable media such as external hard drives and compact\n\
++ \032 flash cards.\n\
++ \032 + The confirmation of \"big deletes\" is now controlled by a\n\
++ \032 boolean preference confirmbigdeletes. Default is true, which\n\
++ \032 gives the same behavior as previously. (This functionality is\n\
++ \032 at least partly superceded by the mountpoint preference, but\n\
++ \032 it has been left in place in case it is useful to some\n\
++ \032 people.)\n\
++ \032 + If Unison is asked to \"follow\" a symbolic link but there is\n\
++ \032 nothing at the other end of the link, it will now flag this\n\
++ \032 path as an error, rather than treating the symlink itself as\n\
++ \032 missing or deleted. This avoids a potentially dangerous\n\
++ \032 situation where a followed symlink points to an external\n\
++ \032 filesystem that might be offline when Unison is run (whereupon\n\
++ \032 Unison would cheerfully delete the corresponding files in the\n\
++ \032 other replica!).\n\
++ \032 * Smaller changes:\n\
++ \032 + Added forcepartial and preferpartial preferences, which behave\n\
++ \032 like force and prefer but can be specified on a per-path\n\
++ \032 basis. [Thanks to Alan Schmitt for this.]\n\
++ \032 + A bare-bones self test feature was added, which runs unison\n\
++ \032 through some of its paces and checks that the results are as\n\
++ \032 expected. The coverage of the tests is still very limited, but\n\
++ \032 the facility has already been very useful in debugging the new\n\
++ \032 backup functionality (especially in exposing some subtle\n\
++ \032 cross-platform issues).\n\
++ \032 + Refined debugging code so that the verbosity of individual\n\
++ \032 modules can be controlled separately. Instead of just putting\n\
++ \032 '-debug verbose' on the command line, you can put '-debug\n\
++ \032 update+', which causes all the extra messages in the Update\n\
++ \032 module, but not other modules, to be printed. Putting '-debug\n\
++ \032 verbose' causes all modules to print with maximum verbosity.\n\
++ \032 + Removed mergebatch preference. (It never seemed very useful,\n\
++ \032 and its semantics were confusing.)\n\
++ \032 + Rewrote some of the merging functionality, for better\n\
++ \032 cooperation with external Harmony instances.\n\
++ \032 + Changed the temp file prefix from .# to .unison.\n\
++ \032 + Compressed the output from the text user interface\n\
++ \032 (particularly when run with the -terse flag) to make it easier\n\
++ \032 to interpret the results when Unison is run several times in\n\
++ \032 succession from a script.\n\
++ \032 + Diff and merge functions now work under Windows.\n\
++ \032 + Changed the order of arguments to the default diff command (so\n\
++ \032 that the + and - annotations in diff's output are reversed).\n\
++ \032 + Added .mpp files to the \"never fastcheck\" list (like .xls\n\
++ \032 files).\n\
++ \032 * Many small bugfixes, including:\n\
++ \032 + Fixed a longstanding bug regarding fastcheck and daylight\n\
++ \032 saving time under Windows when Unison is set up to synchronize\n\
++ \032 modification times. (Modification times cannot be updated in\n\
++ \032 the archive in this case, so we have to ignore one hour\n\
++ \032 differences.)\n\
++ \032 + Fixed a bug that would occasionally cause the archives to be\n\
++ \032 left in non-identical states on the two hosts after\n\
++ \032 synchronization.\n\
++ \032 + Fixed a bug that prevented Unison from communicating correctly\n\
++ \032 between 32- and 64-bit architectures.\n\
++ \032 + On windows, file creation times are no longer used as a proxy\n\
++ \032 for inode numbers. (This is unfortunate, as it makes fastcheck\n\
++ \032 a little less safe. But it turns out that file creation times\n\
++ \032 are not reliable under Windows: if a file is removed and a new\n\
++ \032 file is created in its place, the new one will sometimes be\n\
++ \032 given the same creation date as the old one!)\n\
++ \032 + Set read-only file to R/W on OSX before attempting to change\n\
++ \032 other attributes.\n\
++ \032 + Fixed bug resulting in spurious \"Aborted\" errors during\n\
++ \032 transport (thanks to Jerome Vouillon)\n\
++ \032 + Enable diff if file contents have changed in one replica, but\n\
++ \032 only properties in the other.\n\
++ \032 + Removed misleading documentation for 'repeat' preference.\n\
++ \032 + Fixed a bug in merging code where Unison could sometimes\n\
++ \032 deadlock with the external merge program, if the latter\n\
++ \032 produced large amounts of output.\n\
++ \032 + Workaround for a bug compiling gtk2 user interface against\n\
++ \032 current versions of gtk2+ libraries.\n\
++ \032 + Added a better error message for \"ambiguous paths\".\n\
++ \032 + Squashed a longstanding bug that would cause file transfer to\n\
++ \032 fail with the message \"Failed: Error in readWrite: Is a\n\
++ \032 directory.\"\n\
++ \032 + Replaced symlinks with copies of their targets in the Growl\n\
++ \032 framework in src/uimac. This should make the sources easier to\n\
++ \032 check out from the svn repository on WinXP systems.\n\
++ \032 + Added a workaround (suggested by Karl M.) for the problem\n\
++ \032 discussed on the unison users mailing list where, on the\n\
++ \032 Windows platform, the server would hang when transferring\n\
++ \032 files. I conjecture that the problem has to do with the RPC\n\
++ \032 mechanism, which was used to make a call back from the server\n\
++ \032 to the client (inside the Trace.log function) so that the log\n\
++ \032 message would be appended to the log file on the client. The\n\
++ \032 workaround is to dump these messages (about when xferbycopying\n\
++ \032 shortcuts are applied and whether they succeed) just to the\n\
++ \032 standard output of the Unison process, not to the log file.\n\
++ \n\
++ \032 Changes since 2.13.0:\n\
++ \032 * The features for performing backups and for invoking external merge\n\
++ \032 programs have been completely rewritten by Stephane Lescuyer\n\
++ \032 (thanks, Stephane!). The user-visible functionality should not\n\
++ \032 change, but the internals have been rationalized and there are a\n\
++ \032 number of new features. See the manual (in particular, the\n\
++ \032 description of the backupXXX preferences) for details.\n\
++ \032 * Incorporated patches for ipv6 support, contributed by Samuel\n\
++ \032 Thibault. (Note that, due to a bug in the released OCaml 3.08.3\n\
++ \032 compiler, this code will not actually work with ipv6 unless\n\
++ \032 compiled with the CVS version of the OCaml compiler, where the bug\n\
++ \032 has been fixed; however, ipv4 should continue to work normally.)\n\
++ \032 * OSX interface:\n\
++ \032 + Incorporated Ben Willmore's cool new icon for the Mac UI.\n\
++ \032 * Small fixes:\n\
++ \032 + Fixed off by one error in month numbers (in printed dates)\n\
++ \032 reported by Bob Burger\n\
++ \n\
++ \032 Changes since 2.12.0:\n\
++ \032 * New convention for release numbering: Releases will continue to be\n\
++ \032 given numbers of the form X.Y.Z, but, from now on, just the major\n\
++ \032 version number (X.Y) will be considered significant when checking\n\
++ \032 compatibility between client and server versions. The third\n\
++ \032 component of the version number will be used only to identify\n\
++ \032 \"patch levels\" of releases.\n\
++ \032 This change goes hand in hand with a change to the procedure for\n\
++ \032 making new releases. Candidate releases will initially be given\n\
++ \032 \"beta release\" status when they are announced for public\n\
++ \032 consumption. Any bugs that are discovered will be fixed in a\n\
++ \032 separate branch of the source repository (without changing the\n\
++ \032 major version number) and new tarballs re-released as needed. When\n\
++ \032 this process converges, the patched beta version will be dubbed\n\
++ \032 stable.\n\
++ \032 * Warning (failure in batch mode) when one path is completely\n\
++ \032 emptied. This prevents Unison from deleting everything on one\n\
++ \032 replica when the other disappear.\n\
++ \032 * Fix diff bug (where no difference is shown the first time the diff\n\
++ \032 command is given).\n\
++ \032 * User interface changes:\n\
++ \032 + Improved workaround for button focus problem (GTK2 UI)\n\
++ \032 + Put leading zeroes in date fields\n\
++ \032 + More robust handling of character encodings in GTK2 UI\n\
++ \032 + Changed format of modification time displays, from modified at\n\
++ \032 hh:mm:ss on dd MMM, yyyy to modified on yyyy-mm-dd hh:mm:ss\n\
++ \032 + Changed time display to include seconds (so that people on FAT\n\
++ \032 filesystems will not be confused when Unison tries to update a\n\
++ \032 file time to an odd number of seconds and the filesystem\n\
++ \032 truncates it to an even number!)\n\
++ \032 + Use the diff \"-u\" option by default when showing differences\n\
++ \032 between files (the output is more readable)\n\
++ \032 + In text mode, pipe the diff output to a pager if the\n\
++ \032 environment variable PAGER is set\n\
++ \032 + Bug fixes and cleanups in ssh password prompting. Now works\n\
++ \032 with the GTK2 UI under Linux. (Hopefully the Mac OS X one is\n\
++ \032 not broken!)\n\
++ \032 + Include profile name in the GTK2 window name\n\
++ \032 + Added bindings ',' (same as '<') and '.' (same as '>') in the\n\
++ \032 GTK2 UI\n\
++ \032 * Mac GUI:\n\
++ \032 + actions like < and > scroll to the next item as necessary.\n\
++ \032 + Restart has a menu item and keyboard shortcut (command-R).\n\
++ \032 + Added a command-line tool for Mac OS X. It can be installed\n\
++ \032 from the Unison menu.\n\
++ \032 + New icon.\n\
++ \032 + Handle the \"help\" command-line argument properly.\n\
++ \032 + Handle profiles given on the command line properly.\n\
++ \032 + When a profile has been selected, the profile dialog is\n\
++ \032 replaced by a \"connecting\" message while the connection is\n\
++ \032 being made. This gives better feedback.\n\
++ \032 + Size of left and right columns is now large enough so that\n\
++ \032 \"PropsChanged\" is not cut off.\n\
++ \032 * Minor changes:\n\
++ \032 + Disable multi-threading when both roots are local\n\
++ \032 + Improved error handling code. In particular, make sure all\n\
++ \032 files are closed in case of a transient failure\n\
++ \032 + Under Windows, use $UNISON for home directory as a last resort\n\
++ \032 (it was wrongly moved before $HOME and $USERPROFILE in Unison\n\
++ \032 2.12.0)\n\
++ \032 + Reopen the logfile if its name changes (profile change)\n\
++ \032 + Double-check that permissions and modification times have been\n\
++ \032 properly set: there are some combination of OS and filesystem\n\
++ \032 on which setting them can fail in a silent way.\n\
++ \032 + Check for bad Windows filenames for pure Windows\n\
++ \032 synchronization also (not just cross architecture\n\
++ \032 synchronization). This way, filenames containing backslashes,\n\
++ \032 which are not correctly handled by unison, are rejected right\n\
++ \032 away.\n\
++ \032 + Attempt to resolve issues with synchronizing modification\n\
++ \032 times of read-only files under Windows\n\
++ \032 + Ignore chmod failures when deleting files\n\
++ \032 + Ignore trailing dots in filenames in case insensitive mode\n\
++ \032 + Proper quoting of paths, files and extensions ignored using\n\
++ \032 the UI\n\
++ \032 + The strings CURRENT1 and CURRENT2 are now correctly substitued\n\
++ \032 when they occur in the diff preference\n\
++ \032 + Improvements to syncing resource forks between Macs via a\n\
++ \032 non-Mac system.\n\
++ \n\
++ \032 Changes since 2.10.2:\n\
++ \032 * INCOMPATIBLE CHANGE: Archive format has changed.\n\
++ \032 * Source code availability: The Unison sources are now managed using\n\
++ \032 Subversion. One nice side-effect is that anonymous checkout is now\n\
++ \032 possible, like this:\n\
++ \032 svn co https://cvs.cis.upenn.edu:3690/svnroot/unison/\n\
++ \n\
++ \032 We will also continue to export a \"developer tarball\" of the\n\
++ \032 current (modulo one day) sources in the web export directory. To\n\
++ \032 receive commit logs for changes to the sources, subscribe to the\n\
++ \032 unison-hackers list\n\
++ \032 (http://www.cis.upenn.edu/ bcpierce/unison/lists.html).\n\
++ \032 * Text user interface:\n\
++ \032 + Substantial reworking of the internal logic of the text UI to\n\
++ \032 make it a bit easier to modify.\n\
++ \032 + The dumbtty flag in the text UI is automatically set to true\n\
++ \032 if the client is running on a Unix system and the EMACS\n\
++ \032 environment variable is set to anything other than the empty\n\
++ \032 string.\n\
++ \032 * Native OS X gui:\n\
++ \032 + Added a synchronize menu item with keyboard shortcut\n\
++ \032 + Added a merge menu item, still needs to be debugged\n\
++ \032 + Fixes to compile for Panther\n\
++ \032 + Miscellaneous improvements and bugfixes\n\
++ \032 * Small changes:\n\
++ \032 + Changed the filename checking code to apply to Windows only,\n\
++ \032 instead of OS X as well.\n\
++ \032 + Finder flags now synchronized\n\
++ \032 + Fallback in copy.ml for filesystem that do not support O_EXCL\n\
++ \032 + Changed buffer size for local file copy (was highly\n\
++ \032 inefficient with synchronous writes)\n\
++ \032 + Ignore chmod failure when deleting a directory\n\
++ \032 + Fixed assertion failure when resolving a conflict content\n\
++ \032 change / permission changes in favor of the content change.\n\
++ \032 + Workaround for transferring large files using rsync.\n\
++ \032 + Use buffered I/O for files (this is the only way to open files\n\
++ \032 in binary mode under Cygwin).\n\
++ \032 + On non-Cygwin Windows systems, the UNISON environment variable\n\
++ \032 is now checked first to determine where to look for Unison's\n\
++ \032 archive and preference files, followed by HOME and USERPROFILE\n\
++ \032 in that order. On Unix and Cygwin systems, HOME is used.\n\
++ \032 + Generalized diff preference so that it can be given either as\n\
++ \032 just the command name to be used for calculating diffs or else\n\
++ \032 a whole command line, containing the strings CURRENT1 and\n\
++ \032 CURRENT2, which will be replaced by the names of the files to\n\
++ \032 be diff'ed before the command is called.\n\
++ \032 + Recognize password prompts in some newer versions of ssh.\n\
++ \n\
++ \032 Changes since 2.9.20:\n\
++ \032 * INCOMPATIBLE CHANGE: Archive format has changed.\n\
++ \032 * Major functionality changes:\n\
++ \032 + Major tidying and enhancement of 'merge' functionality. The\n\
++ \032 main user-visible change is that the external merge program\n\
++ \032 may either write the merged output to a single new file, as\n\
++ \032 before, or it may modify one or both of its input files, or it\n\
++ \032 may write two new files. In the latter cases, its\n\
++ \032 modifications will be copied back into place on both the local\n\
++ \032 and the remote host, and (if the two files are now equal) the\n\
++ \032 archive will be updated appropriately. More information can be\n\
++ \032 found in the user manual. Thanks to Malo Denielou and Alan\n\
++ \032 Schmitt for these improvements.\n\
++ \032 Warning: the new merging functionality is not completely\n\
++ \032 compatible with old versions! Check the manual for details.\n\
++ \032 + Files larger than 2Gb are now supported.\n\
++ \032 + Added preliminary (and still somewhat experimental) support\n\
++ \032 for the Apple OS X operating system.\n\
++ \032 o Resource forks should be transferred correctly. (See the\n\
++ \032 manual for details of how this works when synchronizing\n\
++ \032 HFS with non-HFS volumes.) Synchronization of file type\n\
++ \032 and creator information is also supported.\n\
++ \032 o On OSX systems, the name of the directory for storing\n\
++ \032 Unison's archives, preference files, etc., is now\n\
++ \032 determined as follows:\n\
++ \032 # if ~/.unison exists, use it\n\
++ \032 # otherwise, use ~/Library/Application Support/Unison,\n\
++ \032 creating it if necessary.\n\
++ \032 o A preliminary native-Cocoa user interface is under\n\
++ \032 construction. This still needs some work, and some users\n\
++ \032 experience unpredictable crashes, so it is only for\n\
++ \032 hackers for now. Run make with UISTYLE=mac to build this\n\
++ \032 interface.\n\
++ \032 * Minor functionality changes:\n\
++ \032 + Added an ignorelocks preference, which forces Unison to\n\
++ \032 override left-over archive locks. (Setting this preference is\n\
++ \032 dangerous! Use it only if you are positive you know what you\n\
++ \032 are doing.)\n\
++ \032 + Added a new preference assumeContentsAreImmutable. If a\n\
++ \032 directory matches one of the patterns set in this preference,\n\
++ \032 then update detection is skipped for files in this directory.\n\
++ \032 (The purpose is to speed update detection for cases like Mail\n\
++ \032 folders, which contain lots and lots of immutable files.) Also\n\
++ \032 a preference assumeContentsAreImmutableNot, which overrides\n\
++ \032 the first, similarly to ignorenot. (Later amendment: these\n\
++ \032 preferences are now called immutable and immutablenot.)\n\
++ \032 + The ignorecase flag has been changed from a boolean to a\n\
++ \032 three-valued preference. The default setting, called default,\n\
++ \032 checks the operating systems running on the client and server\n\
++ \032 and ignores filename case if either of them is OSX or Windows.\n\
++ \032 Setting ignorecase to true or false overrides this behavior.\n\
++ \032 If you have been setting ignorecase on the command line using\n\
++ \032 -ignorecase=true or -ignorecase=false, you will need to change\n\
++ \032 to -ignorecase true or -ignorecase false.\n\
++ \032 + a new preference, 'repeat', for the text user interface\n\
++ \032 (only). If 'repeat' is set to a number, then, after it\n\
++ \032 finishes synchronizing, Unison will wait for that many seconds\n\
++ \032 and then start over, continuing this way until it is killed\n\
++ \032 from outside. Setting repeat to true will automatically set\n\
++ \032 the batch preference to true.\n\
++ \032 + Excel files are now handled specially, so that the fastcheck\n\
++ \032 optimization is skipped even if the fastcheck flag is set.\n\
++ \032 (Excel does some naughty things with modtimes, making this\n\
++ \032 optimization unreliable and leading to failures during change\n\
++ \032 propagation.)\n\
++ \032 + The ignorecase flag has been changed from a boolean to a\n\
++ \032 three-valued preference. The default setting, called\n\
++ \032 'default', checks the operating systems running on the client\n\
++ \032 and server and ignores filename case if either of them is OSX\n\
++ \032 or Windows. Setting ignorecase to 'true' or 'false' overrides\n\
++ \032 this behavior.\n\
++ \032 + Added a new preference, 'repeat', for the text user interface\n\
++ \032 (only, at the moment). If 'repeat' is set to a number, then,\n\
++ \032 after it finishes synchronizing, Unison will wait for that\n\
++ \032 many seconds and then start over, continuing this way until it\n\
++ \032 is killed from outside. Setting repeat to true will\n\
++ \032 automatically set the batch preference to true.\n\
++ \032 + The 'rshargs' preference has been split into 'rshargs' and\n\
++ \032 'sshargs' (mainly to make the documentation clearer). In fact,\n\
++ \032 'rshargs' is no longer mentioned in the documentation at all,\n\
++ \032 since pretty much everybody uses ssh now anyway.\n\
++ \032 * Documentation\n\
++ \032 + The web pages have been completely redesigned and reorganized.\n\
++ \032 (Thanks to Alan Schmitt for help with this.)\n\
++ \032 * User interface improvements\n\
++ \032 + Added a GTK2 user interface, capable (among other things) of\n\
++ \032 displaying filenames in any locale encoding. Kudos to Stephen\n\
++ \032 Tse for contributing this code!\n\
++ \032 + The text UI now prints a list of failed and skipped transfers\n\
++ \032 at the end of synchronization.\n\
++ \032 + Restarting update detection from the graphical UI will reload\n\
++ \032 the current profile (which in particular will reset the -path\n\
++ \032 preference, in case it has been narrowed by using the \"Recheck\n\
++ \032 unsynchronized items\" command).\n\
++ \032 + Several small improvements to the text user interface,\n\
++ \032 including a progress display.\n\
++ \032 * Bug fixes (too numerous to count, actually, but here are some):\n\
++ \032 + The maxthreads preference works now.\n\
++ \032 + Fixed bug where warning message about uname returning an\n\
++ \032 unrecognized result was preventing connection to server. (The\n\
++ \032 warning is no longer printed, and all systems where 'uname'\n\
++ \032 returns anything other than 'Darwin' are assumed not to be\n\
++ \032 running OS X.)\n\
++ \032 + Fixed a problem on OS X that caused some valid file names\n\
++ \032 (e.g., those including colons) to be considered invalid.\n\
++ \032 + Patched Path.followLink to follow links under cygwin in\n\
++ \032 addition to Unix (suggested by Matt Swift).\n\
++ \032 + Small change to the storeRootsName function, suggested by\n\
++ \032 bliviero at ichips.intel.com, to fix a problem in unison with\n\
++ \032 the `rootalias' option, which allows you to tell unison that\n\
++ \032 two roots contain the same files. Rootalias was being applied\n\
++ \032 after the hosts were sorted, so it wouldn't work properly in\n\
++ \032 all cases.\n\
++ \032 + Incorporated a fix by Dmitry Bely for setting utimes of\n\
++ \032 read-only files on Win32 systems.\n\
++ \032 * Installation / portability:\n\
++ \032 + Unison now compiles with OCaml version 3.07 and later out of\n\
++ \032 the box.\n\
++ \032 + Makefile.OCaml fixed to compile out of the box under OpenBSD.\n\
++ \032 + a few additional ports (e.g. OpenBSD, Zaurus/IPAQ) are now\n\
++ \032 mentioned in the documentation\n\
++ \032 + Unison can now be installed easily on OSX systems using the\n\
++ \032 Fink package manager\n\
++ \n\
++ \032 Changes since 2.9.1:\n\
++ \032 * Added a preference maxthreads that can be used to limit the number\n\
++ \032 of simultaneous file transfers.\n\
++ \032 * Added a backupdir preference, which controls where backup files are\n\
++ \032 stored.\n\
++ \032 * Basic support added for OSX. In particular, Unison now recognizes\n\
++ \032 when one of the hosts being synchronized is running OSX and\n\
++ \032 switches to a case-insensitive treatment of filenames (i.e., 'foo'\n\
++ \032 and 'FOO' are considered to be the same file). (OSX is not yet\n\
++ \032 fully working, however: in particular, files with resource forks\n\
++ \032 will not be synchronized correctly.)\n\
++ \032 * The same hash used to form the archive name is now also added to\n\
++ \032 the names of the temp files created during file transfer. The\n\
++ \032 reason for this is that, during update detection, we are going to\n\
++ \032 silently delete any old temp files that we find along the way, and\n\
++ \032 we want to prevent ourselves from deleting temp files belonging to\n\
++ \032 other instances of Unison that may be running in parallel, e.g.\n\
++ \032 synchronizing with a different host. Thanks to Ruslan Ermilov for\n\
++ \032 this suggestion.\n\
++ \032 * Several small user interface improvements\n\
++ \032 * Documentation\n\
++ \032 + FAQ and bug reporting instructions have been split out as\n\
++ \032 separate HTML pages, accessible directly from the unison web\n\
++ \032 page.\n\
++ \032 + Additions to FAQ, in particular suggestions about performance\n\
++ \032 tuning.\n\
++ \032 * Makefile\n\
++ \032 + Makefile.OCaml now sets UISTYLE=text or UISTYLE=gtk\n\
++ \032 automatically, depending on whether it finds lablgtk installed\n\
++ \032 + Unison should now compile \"out of the box\" under OSX\n\
++ \n\
++ \032 Changes since 2.8.1:\n\
++ \032 * Changing profile works again under Windows\n\
++ \032 * File movement optimization: Unison now tries to use local copy\n\
++ \032 instead of transfer for moved or copied files. It is controled by a\n\
++ \032 boolean option \"xferbycopying\".\n\
++ \032 * Network statistics window (transfer rate, amount of data\n\
++ \032 transferred). [NB: not available in Windows-Cygwin version.]\n\
++ \032 * symlinks work under the cygwin version (which is dynamically\n\
++ \032 linked).\n\
++ \032 * Fixed potential deadlock when synchronizing between Windows and\n\
++ \032 Unix\n\
++ \032 * Small improvements:\n\
++ \032 + If neither the USERPROFILE nor the HOME environment variables\n\
++ \032 are set, then Unison will put its temporary commit log (called\n\
++ \032 DANGER.README) into the directory named by the UNISON\n\
++ \032 environment variable, if any; otherwise it will use C:.\n\
++ \032 + alternative set of values for fastcheck: yes = true; no =\n\
++ \032 false; default = auto.\n\
++ \032 + -silent implies -contactquietly\n\
++ \032 * Source code:\n\
++ \032 + Code reorganization and tidying. (Started breaking up some of\n\
++ \032 the basic utility modules so that the non-unison-specific\n\
++ \032 stuff can be made available for other projects.)\n\
++ \032 + several Makefile and docs changes (for release);\n\
++ \032 + further comments in \"update.ml\";\n\
++ \032 + connection information is not stored in global variables\n\
++ \032 anymore.\n\
++ \n\
++ \032 Changes since 2.7.78:\n\
++ \032 * Small bugfix to textual user interface under Unix (to avoid leaving\n\
++ \032 the terminal in a bad state where it would not echo inputs after\n\
++ \032 Unison exited).\n\
++ \n\
++ \032 Changes since 2.7.39:\n\
++ \032 * Improvements to the main web page (stable and beta version docs are\n\
++ \032 now both accessible).\n\
++ \032 * User manual revised.\n\
++ \032 * Added some new preferences:\n\
++ \032 + \"sshcmd\" and \"rshcmd\" for specifying paths to ssh and rsh\n\
++ \032 programs.\n\
++ \032 + \"contactquietly\" for suppressing the \"contacting server\"\n\
++ \032 message during Unison startup (under the graphical UI).\n\
++ \032 * Bug fixes:\n\
++ \032 + Fixed small bug in UI that neglected to change the displayed\n\
++ \032 column headers if loading a new profile caused the roots to\n\
++ \032 change.\n\
++ \032 + Fixed a bug that would put the text UI into an infinite loop\n\
++ \032 if it encountered a conflict when run in batch mode.\n\
++ \032 + Added some code to try to fix the display of non-Ascii\n\
++ \032 characters in filenames on Windows systems in the GTK UI.\n\
++ \032 (This code is currently untested--if you're one of the people\n\
++ \032 that had reported problems with display of non-ascii\n\
++ \032 filenames, we'd appreciate knowing if this actually fixes\n\
++ \032 things.)\n\
++ \032 + `-prefer/-force newer' works properly now. (The bug was\n\
++ \032 reported by Sebastian Urbaniak and Sean Fulton.)\n\
++ \032 * User interface and Unison behavior:\n\
++ \032 + Renamed `Proceed' to `Go' in the graphical UI.\n\
++ \032 + Added exit status for the textual user interface.\n\
++ \032 + Paths that are not synchronized because of conflicts or errors\n\
++ \032 during update detection are now noted in the log file.\n\
++ \032 + [END] messages in log now use a briefer format\n\
++ \032 + Changed the text UI startup sequence so that ./unison -ui text\n\
++ \032 will use the default profile instead of failing.\n\
++ \032 + Made some improvements to the error messages.\n\
++ \032 + Added some debugging messages to remote.ml.\n\
++ \n\
++ \032 Changes since 2.7.7:\n\
++ \032 * Incorporated, once again, a multi-threaded transport sub-system. It\n\
++ \032 transfers several files at the same time, thereby making much more\n\
++ \032 effective use of available network bandwidth. Unlike the earlier\n\
++ \032 attempt, this time we do not rely on the native thread library of\n\
++ \032 OCaml. Instead, we implement a light-weight, non-preemptive\n\
++ \032 multi-thread library in OCaml directly. This version appears\n\
++ \032 stable.\n\
++ \032 Some adjustments to unison are made to accommodate the\n\
++ \032 multi-threaded version. These include, in particular, changes to\n\
++ \032 the user interface and logging, for example:\n\
++ \032 + Two log entries for each transferring task, one for the\n\
++ \032 beginning, one for the end.\n\
++ \032 + Suppressed warning messages against removing temp files left\n\
++ \032 by a previous unison run, because warning does not work nicely\n\
++ \032 under multi-threading. The temp file names are made less\n\
++ \032 likely to coincide with the name of a file created by the\n\
++ \032 user. They take the form\n\
++ \032 .#<filename>.<serial>.unison.tmp. [N.b. This was later changed\n\
++ \032 to .unison.<filename>.<serial>.unison.tmp.]\n\
++ \032 * Added a new command to the GTK user interface: pressing 'f' causes\n\
++ \032 Unison to start a new update detection phase, using as paths just\n\
++ \032 those paths that have been detected as changed and not yet marked\n\
++ \032 as successfully completed. Use this command to quickly restart\n\
++ \032 Unison on just the set of paths still needing attention after a\n\
++ \032 previous run.\n\
++ \032 * Made the ignorecase preference user-visible, and changed the\n\
++ \032 initialization code so that it can be manually set to true, even if\n\
++ \032 neither host is running Windows. (This may be useful, e.g., when\n\
++ \032 using Unison running on a Unix system with a FAT volume mounted.)\n\
++ \032 * Small improvements and bug fixes:\n\
++ \032 + Errors in preference files now generate fatal errors rather\n\
++ \032 than warnings at startup time. (I.e., you can't go on from\n\
++ \032 them.) Also, we fixed a bug that was preventing these warnings\n\
++ \032 from appearing in the text UI, so some users who have been\n\
++ \032 running (unsuspectingly) with garbage in their prefs files may\n\
++ \032 now get error reports.\n\
++ \032 + Error reporting for preference files now provides file name\n\
++ \032 and line number.\n\
++ \032 + More intelligible message in the case of identical change to\n\
++ \032 the same files: \"Nothing to do: replicas have been changed\n\
++ \032 only in identical ways since last sync.\"\n\
++ \032 + Files with prefix '.#' excluded when scanning for preference\n\
++ \032 files.\n\
++ \032 + Rsync instructions are send directly instead of first\n\
++ \032 marshaled.\n\
++ \032 + Won't try forever to get the fingerprint of a continuously\n\
++ \032 changing file: unison will give up after certain number of\n\
++ \032 retries.\n\
++ \032 + Other bug fixes, including the one reported by Peter Selinger\n\
++ \032 (force=older preference not working).\n\
++ \032 * Compilation:\n\
++ \032 + Upgraded to the new OCaml 3.04 compiler, with the LablGtk\n\
++ \032 1.2.3 library (patched version used for compiling under\n\
++ \032 Windows).\n\
++ \032 + Added the option to compile unison on the Windows platform\n\
++ \032 with Cygwin GNU C compiler. This option only supports building\n\
++ \032 dynamically linked unison executables.\n\
++ \n\
++ \032 Changes since 2.7.4:\n\
++ \032 * Fixed a silly (but debilitating) bug in the client startup\n\
++ \032 sequence.\n\
++ \n\
++ \032 Changes since 2.7.1:\n\
++ \032 * Added addprefsto preference, which (when set) controls which\n\
++ \032 preference file new preferences (e.g. new ignore patterns) are\n\
++ \032 added to.\n\
++ \032 * Bug fix: read the initial connection header one byte at a time, so\n\
++ \032 that we don't block if the header is shorter than expected. (This\n\
++ \032 bug did not affect normal operation -- it just made it hard to tell\n\
++ \032 when you were trying to use Unison incorrectly with an old version\n\
++ \032 of the server, since it would hang instead of giving an error\n\
++ \032 message.)\n\
++ \n\
++ \032 Changes since 2.6.59:\n\
++ \032 * Changed fastcheck from a boolean to a string preference. Its legal\n\
++ \032 values are yes (for a fast check), no (for a safe check), or\n\
++ \032 default (for a fast check--which also happens to be safe--when\n\
++ \032 running on Unix and a safe check when on Windows). The default is\n\
++ \032 default.\n\
++ \032 * Several preferences have been renamed for consistency. All\n\
++ \032 preference names are now spelled out in lowercase. For backward\n\
++ \032 compatibility, the old names still work, but they are not mentioned\n\
++ \032 in the manual any more.\n\
++ \032 * The temp files created by the 'diff' and 'merge' commands are now\n\
++ \032 named by prepending a new prefix to the file name, rather than\n\
++ \032 appending a suffix. This should avoid confusing diff/merge programs\n\
++ \032 that depend on the suffix to guess the type of the file contents.\n\
++ \032 * We now set the keepalive option on the server socket, to make sure\n\
++ \032 that the server times out if the communication link is unexpectedly\n\
++ \032 broken.\n\
++ \032 * Bug fixes:\n\
++ \032 + When updating small files, Unison now closes the destination\n\
++ \032 file.\n\
++ \032 + File permissions are properly updated when the file is behind\n\
++ \032 a followed link.\n\
++ \032 + Several other small fixes.\n\
++ \n\
++ \032 Changes since 2.6.38:\n\
++ \032 * Major Windows performance improvement!\n\
++ \032 We've added a preference fastcheck that makes Unison look only at a\n\
++ \032 file's creation time and last-modified time to check whether it has\n\
++ \032 changed. This should result in a huge speedup when checking for\n\
++ \032 updates in large replicas.\n\
++ \032 When this switch is set, Unison will use file creation times as\n\
++ \032 'pseudo inode numbers' when scanning Windows replicas for updates,\n\
++ \032 instead of reading the full contents of every file. This may cause\n\
++ \032 Unison to miss propagating an update if the create time,\n\
++ \032 modification time, and length of the file are all unchanged by the\n\
++ \032 update (this is not easy to achieve, but it can be done). However,\n\
++ \032 Unison will never overwrite such an update with a change from the\n\
++ \032 other replica, since it always does a safe check for updates just\n\
++ \032 before propagating a change. Thus, it is reasonable to use this\n\
++ \032 switch most of the time and occasionally run Unison once with\n\
++ \032 fastcheck set to false, if you are worried that Unison may have\n\
++ \032 overlooked an update.\n\
++ \032 Warning: This change is has not yet been thoroughly field-tested.\n\
++ \032 If you set the fastcheck preference, pay careful attention to what\n\
++ \032 Unison is doing.\n\
++ \032 * New functionality: centralized backups and merging\n\
++ \032 + This version incorporates two pieces of major new\n\
++ \032 functionality, implemented by Sylvain Roy during a summer\n\
++ \032 internship at Penn: a centralized backup facility that keeps a\n\
++ \032 full backup of (selected files in) each replica, and a merging\n\
++ \032 feature that allows Unison to invoke an external file-merging\n\
++ \032 tool to resolve conflicting changes to individual files.\n\
++ \032 + Centralized backups:\n\
++ \032 o Unison now maintains full backups of the\n\
++ \032 last-synchronized versions of (some of) the files in each\n\
++ \032 replica; these function both as backups in the usual\n\
++ \032 sense and as the \"common version\" when invoking external\n\
++ \032 merge programs.\n\
++ \032 o The backed up files are stored in a directory\n\
++ \032 /.unison/backup on each host. (The name of this directory\n\
++ \032 can be changed by setting the environment variable\n\
++ \032 UNISONBACKUPDIR.)\n\
++ \032 o The predicate backup controls which files are actually\n\
++ \032 backed up: giving the preference 'backup = Path *' causes\n\
++ \032 backing up of all files.\n\
++ \032 o Files are added to the backup directory whenever unison\n\
++ \032 updates its archive. This means that\n\
++ \032 # When unison reconstructs its archive from scratch\n\
++ \032 (e.g., because of an upgrade, or because the archive\n\
++ \032 files have been manually deleted), all files will be\n\
++ \032 backed up.\n\
++ \032 # Otherwise, each file will be backed up the first\n\
++ \032 time unison propagates an update for it.\n\
++ \032 o The preference backupversions controls how many previous\n\
++ \032 versions of each file are kept. The default is 2 (i.e.,\n\
++ \032 the last synchronized version plus one backup).\n\
++ \032 o For backward compatibility, the backups preference is\n\
++ \032 also still supported, but backup is now preferred.\n\
++ \032 o It is OK to manually delete files from the backup\n\
++ \032 directory (or to throw away the directory itself). Before\n\
++ \032 unison uses any of these files for anything important, it\n\
++ \032 checks that its fingerprint matches the one that it\n\
++ \032 expects.\n\
++ \032 + Merging:\n\
++ \032 o Both user interfaces offer a new 'merge' command, invoked\n\
++ \032 by pressing 'm' (with a changed file selected).\n\
++ \032 o The actual merging is performed by an external program.\n\
++ \032 The preferences merge and merge2 control how this program\n\
++ \032 is invoked. If a backup exists for this file (see the\n\
++ \032 backup preference), then the merge preference is used for\n\
++ \032 this purpose; otherwise merge2 is used. In both cases,\n\
++ \032 the value of the preference should be a string\n\
++ \032 representing the command that should be passed to a shell\n\
++ \032 to invoke the merge program. Within this string, the\n\
++ \032 special substrings CURRENT1, CURRENT2, NEW, and OLD may\n\
++ \032 appear at any point. Unison will substitute these as\n\
++ \032 follows before invoking the command:\n\
++ \032 # CURRENT1 is replaced by the name of the local copy\n\
++ \032 of the file;\n\
++ \032 # CURRENT2 is replaced by the name of a temporary\n\
++ \032 file, into which the contents of the remote copy of\n\
++ \032 the file have been transferred by Unison prior to\n\
++ \032 performing the merge;\n\
++ \032 # NEW is replaced by the name of a temporary file that\n\
++ \032 Unison expects to be written by the merge program\n\
++ \032 when it finishes, giving the desired new contents of\n\
++ \032 the file; and\n\
++ \032 # OLD is replaced by the name of the backed up copy of\n\
++ \032 the original version of the file (i.e., its state at\n\
++ \032 the end of the last successful run of Unison), if\n\
++ \032 one exists (applies only to merge, not merge2).\n\
++ \032 For example, on Unix systems setting the merge preference\n\
++ \032 to\n\
++ \032 merge = diff3 -m CURRENT1 OLD CURRENT2 > NEW\n\
++ \n\
++ \032 will tell Unison to use the external diff3 program for\n\
++ \032 merging.\n\
++ \032 A large number of external merging programs are\n\
++ \032 available. For example, emacs users may find the\n\
++ \032 following convenient:\n\
++ \032 merge2 = emacs -q --eval '(ediff-merge-files \"CURRENT1\" \"CURRENT2\"\n\
++ \032 nil \"NEW\")'\n\
++ \032 merge = emacs -q --eval '(ediff-merge-files-with-ancestor\n\
++ \032 \"CURRENT1\" \"CURRENT2\" \"OLD\" nil \"NEW\")'\n\
++ \n\
++ \032 (These commands are displayed here on two lines to avoid\n\
++ \032 running off the edge of the page. In your preference\n\
++ \032 file, each should be written on a single line.)\n\
++ \032 o If the external program exits without leaving any file at\n\
++ \032 the path NEW, Unison considers the merge to have failed.\n\
++ \032 If the merge program writes a file called NEW but exits\n\
++ \032 with a non-zero status code, then Unison considers the\n\
++ \032 merge to have succeeded but to have generated conflicts.\n\
++ \032 In this case, it attempts to invoke an external editor so\n\
++ \032 that the user can resolve the conflicts. The value of the\n\
++ \032 editor preference controls what editor is invoked by\n\
++ \032 Unison. The default is emacs.\n\
++ \032 o Please send us suggestions for other useful values of the\n\
++ \032 merge2 and merge preferences - we'd like to give several\n\
++ \032 examples in the manual.\n\
++ \032 * Smaller changes:\n\
++ \032 + When one preference file includes another, unison no longer\n\
++ \032 adds the suffix '.prf' to the included file by default. If a\n\
++ \032 file with precisely the given name exists in the .unison\n\
++ \032 directory, it will be used; otherwise Unison will add .prf, as\n\
++ \032 it did before. (This change means that included preference\n\
++ \032 files can be named blah.include instead of blah.prf, so that\n\
++ \032 unison will not offer them in its 'choose a preference file'\n\
++ \032 dialog.)\n\
++ \032 + For Linux systems, we now offer both a statically linked and a\n\
++ \032 dynamically linked executable. The static one is larger, but\n\
++ \032 will probably run on more systems, since it doesn't depend on\n\
++ \032 the same versions of dynamically linked library modules being\n\
++ \032 available.\n\
++ \032 + Fixed the force and prefer preferences, which were getting the\n\
++ \032 propagation direction exactly backwards.\n\
++ \032 + Fixed a bug in the startup code that would cause unison to\n\
++ \032 crash when the default profile (~/.unison/default.prf) does\n\
++ \032 not exist.\n\
++ \032 + Fixed a bug where, on the run when a profile is first created,\n\
++ \032 Unison would confusingly display the roots in reverse order in\n\
++ \032 the user interface.\n\
++ \032 * For developers:\n\
++ \032 + We've added a module dependency diagram to the source\n\
++ \032 distribution, in src/DEPENDENCIES.ps, to help new prospective\n\
++ \032 developers with navigating the code.\n\
++ \n\
++ \032 Changes since 2.6.11:\n\
++ \032 * INCOMPATIBLE CHANGE: Archive format has changed.\n\
++ \032 * INCOMPATIBLE CHANGE: The startup sequence has been completely\n\
++ \032 rewritten and greatly simplified. The main user-visible change is\n\
++ \032 that the defaultpath preference has been removed. Its effect can be\n\
++ \032 approximated by using multiple profiles, with include directives to\n\
++ \032 incorporate common settings. All uses of defaultpath in existing\n\
++ \032 profiles should be changed to path.\n\
++ \032 Another change in startup behavior that will affect some users is\n\
++ \032 that it is no longer possible to specify roots both in the profile\n\
++ \032 and on the command line.\n\
++ \032 You can achieve a similar effect, though, by breaking your profile\n\
++ \032 into two:\n\
++ \n\
++ \032 default.prf =\n\
++ \032 root = blah\n\
++ \032 root = foo\n\
++ \032 include common\n\
++ \n\
++ \032 common.prf =\n\
++ \032 <everything else>\n\
++ \n\
++ \032 Now do\n\
++ \032 unison common root1 root2\n\
++ \n\
++ \032 when you want to specify roots explicitly.\n\
++ \032 * The -prefer and -force options have been extended to allow users to\n\
++ \032 specify that files with more recent modtimes should be propagated,\n\
++ \032 writing either -prefer newer or -force newer. (For symmetry, Unison\n\
++ \032 will also accept -prefer older or -force older.) The -force\n\
++ \032 older/newer options can only be used when -times is also set.\n\
++ \032 The graphical user interface provides access to these facilities on\n\
++ \032 a one-off basis via the Actions menu.\n\
++ \032 * Names of roots can now be \"aliased\" to allow replicas to be\n\
++ \032 relocated without changing the name of the archive file where\n\
++ \032 Unison stores information between runs. (This feature is for\n\
++ \032 experts only. See the \"Archive Files\" section of the manual for\n\
++ \032 more information.)\n\
++ \032 * Graphical user-interface:\n\
++ \032 + A new command is provided in the Synchronization menu for\n\
++ \032 switching to a new profile without restarting Unison from\n\
++ \032 scratch.\n\
++ \032 + The GUI also supports one-key shortcuts for commonly used\n\
++ \032 profiles. If a profile contains a preference of the form 'key\n\
++ \032 = n', where n is a single digit, then pressing this key will\n\
++ \032 cause Unison to immediately switch to this profile and begin\n\
++ \032 synchronization again from scratch. (Any actions that may have\n\
++ \032 been selected for a set of changes currently being displayed\n\
++ \032 will be discarded.)\n\
++ \032 + Each profile may include a preference 'label = <string>'\n\
++ \032 giving a descriptive string that described the options\n\
++ \032 selected in this profile. The string is listed along with the\n\
++ \032 profile name in the profile selection dialog, and displayed in\n\
++ \032 the top-right corner of the main Unison window.\n\
++ \032 * Minor:\n\
++ \032 + Fixed a bug that would sometimes cause the 'diff' display to\n\
++ \032 order the files backwards relative to the main user interface.\n\
++ \032 (Thanks to Pascal Brisset for this fix.)\n\
++ \032 + On Unix systems, the graphical version of Unison will check\n\
++ \032 the DISPLAY variable and, if it is not set, automatically fall\n\
++ \032 back to the textual user interface.\n\
++ \032 + Synchronization paths (path preferences) are now matched\n\
++ \032 against the ignore preferences. So if a path is both specified\n\
++ \032 in a path preference and ignored, it will be skipped.\n\
++ \032 + Numerous other bugfixes and small improvements.\n\
++ \n\
++ \032 Changes since 2.6.1:\n\
++ \032 * The synchronization of modification times has been disabled for\n\
++ \032 directories.\n\
++ \032 * Preference files may now include lines of the form include <name>,\n\
++ \032 which will cause name.prf to be read at that point.\n\
++ \032 * The synchronization of permission between Windows and Unix now\n\
++ \032 works properly.\n\
++ \032 * A binding CYGWIN=binmode in now added to the environment so that\n\
++ \032 the Cygwin port of OpenSSH works properly in a non-Cygwin context.\n\
++ \032 * The servercmd and addversionno preferences can now be used\n\
++ \032 together: -addversionno appends an appropriate -NNN to the server\n\
++ \032 command, which is found by using the value of the -servercmd\n\
++ \032 preference if there is one, or else just unison.\n\
++ \032 * Both '-pref=val' and '-pref val' are now allowed for boolean\n\
++ \032 values. (The former can be used to set a preference to false.)\n\
++ \032 * Lot of small bugs fixed.\n\
++ \n\
++ \032 Changes since 2.5.31:\n\
++ \032 * The log preference is now set to true by default, since the log\n\
++ \032 file seems useful for most users.\n\
++ \032 * Several miscellaneous bugfixes (most involving symlinks).\n\
++ \n\
++ \032 Changes since 2.5.25:\n\
++ \032 * INCOMPATIBLE CHANGE: Archive format has changed (again).\n\
++ \032 * Several significant bugs introduced in 2.5.25 have been fixed.\n\
++ \n\
++ \032 Changes since 2.5.1:\n\
++ \032 * INCOMPATIBLE CHANGE: Archive format has changed. Make sure you\n\
++ \032 synchronize your replicas before upgrading, to avoid spurious\n\
++ \032 conflicts. The first sync after upgrading will be slow.\n\
++ \032 * New functionality:\n\
++ \032 + Unison now synchronizes file modtimes, user-ids, and\n\
++ \032 group-ids.\n\
++ \032 These new features are controlled by a set of new preferences,\n\
++ \032 all of which are currently false by default.\n\
++ \032 o When the times preference is set to true, file\n\
++ \032 modification times are propaged. (Because the\n\
++ \032 representations of time may not have the same granularity\n\
++ \032 on both replicas, Unison may not always be able to make\n\
++ \032 the modtimes precisely equal, but it will get them as\n\
++ \032 close as the operating systems involved allow.)\n\
++ \032 o When the owner preference is set to true, file ownership\n\
++ \032 information is synchronized.\n\
++ \032 o When the group preference is set to true, group\n\
++ \032 information is synchronized.\n\
++ \032 o When the numericIds preference is set to true, owner and\n\
++ \032 group information is synchronized numerically. By\n\
++ \032 default, owner and group numbers are converted to names\n\
++ \032 on each replica and these names are synchronized. (The\n\
++ \032 special user id 0 and the special group 0 are never\n\
++ \032 mapped via user/group names even if this preference is\n\
++ \032 not set.)\n\
++ \032 + Added an integer-valued preference perms that can be used to\n\
++ \032 control the propagation of permission bits. The value of this\n\
++ \032 preference is a mask indicating which permission bits should\n\
++ \032 be synchronized. It is set by default to 0o1777: all bits but\n\
++ \032 the set-uid and set-gid bits are synchronised (synchronizing\n\
++ \032 theses latter bits can be a security hazard). If you want to\n\
++ \032 synchronize all bits, you can set the value of this preference\n\
++ \032 to -1.\n\
++ \032 + Added a log preference (default false), which makes Unison\n\
++ \032 keep a complete record of the changes it makes to the\n\
++ \032 replicas. By default, this record is written to a file called\n\
++ \032 unison.log in the user's home directory (the value of the HOME\n\
++ \032 environment variable). If you want it someplace else, set the\n\
++ \032 logfile preference to the full pathname you want Unison to\n\
++ \032 use.\n\
++ \032 + Added an ignorenot preference that maintains a set of patterns\n\
++ \032 for paths that should definitely not be ignored, whether or\n\
++ \032 not they match an ignore pattern. (That is, a path will now be\n\
++ \032 ignored iff it matches an ignore pattern and does not match\n\
++ \032 any ignorenot patterns.)\n\
++ \032 * User-interface improvements:\n\
++ \032 + Roots are now displayed in the user interface in the same\n\
++ \032 order as they were given on the command line or in the\n\
++ \032 preferences file.\n\
++ \032 + When the batch preference is set, the graphical user interface\n\
++ \032 no longer waits for user confirmation when it displays a\n\
++ \032 warning message: it simply pops up an advisory window with a\n\
++ \032 Dismiss button at the bottom and keeps on going.\n\
++ \032 + Added a new preference for controlling how many status\n\
++ \032 messages are printed during update detection: statusdepth\n\
++ \032 controls the maximum depth for paths on the local machine\n\
++ \032 (longer paths are not displayed, nor are non-directory paths).\n\
++ \032 The value should be an integer; default is 1.\n\
++ \032 + Removed the trace and silent preferences. They did not seem\n\
++ \032 very useful, and there were too many preferences for\n\
++ \032 controlling output in various ways.\n\
++ \032 + The text UI now displays just the default command (the one\n\
++ \032 that will be used if the user just types <return>) instead of\n\
++ \032 all available commands. Typing ? will print the full list of\n\
++ \032 possibilities.\n\
++ \032 + The function that finds the canonical hostname of the local\n\
++ \032 host (which is used, for example, in calculating the name of\n\
++ \032 the archive file used to remember which files have been\n\
++ \032 synchronized) normally uses the gethostname operating system\n\
++ \032 call. However, if the environment variable UNISONLOCALHOSTNAME\n\
++ \032 is set, its value will now be used instead. This makes it\n\
++ \032 easier to use Unison in situations where a machine's name\n\
++ \032 changes frequently (e.g., because it is a laptop and gets\n\
++ \032 moved around a lot).\n\
++ \032 + File owner and group are now displayed in the \"detail window\"\n\
++ \032 at the bottom of the screen, when unison is configured to\n\
++ \032 synchronize them.\n\
++ \032 * For hackers:\n\
++ \032 + Updated to Jacques Garrigue's new version of lablgtk, which\n\
++ \032 means we can throw away our local patched version.\n\
++ \032 If you're compiling the GTK version of unison from sources,\n\
++ \032 you'll need to update your copy of lablgtk to the developers\n\
++ \032 release. (Warning: installing lablgtk under Windows is\n\
++ \032 currently a bit challenging.)\n\
++ \032 + The TODO.txt file (in the source distribution) has been\n\
++ \032 cleaned up and reorganized. The list of pending tasks should\n\
++ \032 be much easier to make sense of, for people that may want to\n\
++ \032 contribute their programming energies. There is also a\n\
++ \032 separate file BUGS.txt for open bugs.\n\
++ \032 + The Tk user interface has been removed (it was not being\n\
++ \032 maintained and no longer compiles).\n\
++ \032 + The debug preference now prints quite a bit of additional\n\
++ \032 information that should be useful for identifying sources of\n\
++ \032 problems.\n\
++ \032 + The version number of the remote server is now checked right\n\
++ \032 away during the connection setup handshake, rather than later.\n\
++ \032 (Somebody sent a bug report of a server crash that turned out\n\
++ \032 to come from using inconsistent versions: better to check this\n\
++ \032 earlier and in a way that can't crash either client or\n\
++ \032 server.)\n\
++ \032 + Unison now runs correctly on 64-bit architectures (e.g. Alpha\n\
++ \032 linux). We will not be distributing binaries for these\n\
++ \032 architectures ourselves (at least for a while) but if someone\n\
++ \032 would like to make them available, we'll be glad to provide a\n\
++ \032 link to them.\n\
++ \032 * Bug fixes:\n\
++ \032 + Pattern matching (e.g. for ignore) is now case-insensitive\n\
++ \032 when Unison is in case-insensitive mode (i.e., when one of the\n\
++ \032 replicas is on a windows machine).\n\
++ \032 + Some people had trouble with mysterious failures during\n\
++ \032 propagation of updates, where files would be falsely reported\n\
++ \032 as having changed during synchronization. This should be\n\
++ \032 fixed.\n\
++ \032 + Numerous smaller fixes.\n\
++ \n\
++ \032 Changes since 2.4.1:\n\
++ \032 * Added a number of 'sorting modes' for the user interface. By\n\
++ \032 default, conflicting changes are displayed at the top, and the rest\n\
++ \032 of the entries are sorted in alphabetical order. This behavior can\n\
++ \032 be changed in the following ways:\n\
++ \032 + Setting the sortnewfirst preference to true causes newly\n\
++ \032 created files to be displayed before changed files.\n\
++ \032 + Setting sortbysize causes files to be displayed in increasing\n\
++ \032 order of size.\n\
++ \032 + Giving the preference sortfirst=<pattern> (where <pattern> is\n\
++ \032 a path descriptor in the same format as 'ignore' and 'follow'\n\
++ \032 patterns, causes paths matching this pattern to be displayed\n\
++ \032 first.\n\
++ \032 + Similarly, giving the preference sortlast=<pattern> causes\n\
++ \032 paths matching this pattern to be displayed last.\n\
++ \032 The sorting preferences are described in more detail in the user\n\
++ \032 manual. The sortnewfirst and sortbysize flags can also be accessed\n\
++ \032 from the 'Sort' menu in the grpahical user interface.\n\
++ \032 * Added two new preferences that can be used to change unison's\n\
++ \032 fundamental behavior to make it more like a mirroring tool instead\n\
++ \032 of a synchronizer.\n\
++ \032 + Giving the preference prefer with argument <root> (by adding\n\
++ \032 -prefer <root> to the command line or prefer=<root>) to your\n\
++ \032 profile) means that, if there is a conflict, the contents of\n\
++ \032 <root> should be propagated to the other replica (with no\n\
++ \032 questions asked). Non-conflicting changes are treated as\n\
++ \032 usual.\n\
++ \032 + Giving the preference force with argument <root> will make\n\
++ \032 unison resolve all differences in favor of the given root,\n\
++ \032 even if it was the other replica that was changed.\n\
++ \032 These options should be used with care! (More information is\n\
++ \032 available in the manual.)\n\
++ \032 * Small changes:\n\
++ \032 + Changed default answer to 'Yes' in all two-button dialogs in\n\
++ \032 the graphical interface (this seems more intuitive).\n\
++ \032 + The rsync preference has been removed (it was used to activate\n\
++ \032 rsync compression for file transfers, but rsync compression is\n\
++ \032 now enabled by default).\n\
++ \032 + In the text user interface, the arrows indicating which\n\
++ \032 direction changes are being propagated are printed differently\n\
++ \032 when the user has overridded Unison's default recommendation\n\
++ \032 (====> instead of ---->). This matches the behavior of the\n\
++ \032 graphical interface, which displays such arrows in a different\n\
++ \032 color.\n\
++ \032 + Carriage returns (Control-M's) are ignored at the ends of\n\
++ \032 lines in profiles, for Windows compatibility.\n\
++ \032 + All preferences are now fully documented in the user manual.\n\
++ \n\
++ \032 Changes since 2.3.12:\n\
++ \032 * INCOMPATIBLE CHANGE: Archive format has changed. Make sure you\n\
++ \032 synchronize your replicas before upgrading, to avoid spurious\n\
++ \032 conflicts. The first sync after upgrading will be slow.\n\
++ \032 * New/improved functionality:\n\
++ \032 + A new preference -sortbysize controls the order in which\n\
++ \032 changes are displayed to the user: when it is set to true, the\n\
++ \032 smallest changed files are displayed first. (The default\n\
++ \032 setting is false.)\n\
++ \032 + A new preference -sortnewfirst causes newly created files to\n\
++ \032 be listed before other updates in the user interface.\n\
++ \032 + We now allow the ssh protocol to specify a port.\n\
++ \032 + Incompatible change: The unison: protocol is deprecated, and\n\
++ \032 we added file: and socket:. You may have to modify your\n\
++ \032 profiles in the .unison directory. If a replica is specified\n\
++ \032 without an explicit protocol, we now assume it refers to a\n\
++ \032 file. (Previously \"//saul/foo\" meant to use SSH to connect to\n\
++ \032 saul, then access the foo directory. Now it means to access\n\
++ \032 saul via a remote file mechanism such as samba; the old effect\n\
++ \032 is now achieved by writing ssh://saul/foo.)\n\
++ \032 + Changed the startup sequence for the case where roots are\n\
++ \032 given but no profile is given on the command line. The new\n\
++ \032 behavior is to use the default profile (creating it if it does\n\
++ \032 not exist), and temporarily override its roots. The manual\n\
++ \032 claimed that this case would work by reading no profile at\n\
++ \032 all, but AFAIK this was never true.\n\
++ \032 + In all user interfaces, files with conflicts are always listed\n\
++ \032 first\n\
++ \032 + A new preference 'sshversion' can be used to control which\n\
++ \032 version of ssh should be used to connect to the server. Legal\n\
++ \032 values are 1 and 2. (Default is empty, which will make unison\n\
++ \032 use whatever version of ssh is installed as the default 'ssh'\n\
++ \032 command.)\n\
++ \032 + The situation when the permissions of a file was updated the\n\
++ \032 same on both side is now handled correctly (we used to report\n\
++ \032 a spurious conflict)\n\
++ \032 * Improvements for the Windows version:\n\
++ \032 + The fact that filenames are treated case-insensitively under\n\
++ \032 Windows should now be handled correctly. The exact behavior is\n\
++ \032 described in the cross-platform section of the manual.\n\
++ \032 + It should be possible to synchronize with Windows shares,\n\
++ \032 e.g., //host/drive/path.\n\
++ \032 + Workarounds to the bug in syncing root directories in Windows.\n\
++ \032 The most difficult thing to fix is an ocaml bug: Unix.opendir\n\
++ \032 fails on c: in some versions of Windows.\n\
++ \032 * Improvements to the GTK user interface (the Tk interface is no\n\
++ \032 longer being maintained):\n\
++ \032 + The UI now displays actions differently (in blue) when they\n\
++ \032 have been explicitly changed by the user from Unison's default\n\
++ \032 recommendation.\n\
++ \032 + More colorful appearance.\n\
++ \032 + The initial profile selection window works better.\n\
++ \032 + If any transfers failed, a message to this effect is displayed\n\
++ \032 along with 'Synchronization complete' at the end of the\n\
++ \032 transfer phase (in case they may have scrolled off the top).\n\
++ \032 + Added a global progress meter, displaying the percentage of\n\
++ \032 total bytes that have been transferred so far.\n\
++ \032 * Improvements to the text user interface:\n\
++ \032 + The file details will be displayed automatically when a\n\
++ \032 conflict is been detected.\n\
++ \032 + when a warning is generated (e.g. for a temporary file left\n\
++ \032 over from a previous run of unison) Unison will no longer wait\n\
++ \032 for a response if it is running in -batch mode.\n\
++ \032 + The UI now displays a short list of possible inputs each time\n\
++ \032 it waits for user interaction.\n\
++ \032 + The UI now quits immediately (rather than looping back and\n\
++ \032 starting the interaction again) if the user presses 'q' when\n\
++ \032 asked whether to propagate changes.\n\
++ \032 + Pressing 'g' in the text user interface will proceed\n\
++ \032 immediately with propagating updates, without asking any more\n\
++ \032 questions.\n\
++ \032 * Documentation and installation changes:\n\
++ \032 + The manual now includes a FAQ, plus sections on common\n\
++ \032 problems and on tricks contributed by users.\n\
++ \032 + Both the download page and the download directory explicitly\n\
++ \032 say what are the current stable and beta-test version numbers.\n\
++ \032 + The OCaml sources for the up-to-the-minute developers' version\n\
++ \032 (not guaranteed to be stable, or even to compile, at any given\n\
++ \032 time!) are now available from the download page.\n\
++ \032 + Added a subsection to the manual describing cross-platform\n\
++ \032 issues (case conflicts, illegal filenames)\n\
++ \032 * Many small bug fixes and random improvements.\n\
++ \n\
++ \032 Changes since 2.3.1:\n\
++ \032 * Several bug fixes. The most important is a bug in the rsync module\n\
++ \032 that would occasionally cause change propagation to fail with a\n\
++ \032 'rename' error.\n\
++ \n\
++ \032 Changes since 2.2:\n\
++ \032 * The multi-threaded transport system is now disabled by default. (It\n\
++ \032 is not stable enough yet.)\n\
++ \032 * Various bug fixes.\n\
++ \032 * A new experimental feature:\n\
++ \032 The final component of a -path argument may now be the wildcard\n\
++ \032 specifier *. When Unison sees such a path, it expands this path on\n\
++ \032 the client into into the corresponding list of paths by listing the\n\
++ \032 contents of that directory.\n\
++ \032 Note that if you use wildcard paths from the command line, you will\n\
++ \032 probably need to use quotes or a backslash to prevent the * from\n\
++ \032 being interpreted by your shell.\n\
++ \032 If both roots are local, the contents of the first one will be used\n\
++ \032 for expanding wildcard paths. (Nb: this is the first one after the\n\
++ \032 canonization step - i.e., the one that is listed first in the user\n\
++ \032 interface - not the one listed first on the command line or in the\n\
++ \032 preferences file.)\n\
++ \n\
++ \032 Changes since 2.1:\n\
++ \032 * The transport subsystem now includes an implementation by Sylvain\n\
++ \032 Gommier and Norman Ramsey of Tridgell and Mackerras's rsync\n\
++ \032 protocol. This protocol achieves much faster transfers when only a\n\
++ \032 small part of a large file has been changed by sending just diffs.\n\
++ \032 This feature is mainly helpful for transfers over slow links--on\n\
++ \032 fast local area networks it can actually degrade performance--so we\n\
++ \032 have left it off by default. Start unison with the -rsync option\n\
++ \032 (or put rsync=true in your preferences file) to turn it on.\n\
++ \032 * \"Progress bars\" are now diplayed during remote file transfers,\n\
++ \032 showing what percentage of each file has been transferred so far.\n\
++ \032 * The version numbering scheme has changed. New releases will now be\n\
++ \032 have numbers like 2.2.30, where the second component is incremented\n\
++ \032 on every significant public release and the third component is the\n\
++ \032 \"patch level.\"\n\
++ \032 * Miscellaneous improvements to the GTK-based user interface.\n\
++ \032 * The manual is now available in PDF format.\n\
++ \032 * We are experimenting with using a multi-threaded transport\n\
++ \032 subsystem to transfer several files at the same time, making much\n\
++ \032 more effective use of available network bandwidth. This feature is\n\
++ \032 not completely stable yet, so by default it is disabled in the\n\
++ \032 release version of Unison.\n\
++ \032 If you want to play with the multi-threaded version, you'll need to\n\
++ \032 recompile Unison from sources (as described in the documentation),\n\
++ \032 setting the THREADS flag in Makefile.OCaml to true. Make sure that\n\
++ \032 your OCaml compiler has been installed with the -with-pthreads\n\
++ \032 configuration option. (You can verify this by checking whether the\n\
++ \032 file threads/threads.cma in the OCaml standard library directory\n\
++ \032 contains the string -lpthread near the end.)\n\
++ \n\
++ \032 Changes since 1.292:\n\
++ \032 * Reduced memory footprint (this is especially important during the\n\
++ \032 first run of unison, where it has to gather information about all\n\
++ \032 the files in both repositories).\n\
++ \032 * Fixed a bug that would cause the socket server under NT to fail\n\
++ \032 after the client exits.\n\
++ \032 * Added a SHIFT modifier to the Ignore menu shortcut keys in GTK\n\
++ \032 interface (to avoid hitting them accidentally).\n\
++ \n\
++ \032 Changes since 1.231:\n\
++ \032 * Tunneling over ssh is now supported in the Windows version. See the\n\
++ \032 installation section of the manual for detailed instructions.\n\
++ \032 * The transport subsystem now includes an implementation of the rsync\n\
++ \032 protocol, built by Sylvain Gommier and Norman Ramsey. This protocol\n\
++ \032 achieves much faster transfers when only a small part of a large\n\
++ \032 file has been changed by sending just diffs. The rsync feature is\n\
++ \032 off by default in the current version. Use the -rsync switch to\n\
++ \032 turn it on. (Nb. We still have a lot of tuning to do: you may not\n\
++ \032 notice much speedup yet.)\n\
++ \032 * We're experimenting with a multi-threaded transport subsystem,\n\
++ \032 written by Jerome Vouillon. The downloadable binaries are still\n\
++ \032 single-threaded: if you want to try the multi-threaded version,\n\
++ \032 you'll need to recompile from sources. (Say make THREADS=true.)\n\
++ \032 Native thread support from the compiler is required. Use the option\n\
++ \032 -threads N to select the maximal number of concurrent threads\n\
++ \032 (default is 5). Multi-threaded and single-threaded clients/servers\n\
++ \032 can interoperate.\n\
++ \032 * A new GTK-based user interface is now available, thanks to Jacques\n\
++ \032 Garrigue. The Tk user interface still works, but we'll be shifting\n\
++ \032 development effort to the GTK interface from now on.\n\
++ \032 * OCaml 3.00 is now required for compiling Unison from sources. The\n\
++ \032 modules uitk and myfileselect have been changed to use labltk\n\
++ \032 instead of camltk. To compile the Tk interface in Windows, you must\n\
++ \032 have ocaml-3.00 and tk8.3. When installing tk8.3, put it in c:\\Tcl\n\
++ \032 rather than the suggested c:\\Program Files\\Tcl, and be sure to\n\
++ \032 install the headers and libraries (which are not installed by\n\
++ \032 default).\n\
++ \032 * Added a new -addversionno switch, which causes unison to use\n\
++ \032 unison-<currentversionnumber> instead of just unison as the remote\n\
++ \032 server command. This allows multiple versions of unison to coexist\n\
++ \032 conveniently on the same server: whichever version is run on the\n\
++ \032 client, the same version will be selected on the server.\n\
++ \n\
++ \032 Changes since 1.219:\n\
++ \032 * INCOMPATIBLE CHANGE: Archive format has changed. Make sure you\n\
++ \032 synchronize your replicas before upgrading, to avoid spurious\n\
++ \032 conflicts. The first sync after upgrading will be slow.\n\
++ \032 * This version fixes several annoying bugs, including:\n\
++ \032 + Some cases where propagation of file permissions was not\n\
++ \032 working.\n\
++ \032 + umask is now ignored when creating directories\n\
++ \032 + directories are create writable, so that a read-only directory\n\
++ \032 and its contents can be propagated.\n\
++ \032 + Handling of warnings generated by the server.\n\
++ \032 + Synchronizing a path whose parent is not a directory on both\n\
++ \032 sides is now flagged as erroneous.\n\
++ \032 + Fixed some bugs related to symnbolic links and nonexistant\n\
++ \032 roots.\n\
++ \032 o When a change (deletion or new contents) is propagated\n\
++ \032 onto a 'follow'ed symlink, the file pointed to by the\n\
++ \032 link is now changed. (We used to change the link itself,\n\
++ \032 which doesn't fit our assertion that 'follow' means the\n\
++ \032 link is completely invisible)\n\
++ \032 o When one root did not exist, propagating the other root\n\
++ \032 on top of it used to fail, because unison could not\n\
++ \032 calculate the working directory into which to write\n\
++ \032 changes. This should be fixed.\n\
++ \032 * A human-readable timestamp has been added to Unison's archive\n\
++ \032 files.\n\
++ \032 * The semantics of Path and Name regular expressions now correspond\n\
++ \032 better.\n\
++ \032 * Some minor improvements to the text UI (e.g. a command for going\n\
++ \032 back to previous items)\n\
++ \032 * The organization of the export directory has changed -- should be\n\
++ \032 easier to find / download things now.\n\
++ \n\
++ \032 Changes since 1.200:\n\
++ \032 * INCOMPATIBLE CHANGE: Archive format has changed. Make sure you\n\
++ \032 synchronize your replicas before upgrading, to avoid spurious\n\
++ \032 conflicts. The first sync after upgrading will be slow.\n\
++ \032 * This version has not been tested extensively on Windows.\n\
++ \032 * Major internal changes designed to make unison safer to run at the\n\
++ \032 same time as the replicas are being changed by the user.\n\
++ \032 * Internal performance improvements.\n\
++ \n\
++ \032 Changes since 1.190:\n\
++ \032 * INCOMPATIBLE CHANGE: Archive format has changed. Make sure you\n\
++ \032 synchronize your replicas before upgrading, to avoid spurious\n\
++ \032 conflicts. The first sync after upgrading will be slow.\n\
++ \032 * A number of internal functions have been changed to reduce the\n\
++ \032 amount of memory allocation, especially during the first\n\
++ \032 synchronization. This should help power users with very big\n\
++ \032 replicas.\n\
++ \032 * Reimplementation of low-level remote procedure call stuff, in\n\
++ \032 preparation for adding rsync-like smart file transfer in a later\n\
++ \032 release.\n\
++ \032 * Miscellaneous bug fixes.\n\
++ \n\
++ \032 Changes since 1.180:\n\
++ \032 * INCOMPATIBLE CHANGE: Archive format has changed. Make sure you\n\
++ \032 synchronize your replicas before upgrading, to avoid spurious\n\
++ \032 conflicts. The first sync after upgrading will be slow.\n\
++ \032 * Fixed some small bugs in the interpretation of ignore patterns.\n\
++ \032 * Fixed some problems that were preventing the Windows version from\n\
++ \032 working correctly when click-started.\n\
++ \032 * Fixes to treatment of file permissions under Windows, which were\n\
++ \032 causing spurious reports of different permissions when\n\
++ \032 synchronizing between windows and unix systems.\n\
++ \032 * Fixed one more non-tail-recursive list processing function, which\n\
++ \032 was causing stack overflows when synchronizing very large replicas.\n\
++ \n\
++ \032 Changes since 1.169:\n\
++ \032 * The text user interface now provides commands for ignoring files.\n\
++ \032 * We found and fixed some more non-tail-recursive list processing\n\
++ \032 functions. Some power users have reported success with very large\n\
++ \032 replicas.\n\
++ \032 * INCOMPATIBLE CHANGE: Files ending in .tmp are no longer ignored\n\
++ \032 automatically. If you want to ignore such files, put an appropriate\n\
++ \032 ignore pattern in your profile.\n\
++ \032 * INCOMPATIBLE CHANGE: The syntax of ignore and follow patterns has\n\
++ \032 changed. Instead of putting a line of the form\n\
++ \032 ignore = <regexp>\n\
++ \n\
++ \032 in your profile (.unison/default.prf), you should put:\n\
++ \032 ignore = Regex <regexp>\n\
++ \n\
++ \032 Moreover, two other styles of pattern are also recognized:\n\
++ \032 ignore = Name <name>\n\
++ \n\
++ \032 matches any path in which one component matches <name>, while\n\
++ \032 ignore = Path <path>\n\
++ \n\
++ \032 matches exactly the path <path>.\n\
++ \032 Standard \"globbing\" conventions can be used in <name> and <path>:\n\
++ \032 + a ? matches any single character except /\n\
++ \032 + a * matches any sequence of characters not including /\n\
++ \032 + [xyz] matches any character from the set {x, y, z }\n\
++ \032 + {a,bb,ccc} matches any one of a, bb, or ccc.\n\
++ \032 See the user manual for some examples.\n\
++ \n\
++ \032 Changes since 1.146:\n\
++ \032 * Some users were reporting stack overflows when synchronizing huge\n\
++ \032 directories. We found and fixed some non-tail-recursive list\n\
++ \032 processing functions, which we hope will solve the problem. Please\n\
++ \032 give it a try and let us know.\n\
++ \032 * Major additions to the documentation.\n\
++ \n\
++ \032 Changes since 1.142:\n\
++ \032 * Major internal tidying and many small bugfixes.\n\
++ \032 * Major additions to the user manual.\n\
++ \032 * Unison can now be started with no arguments - it will prompt\n\
++ \032 automatically for the name of a profile file containing the roots\n\
++ \032 to be synchronized. This makes it possible to start the graphical\n\
++ \032 UI from a desktop icon.\n\
++ \032 * Fixed a small bug where the text UI on NT was raising a 'no such\n\
++ \032 signal' exception.\n\
++ \n\
++ \032 Changes since 1.139:\n\
++ \032 * The precompiled windows binary in the last release was compiled\n\
++ \032 with an old OCaml compiler, causing propagation of permissions not\n\
++ \032 to work (and perhaps leading to some other strange behaviors we've\n\
++ \032 heard reports about). This has been corrected. If you're using\n\
++ \032 precompiled binaries on Windows, please upgrade.\n\
++ \032 * Added a -debug command line flag, which controls debugging of\n\
++ \032 various modules. Say -debug XXX to enable debug tracing for module\n\
++ \032 XXX, or -debug all to turn on absolutely everything.\n\
++ \032 * Fixed a small bug where the text UI on NT was raising a 'no such\n\
++ \032 signal' exception.\n\
++ \n\
++ \032 Changes since 1.111:\n\
++ \032 * INCOMPATIBLE CHANGE: The names and formats of the preference files\n\
++ \032 in the .unison directory have changed. In particular:\n\
++ \032 + the file \"prefs\" should be renamed to default.prf\n\
++ \032 + the contents of the file \"ignore\" should be merged into\n\
++ \032 default.prf. Each line of the form REGEXP in ignore should\n\
++ \032 become a line of the form ignore = REGEXP in default.prf.\n\
++ \032 * Unison now handles permission bits and symbolic links. See the\n\
++ \032 manual for details.\n\
++ \032 * You can now have different preference files in your .unison\n\
++ \032 directory. If you start unison like this\n\
++ \032 unison profilename\n\
++ \n\
++ \032 (i.e. with just one \"anonymous\" command-line argument), then the\n\
++ \032 file ~/.unison/profilename.prf will be loaded instead of\n\
++ \032 default.prf.\n\
++ \032 * Some improvements to terminal handling in the text user interface\n\
++ \032 * Added a switch -killServer that terminates the remote server\n\
++ \032 process when the unison client is shutting down, even when using\n\
++ \032 sockets for communication. (By default, a remote server created\n\
++ \032 using ssh/rsh is terminated automatically, while a socket server is\n\
++ \032 left running.)\n\
++ \032 * When started in 'socket server' mode, unison prints 'server\n\
++ \032 started' on stderr when it is ready to accept connections. (This\n\
++ \032 may be useful for scripts that want to tell when a socket-mode\n\
++ \032 server has finished initalization.)\n\
++ \032 * We now make a nightly mirror of our current internal development\n\
++ \032 tree, in case anyone wants an up-to-the-minute version to hack\n\
++ \032 around with.\n\
++ \032 * Added a file CONTRIB with some suggestions for how to help us make\n\
++ \032 Unison better.\n\
++ \n\
++ "))
++::
++ ("", ("Junk",
++ "\032 __________________________________________________________________\n\
++ \n\
++ \032 This document was translated from L^AT[E]X by [2]H^EV^EA.\n\
++ \n\
++ References\n\
++ \n\
++ \032 1. file://localhost/home/greg/projects/unison/branches/2.40/doc/temp.html#ssh-win\n\
++ \032 2. http://hevea.inria.fr/index.html\n\
++ "))
++::
++ [];;
++
diff --git a/unison240.spec b/unison240.spec
index 440c330..26c7334 100644
--- a/unison240.spec
+++ b/unison240.spec
@@ -28,7 +28,7 @@
Name: unison%{ver_compat_name}
Version: %{ver_compat}%{ver_noncompat}
-Release: 4%{?dist}
+Release: 6%{?dist}
Summary: Multi-master File synchronization tool
@@ -37,6 +37,11 @@ License: GPLv3+
URL: http://www.cis.upenn.edu/~bcpierce/unison
Source0: http://www.cis.upenn.edu/~bcpierce/unison/download/releases/unison-%{version}/unison-%{version}.tar.gz
Source1: unison.png
+Source2: http://www.cis.upenn.edu/~bcpierce/unison/download/releases/unison-%{ver_compat}%{ver_noncompat}/unison-%{ver_compat}%{ver_noncompat}-manual.html
+
+#Add documentation, already fixed in trunk (upstream)
+Patch1: %{name}-missing-documentation.patch
+
ExcludeArch: sparc64 s390 s390x
BuildRequires: ocaml
@@ -66,9 +71,12 @@ Note that this package contains Unison version %{ver_compat}, and
will never be upgraded to a different major version. Other packages
exist if you require a different major version.
+
%prep
%setup -q -n unison-%{version}
+%patch1 -p1 -b .documentation
+
cat > %{name}.desktop <<EOF
[Desktop Entry]
Type=Application
@@ -82,15 +90,20 @@ StartupNotify=true
Categories=Utility;
EOF
+
%build
make NATIVE=true UISTYLE=gtk2 THREADS=true
+
%install
mkdir -p %{buildroot}%{_bindir}
cp -p unison %{buildroot}%{_bindir}/unison-%{ver_compat}
mkdir -p %{buildroot}%{_datadir}/pixmaps
cp -p %{SOURCE1} %{buildroot}%{_datadir}/pixmaps/%{name}.png
+#additional documentation
+cp -p %{SOURCE2} unison-manual.html
+
desktop-file-install --dir %{buildroot}%{_datadir}/applications \
%{name}.desktop
@@ -102,6 +115,7 @@ alternatives \
%{_bindir}/unison-%{ver_compat} \
%{ver_priority}
+
%postun
if [ $1 -eq 0 ]; then
alternatives --remove unison \
@@ -109,26 +123,33 @@ if [ $1 -eq 0 ]; then
fi
exit 0
+
%files
-%defattr(-,root,root,-)
-%doc COPYING NEWS README
+%doc COPYING NEWS README unison-manual.html
%{_bindir}/unison-%{ver_compat}
%{_datadir}/applications/%{name}.desktop
%{_datadir}/pixmaps/%{name}.png
+
%changelog
+* Sun Jan 22 2012 Gregor Tätzner <brummbq at fedoraproject.com> - 2.40.63-6
+- Patch built-in documentation.
+
+* Sat Jan 21 2012 Gregor Tätzner <brummbq at fedoraproject.org> - 2.40.63-5
+- Add unison-manual.html.
+
* Fri Jan 13 2012 Gregor Tätzner <brummbq at fedoraproject.org> - 2.40.63-4
-- remove ocaml minimum version
-- add Requires and provides scripts
+- Remove ocaml minimum version.
+- Add Requires and provides scripts.
-* Tue Sep 27 2011 Gregor Taetzner <brummbq at fedoraproject.org> - 2.40.63-3
-- vendor tag removed
+* Tue Sep 27 2011 Gregor Tätzner <brummbq at fedoraproject.org> - 2.40.63-3
+- Remove vendor tag.
-* Sun Sep 04 2011 Gregor Taetzner <gregor at freenet.de> - 2.40.63-2
-- remove xorg-x11-font-utils Requirement
-- enable THREADS=true
+* Sun Sep 04 2011 Gregor Tätzner <brummbq at fedoraproject.org> - 2.40.63-2
+- Remove xorg-x11-font-utils Requirement.
+- Enable THREADS=true.
-* Thu Aug 30 2011 Gregor Taetzner <gregor at freenet.de> - 2.40.63-1
+* Thu Aug 30 2011 Gregor Tätzner <brummbq at fedoraproject.org> - 2.40.63-1
- Version bump.
* Sun Jul 26 2009 Fedora Release Engineering <rel-eng at lists.fedoraproject.org> - 2.27.57-13
More information about the scm-commits
mailing list