Syncers

Overview

Paludis makes use of scripts called 'syncers' to perform certain sync actions (e.g. handling paludis --sync for e format repositories). Some syncers support additional options that can be set via the sync_options repository configuration key. Syncers can be added for additional protocols (for example, if you need to use a repository that uses a weird version control system), and built-in syncers can be replaced (for example, if you want to use a non-standard program).

The syncer protocol used by Paludis is not always identical to the one used by the syncing program. In particular, several syncing programs support URIs in the form http://, and Paludis would not be able to tell whether such a URI should be synced by, say, Subversion, Git or Darcs. Instead, you must use svn+http:// and so on.

Standard Syncers

Paludis ships with the following sync protocols (you can use cave print-sync-protocols and cave sync-protocol-options to get the list yourself). Note that many of these syncers depend upon external programs that are not listed as dependencies for Paludis.

bzr
bzr+aftp
bzr+file
bzr+ftp
bzr+http
bzr+https
bzr+lp
bzr+sftp
bzr+ssh
cvs+ext
cvs+pserver
cvs+ssh
darcs+file
darcs+http
darcs+https
darcs+ssh
file
git
git+file
git+http
git+https
git+rsync
git+ssh
hg+file
hg+http
hg+https
hg+ssh
hg+static-http
rsync
rsync+ssh
svn
svn+file
svn+http
svn+https
svn+ssh
tar+file
tar+ftp
tar+http
tar+https
dummy

User Defined Syncers

To write your own syncer for protocol proto, create an executable script named doproto (the do prefix is essential). Syncers may be located in any of the following directories:

• confdir/syncers/, where confdir is the directory in which use.conf et al. reside.
• DATADIR/paludis/syncers/. On most systems, DATADIR is /usr/share.
• LIBEXECDIR/paludis/syncers/. On most systems, LIBEXECDIR is /usr/libexec.

Paludis places its own syncers in LIBEXECDIR/syncers/doproto. This directory is not for end user use.

A syncer script can be called in two ways:

• With --help as an argument. When this happens, it must output a useful help message and then exit without syncing anything.
• With two arguments, the first being the local directory and the second being the remote sync URL. If sync_options is used, its contents are also passed as arguments. Success or failure is indicated via exit status.

Many syncers use source "${PALUDIS_EBUILD_DIR}/echo_functions.bash" early on to get access to ewarn and friends.

For examples, consult the built-in syncers, which can be found in LIBEXECDIR/paludis/syncers/.