Common options

repository : string

When a repository is used as a source, it must indicate its origin with repository, and for some backends also a module, but are not required when it's a target system, even if some backend may use the information to create the target repository (like svn backend does).

subdir : string

When the source and target repositories use different subdirectories, tailor uses rsync to copy the changes between the two after each applied changeset. When the source repository basedir is a subdirectory of target basedir tailor prefixes all paths coming from upstream to match the relative position.

This defaults to the project's setting.

command : string

Backends based on external command line tool such as svn or darcs offers this option to impose a particular external binary to be used, as done below in the example about disjunct working directories.

python-path : string

For pythonique backends such as bzr and hg this indicates where the respective library is located.

encoding : string

States the charset encoding the particular repository uses, and it's particularly important when it differs from local system setup, that you may inspect executing:

python -m locale

encoding-errors-policy : string

By default is strict, that means that Python will raise an exception on Unicode conversion errors. Valid options are ignore that simply skips offending glyphs and replace where unrecognized entities are replaced with a place holder.

delay-before-apply : integer

Sometime the migration is fast enough to put the upstream server under an excessive load. When this is the case, you may specify delay-before-apply = 5, that is the number of seconds tailor will wait before applying each changeset.

It defaults to None, ie no delay at all.

post-commit-check : bool

After each commit tailor will perform a check on the target working directory asserting there's no changes left. This is particularly useful when trying to debug source backends... at a little cost.

True by default.

aegis

Sample config fragment:

[aegis:target]
#
# Set the aegis project as the tailor module, tailor will *not*
# create the aegis project for you!
#
module = $AEGIS_PROJECT
#
# the subdir will be used as the working directory for aegis
# changes, it *must* be different from the source:subdir.
#
subdir = aegisside

arx

baz

bzr

cdv

cvs

changeset-threshold : integer

Maximum number of seconds allowed to separated commits to different files for them to be considered part of the same changeset.

180 by default.

freeze-keywords : bool

With this enabled (it is off by default) tailor will use -kk flag on checkouts and updates to turn off the keyword expansion. This may help minimizing the chance of spurious conflicts with later merges between different branches.

False by default.

tag-entries : bool

CVS and CVSPS repositories may turn off automatic tagging of entries, that tailor does by default to prevent manual interventions in the CVS working copy, using tag_entries = False.

True by default.

trim-module-components : integer

When the checked out tree involves CVS modules on the server Tailor fails to build up the ChangeSets view from the cvs rlog output, since in that case the paths that Tailor finds in the log refers to the real location of the entries on the server, and not, as usual, relatives to the root of the checked out tree. Of course, Tailor must be exact in correlating the information coming from the log and the actual checked out content in the filesystem, so in this case, by default it fails with an obscure message at bootstrap time.

Given that most of the time it's simply a matter of a common prefix, this option offers the so called "far-from-perfect-poor-man-workaround" to the CVS/Tailor shortcoming, until a better solution arises.

When you set this to an integer greater than zero, the parser will cut off that many components from the beginning of the pathnames it finds in the log.

0 (zero) by default.

cvsps

freeze-keywords : bool

With this enabled (it is off by default) tailor will use -kk flag on checkouts and updates to turn off the keyword expansion. This may help minimizing the chance of spurious conflicts with later merges between different branches.

False by default.

tag-entries : bool

CVS and CVSPS repositories may turn off automatic tagging of entries, that tailor does by default to prevent manual interventions in the CVS working copy, using tag_entries = False.

True by default.

darcs

init-options : string

By default empty, may specify options used to initialize the target repository, for example to use the newer darcs-2.

look-for-adds : bool

By default tailor commits only the entries explicitly mentioned by the upstream changeset. Sometimes this is not desiderable, maybe even as a quick workaround to a tailor bug. This option allows a more relaxed view of life using record --look-for-adds.

replace-badchars : string

Apparently some darcs repo contains some characters that are illegal in an XML stream. This is the case when one uses non-utf8 accents. To be safe, you can replace them with their xml-safe equivalent. The given string must be a regular and valid Python dictionary, with each substitution keyed on the character to be replaced. By default it's:

{
  '\xc1': 'Á',
  '\xc9': 'É',
  '\xcd': 'Í',
  '\xd3': 'Ó',
  '\xd6': 'Ö',
  '\xd5': 'Ő',
  '\xda': 'Ú',
  '\xdc': 'Ü',
  '\xdb': 'Ű',
  '\xe1': 'á',
  '\xe9': 'é',
  '\xed': 'í',
  '\xf3': 'ó',
  '\xf6': 'ö',
  '\xf5': 'ő',
  '\xfa': 'ú',
  '\xfc': 'ü',
  '\xfb': 'ű',
  '\xf1': 'ñ',
  '\xdf': 'ß',
  '\xe5': 'å'
}

