#---------------#
# Documentation #
#---------------#

Documentation for Unison is in the manual, which is available in
text formats in /usr/share/doc/unison. The same documentation
can also be accessed over the command line, and you can list the
available topics by executing 'unison -doc topics'. Of
particular interest for new users is the tutorial at
'unison -doc tutorial'.

The most common usage of this package is to use ssh to connect
to the remote host via to synchronise files. The 'Install'
section of the manual details how to set up ssh with a key
file and authentication agent to avoid repeatedly entering
passwords or pass-phrases. Assuming your key file remains
private, this is a more secure authentication method than
passwords.

The GTK+ interface for Unison is now available separately in
the unison-gtk package.

 -- Robert McQueen <robot101@debian.org>  Wed, 29 Aug 2001 21:18:29 +0100

#------------------------#
# Unison and UnisonX.Y.Z #
#------------------------#

This package has been split when Unison 2.10.2 was released.
There is now many versions of the package :
- unison, unison-gtk (version 2.27)
- unison2.27.57, unison2.27.57-gtk (version 2.27.57)
- unison2.13.16, unison2.13.16-gtk (version 2.13.16)
- unison2.9.1, unison2.9.1-gtk (version 2.9.1)

The reason for this split is to preserve protocol compatibility with actual
stable release of debian (e.g. Woody or Sarge or Etch).  By this way, you can
install unison and synchronise testing/unstable systems or install unison2.9.1
and synchronise testing/unstable with stable systems.

You can install both unison and unisonX.Y.Z, an alternative system is used (see
"man update-alternatives").

When the stable release will contain unison 2.10.2, unison2.9.1 will be
removed. When a new stable release of unison will come (for example unison
2.11.0) a package unison2.10.2 will be created to be able to synchronise with
the future stable release of debian. The package unison will then hold the
latest release of Unison (e.g. 2.11.0).

By this way, you should always be able to synchronise stable/testing/unstable
system using unison (the good version of unison).

This scheme continue to apply further (unison 2.13.16 was released in unison
package and unison2.9.1 was keep in Etch/Sid while Sarge was stable).

Etch has been released with unison 2.13.16, so unison2.9.1 has been removed.
Lenny has been released with unison 2.27.57, so unison2.13.16 has been removed.

 -- Sylvain Le Gall <gildor@debian.org>  Mon, 25 Apr 2005 23:06:44 +0200

#-------------#
# ssh-askpass #
#-------------#

Ssh-askpass is a recommended package when using unison-gtk. The reason
for this is that if you use SSH access and that the key for this specific
SSH login is password protected and that you don't have added it to your
ssh-agent, you should be asked for a password in console mode. If unison
was launched from menu, you won't be aware of this and the command will
fail without explanation. The problem will be the same for simple password
access. So it is strongly recommended to install ssh-askpass if you want
to use SSH access.

However, it is not a dependency, because there is no obvious call to
ssh-askpass in the unison source. Moreover, using SSH is not mandatory for
unison, ssh is only a "recommends" for unison and not a "depends".

 -- Sylvain Le Gall <gildor@debian.org>  Mon,  9 May 2005 00:47:47 +0200

#-----------------#
# removable media #
#-----------------#

Using unison with removable media is not safe. If you run unison in batch mode
with one of the replica on a removable media and if the media get disconnected
during the operation unison will consider that most files of one replica has
just been deleted and will delete the file of the other replica since it is
running in batch mode.

This happens if you run in batch mode. If you are not running in batch you
should notice that unison propose to delete a lot of files!

As usual: keep an eye of what is proposed by unison! This is one of the reason
why unison keep asking you what you really want to do.

 -- Sylvain Le Gall <gildor@debian.org>  Thu, 15 Feb 2007 22:12:48 +0100

#----------------------#
# unison-latest-stable #
#----------------------#

The package unison provide a link to the latest stable version of unison. This
link is here to help people not asking themselves what is the latest stable
version of unison.

In package provided for compatibility reason (unison2.9.1 for example) such a link
doesn't exists.

If you use unison-latest-stable, you are sure to use the most up-to-date stable
version of unison.

Moreover, using a constant name help "update-alternatives" not to get lost when
upgrading the package from major version to major version (when the version
of unison change).

 -- Sylvain Le Gall <gildor@debian.org>  Thu, 20 Sep 2007 15:58:53 +0200

#---------------------------------------------#
# Git merge, branches and unisonX.Y.Z package #
#---------------------------------------------#

The unison package is represented by the master branch in git. unisonX.Y.Z are
represented through X.Y.Z/{master|upstream} branches.

To create a new branch:
- git checkout master
- git branch X.Y.Z/master
- git checkout X.Y.Z/master
- go through the checklist (see after)
- git checkout upstream
- git branch X.Y.Z/upstream
- git checkout pristine-tar
- copy and rename corresponding pristine tar files to allow a
  unisonX.Y.Z.orig.tar.gz to be recreated.

To merge a branch X.Y.Z/master:
- git checkout X.Y.Z/master
- dch "Synchronize with unison package:" && git add debian/changelog
  && git commit
- git merge master
- solve conflicts and go through checlist (see after)

To merge the branch master:
- git checkout master
- dch "Synchronize with unisonX.Y.Z package:" && git add debian/changelog
  && git commit
- git merge X.Y.Z/master
- solve conflicts and go through checlist (see after)

Checklist:
- debian/changelog: check that changelog has not been erased
- debian/control: rename every package to unisonX.Y.Z or unisonX.Y.Z-gtk (or
  for unison package unison and unison-gtk)
- debian/gbp.conf: check that content end with
    upstream-branch = X.Y.Z/upstream
    debian-branch = X.Y.Z/master
    debian-tag = debian/unisonX.Y.Z-%(version)s
  or (for unison package)
    nothing

 -- Sylvain Le Gall <gildor@debian.org>  Fri, 26 Feb 2010 01:12:22 +0100
