The configuration file

Tailor reads a standard  ConfigParser configuration file, composed by several sections.

Alternatively, the configuration file may be a full fledged Python script, where the configuration settings are expressed in its docstring.

For a detailed and up-to-date list of accepted options see the source:README file.

My standard config

For the impatient readers, here is my standard basic recipe:

#!/usr/bin/env /usr/local/bin/tailor

"""
[DEFAULT]
verbose = True

[billiards]
target = darcs:billiards
root-directory = billiards
source = cvs:billiards
start-revision = INITIAL
subdir = billiards

[darcs:billiards]
darcs-command = /usr/local/bin/darcs220-64bit
init-options = --darcs-2
split-initial-changeset-level = 2

[cvs:billiards]
repository = :pserver:anonymous@cvs.sv.gnu.org:/sources/billiards
module = billiards
"""

This will will create a "billiards" directory in the CWD (the "root-directory" option), containing tailor private stuff, and the real darcs target repository in a "billiards" subdir under that (as specified by "subdir" option, see also DisjunctWorkingDirectories).

The two levels let me follow several branches (say, billiards-trunk and billiards-stable). In such a case, the file would contain multiple related tasks.

I usually write a variant of this in (say) billiards.tailor , chmod +x, and re-execute at will.

Historical note, or what command line options are for

CvSync didn't use an external configuration, but rather used only command line options to drive its activity. That turned out to be confusing at best, given the flexibility one may want to achieve.

When tailor was introduced with its new mechanism, I opted to keep the options but to use them just as a quick way to start a new configuration file.

When --configfile is not specified but --verbose is, tailor simply writes on the standard output a very basic configuration that resembles the given settings. So

tailor -s baz -Radmin@some.where.net--funny-configs -mfun--main--0 -tbzr --ignore-arch-ids --verbose > config.tailor

is the easiest way to start a new migration from baz to bzr in this case. Be sure to edit the template to adapt it to your needs before using it with

tailor --configfile config.tailor

Command line options most likely won't survive VersionOne...

The [DEFAULT] section

Here you can set commonly used settings: all projects and repositories will fallback using this section if they don't explicitly set a particular value.

[DEFAULT]
verbose = True
patch-name-format=[%(project)s @ %(revision)s]: %(firstlogline)s
remove-first-log-line=True

By default tailor operates on all the projects contained by the configuration file. If this is not wanted, you can use the projects option to set the names of the projects to consider by default. Other projects will be processed only when explicitly specified on the command line. With the following incomplete config

[DEFAULT]
projects = projA,projB

[projA]
...

[projB]
...

[projC]

executing

$ tailor --configfile=incomplete.config

would operate on projA and projB, while

$ tailor --configfile=incomplete.config projC

would operate on projC only.

Project sections

Every section which name does not contain a colon : denotes a project, and thus a single configuration file may describe several different projects.

Two mandatory options of any project are source and target, respectively indicating the SourceRepository and the TargetRepository.

[project]
patch-name-format = None
source = bzr:project
target = darcs:project

[bzr:project]
...

[darcs:project]
...

Repository sections

Each repository (actually, the WorkingDirectory of a repository) is described by a section which name starts with a known backend system followed by a colon : character, like darcs: or monotone:.

The needed options depend on the repository kind and weather its being used as a SourceRepository or a TargetRepository: generally the source repository requires at least the repository option, ie the address of the upstream repository.