= The configuration file =

Tailor reads a standard [http://docs.python.org/lib/module-ConfigParser.html 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.