start-revision : string

Under darcs this may be either the name of a tag or the hash of an arbitrary patch in the repository, plus the ordinary INITIAL or HEAD symbols.

Note

If you want to start from a particular patch, giving its hash value as start-revision, you must use a subdir different from ".". [5]

split-initial-changeset-level : integer

Sometime it's desiderable to avoid the impact of the huge patch produced by the bootstrap step, that's basically a snapshot of the whole working directory. This option controls that: if greater than zero, the initial import will be splitted in multiple changesets, one per directory not deeper than the specified level. A value of 1 will build a changeset for the top level contents (directories and files), then a changeset for each subtree. Finally, a tag will comprehend all the changesets.

0 by default.

metadir : string

The location of the _darcs repository, relative to subdir. This is useful, e.g., to handle svn:externals, and more generally to merge multiple sources to a single darcs repository.

_darcs by default.

It allows you to specify the location of the _darcs repository, which makes it possible to have the following structure:

- target_repo
  | _darcs
  | source_repo_A
    | source_repo_C
    | source_repo_D
  | source_repo_B
    | source_repo_E

Every source_repo (from A to E) is registered in target_repo, merging them in a single darcs repository (but you still need five target repository in the config file, to specify each metadir).

Here is a sample config (from a real-world example) to give you and idea of how I use it (with a "disjunct working directories" scheme):

[DEFAULT]
projects = cil,ocamlutil
root-directory = /tmp/test
[cil]
source = svn:cil
start-revision = 10792
state-file = cil.tailor.state
target = darcs:cil
filter-badchars = True
[ocamlutil]
source = svn:ocamlutil
start-revision = 10719
state-file = ocamlutil.tailor.state
target = darcs:ocamlutil
filter-badchars = True
[svn:cil]
module = /trunk/cil
repository = svn://hal.cs.berkeley.edu/home/svn/projects
subdir = cil-svn
[darcs:cil]
subdir = cil-patched
[svn:ocamlutil]
module = /trunk/ocamlutil
repository = svn://hal.cs.berkeley.edu/home/svn/projects
subdir = cil-svn/ocamlutil
[darcs:ocamlutil]
subdir = cil-patched/ocamlutil
metadir = ../_darcs

Note

This setting must not be mistaken with the --repodir option from darcs. It should always match the following regexp: (../)*_darcs, since the metadir must be somewhere above subdir for darcs to handle it automatically.

mkdir /tmp/intermediary-repo
cd /tmp/intermediary-repo
darcs init --darcs-2
while python -c "print 'y'*200+'d'" | darcs pull --quiet real-source-repo
do
  tailor -c from-intermediary.tailor
done

git target

parent-repo : string

Relative path to a git directory to use as a parent. This is one way to import branches into a git repository, which creates a new git repository borrowing ancestry from the parent-repo. It is quite a simple way, and thus believed to be quite robust, but spreads branches across several git repositories. If this parameter is not set, and repository is not set either, the branch has no parent.

The alternative is to specify a repository parameter, to contain all git branches. The .git directory in the working copy for each branch will then only contain the .git/index file.

branch : string

The name of the branch to which to commit. It is only used in single-repository mode (using repository, see above). The default is to use the "master" branch.

branchpoint : string

A reference to the git commit which is the parent for the first revision on the branch to be imported. It can be a tag name or any syntax acceptable by git (eg. something like "tag~2", if you want to correct the idea of where the branchpoint is).

Since tailor generates mostly-stable SHA-1 revisions, you can usually also use a SHA-1 as branchpoint. Just import your trunk first, find the correct SHA-1, and setup and import your branch. This is especially useful since the current cvs source implementation misses many tags.

overwrite-tags : bool

By default the backend does not overwrite previous tag with a newer by the same name, and stops with an error. This flag allows you to force git to override preceeding tag with the same name.

False by default.

hg

monotone

keyid : string

Monotone key id to use for commits. The specified key must exist on keystore. Takes precedence over keygenid.

keygenid : string

Id of a new keypair to generate and store in the repository. The keypair is used for commits. Ignored if keyid is specified.

passphrase : string

Passphrase to use for commits. Must be specified unless you have one on your .monotonerc file

custom-lua : string

Optional custom lua script. If present, is written into _MTN/monotonerc.

p4

depot-path : string

The path within the depot indicating the root of all files that will be replicated.

This is used both for determining changes as well as mapping file locations from changesets to the filesystem.

Example: //depot/project/main/

p4-client : string

The perforce client spec to use.

Example: myhostname-tailor

p4-port : string

The address of the perforce server.

Example: perforce.mycompany.com:1666

svn

filter-badchars : bool (or string)

Activate (with True) or activate and specify (with a string) the filter on the svn log to eliminate illegal XML characters.

False by default, when set to True the following characters are washed out from the upstream changes:

allbadchars = "\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09" \
              "\x0B\x0C\x0E\x0F\x10\x11\x12\x13\x14\x15" \
              "\x16\x17\x18\x19\x1A\x1B\x1C\x1D\x1E\x1F\x7f"

If this is not right or enough, you can specify a string value instead of the boolean flag, containing the characters to omit, as in:

filter-badchars=\x00\x01

use-propset : bool

Indicate that tailor is allowed to properly inject the upstream changeset's author and timestamp into the target repository. As stated above, this requires a manual intervention on the repository itself and thus is off by default, and tailor simply appends those values to the changelog. When active at bootstrap time and the repository is local, tailor creates automatically a minimal hooks/pre-revprop-change script inside the repository, so no other intervention is needed.

False by default.

propset-date : bool

By default True, can be used to avoid setting the svn:date property on the Subversion revision, and thus problem with -r{DATE} mentioned above. When this is False, the original timestamp gets appended to the revision log.

use-limit : bool

By default True, should be set to False when using old Subversion clients, since log --limit was introduced with version 1.2. By using this option tailor can fetch just the revision it needs, instead of transfering whole history log.

commit-all-files : bool

By default True, commits all files from current changeset. Lets Subversion check the changes self. Set it to False, then whish to commits only changed files, that tailor detects, perhaps a network speedup. But a False can be insert an extra revision on long dep paths with lot of files. You would see two revisions on target, where the source have only one. For a true convert should leave it True.

trust-root : bool

Tailor by default verifies that the specified repository effectively points to the root of a Subversion repository, eventually splitting it and adjusting module accordingly. This is sometimes undesiderable, for example when the root isn't public and cannot be listed. Setting this option to True disable the check and tailor takes the given repository and module as-is.

ignore-externals : bool

By default the Subversion backend does not consider the external references defined in the source repository. This option force Tailor to behave as it did up to 0.9.20.

svn-tags : string

Name of the directory used for tags: tailor will copy tagged revisions under this directory.

/tags by default.

svn-branches : string

Name of the directory used for branches: tailor will copy branches under that directory.

/branches by default.

Note

Target module for branches must start with branches/. Every branch must configure in a single-repository mode.

Example: module = branches/branch.name

tla

Example 1

Just to illustrate the functionality, consider the following example:

#!/usr/bin/env tailor
"""
[DEFAULT]
debug = False
verbose = True
[project]
target = bzr:target
root-directory = /tmp/prova
state-file = tailor.state
source = darcs:source
before-commit = before
after-commit = after
start-revision = Almost arbitrarily tagging this as version 0.8
[bzr:target]
python-path = /opt/src/bzr.dev
subdir = bzrside
[darcs:source]
repository = /home/lele/WiP/cvsync
subdir = darcside
"""
def before(wd, changeset):
    print "BEFORE", changeset
    changeset.author = "LELE"
    return changeset
def after(wd, changeset):
    print "AFTER", changeset

With the above in a script called say tester, just doing:

$ chmod 755 tester
$ ./tester

will migrate the history from a darcs repository to a Bazaar one, forcing the author to a well-known name :-)

Example 2

A pre commit hook may even alter the content of the files. The following function replaces the DOS end-of-line convention with the UNIX one:

def newlinefix(wd, changeset):
    from pyutil import lineutil
    lineutil.lineify_all_files(wd.basedir, strip=True,
                               dirpruner=lineutil.darcs_metadir_dirpruner,
                               filepruner=lineutil.source_code_filepruner)
    return True

It uses zooko's pyutil [7] toolset. Another approach would be looping over changeset.entries and operating only on added or changed entries.

Example 3

This loops over the file touched by a particular changeset and tries to reindent it if it's a Python file:

def reindent_em(wd, changeset):
    import reindent
    import os
    for entry in changeset.entries:
        fname = os.path.join(wd.basedir, entry.name)
        try:
            if fname[-3:] == '.py':
                reindent.check(fname)
        except Exception, le:
            print "got an exception from attempt to reindent" \
                  " (maybe that file wasn't Python code?):" \
                  " changeset entry: %s, exception:" \
                  " %s %s %s" % (entry, type(le), repr(le),
                                 hasattr(le, 'args') and le.args,)
            raise le
    return True

You have to find reindent.py in your Python distribution and put it in your python path. Beware that this has some drawbacks: be sure to read ticket 8 annotations if you use it.