tailor (0.9.35+darcs20090615-1) direct (non packaging) changes

Summary

 README.html | 1702 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 1702 insertions(+)

    
download this patch

Patch contents

--- tailor-0.9.35+darcs20090615.orig/README.html
+++ tailor-0.9.35+darcs20090615/README.html
@@ -0,0 +1,1702 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
+<title>Tailor 1.0</title>
+<style type="text/css">
+
+/*
+:Author: David Goodger (goodger@python.org)
+:Id: $Id: html4css1.css 5196 2007-06-03 20:25:28Z wiemann $
+:Copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+
+See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
+customize this style sheet.
+*/
+
+/* used to remove borders from tables and images */
+.borderless, table.borderless td, table.borderless th {
+  border: 0 }
+
+table.borderless td, table.borderless th {
+  /* Override padding for "table.docutils td" with "! important".
+     The right padding separates the table cells. */
+  padding: 0 0.5em 0 0 ! important }
+
+.first {
+  /* Override more specific margin styles with "! important". */
+  margin-top: 0 ! important }
+
+.last, .with-subtitle {
+  margin-bottom: 0 ! important }
+
+.hidden {
+  display: none }
+
+a.toc-backref {
+  text-decoration: none ;
+  color: black }
+
+blockquote.epigraph {
+  margin: 2em 5em ; }
+
+dl.docutils dd {
+  margin-bottom: 0.5em }
+
+/* Uncomment (and remove this text!) to get bold-faced definition list terms
+dl.docutils dt {
+  font-weight: bold }
+*/
+
+div.abstract {
+  margin: 2em 5em }
+
+div.abstract p.topic-title {
+  font-weight: bold ;
+  text-align: center }
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+  margin: 2em ;
+  border: medium outset ;
+  padding: 1em }
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+  font-weight: bold ;
+  font-family: sans-serif }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+  color: red ;
+  font-weight: bold ;
+  font-family: sans-serif }
+
+/* Uncomment (and remove this text!) to get reduced vertical space in
+   compound paragraphs.
+div.compound .compound-first, div.compound .compound-middle {
+  margin-bottom: 0.5em }
+
+div.compound .compound-last, div.compound .compound-middle {
+  margin-top: 0.5em }
+*/
+
+div.dedication {
+  margin: 2em 5em ;
+  text-align: center ;
+  font-style: italic }
+
+div.dedication p.topic-title {
+  font-weight: bold ;
+  font-style: normal }
+
+div.figure {
+  margin-left: 2em ;
+  margin-right: 2em }
+
+div.footer, div.header {
+  clear: both;
+  font-size: smaller }
+
+div.line-block {
+  display: block ;
+  margin-top: 1em ;
+  margin-bottom: 1em }
+
+div.line-block div.line-block {
+  margin-top: 0 ;
+  margin-bottom: 0 ;
+  margin-left: 1.5em }
+
+div.sidebar {
+  margin: 0 0 0.5em 1em ;
+  border: medium outset ;
+  padding: 1em ;
+  background-color: #ffffee ;
+  width: 40% ;
+  float: right ;
+  clear: right }
+
+div.sidebar p.rubric {
+  font-family: sans-serif ;
+  font-size: medium }
+
+div.system-messages {
+  margin: 5em }
+
+div.system-messages h1 {
+  color: red }
+
+div.system-message {
+  border: medium outset ;
+  padding: 1em }
+
+div.system-message p.system-message-title {
+  color: red ;
+  font-weight: bold }
+
+div.topic {
+  margin: 2em }
+
+h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
+h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
+  margin-top: 0.4em }
+
+h1.title {
+  text-align: center }
+
+h2.subtitle {
+  text-align: center }
+
+hr.docutils {
+  width: 75% }
+
+img.align-left {
+  clear: left }
+
+img.align-right {
+  clear: right }
+
+ol.simple, ul.simple {
+  margin-bottom: 1em }
+
+ol.arabic {
+  list-style: decimal }
+
+ol.loweralpha {
+  list-style: lower-alpha }
+
+ol.upperalpha {
+  list-style: upper-alpha }
+
+ol.lowerroman {
+  list-style: lower-roman }
+
+ol.upperroman {
+  list-style: upper-roman }
+
+p.attribution {
+  text-align: right ;
+  margin-left: 50% }
+
+p.caption {
+  font-style: italic }
+
+p.credits {
+  font-style: italic ;
+  font-size: smaller }
+
+p.label {
+  white-space: nowrap }
+
+p.rubric {
+  font-weight: bold ;
+  font-size: larger ;
+  color: maroon ;
+  text-align: center }
+
+p.sidebar-title {
+  font-family: sans-serif ;
+  font-weight: bold ;
+  font-size: larger }
+
+p.sidebar-subtitle {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+p.topic-title {
+  font-weight: bold }
+
+pre.address {
+  margin-bottom: 0 ;
+  margin-top: 0 ;
+  font-family: serif ;
+  font-size: 100% }
+
+pre.literal-block, pre.doctest-block {
+  margin-left: 2em ;
+  margin-right: 2em }
+
+span.classifier {
+  font-family: sans-serif ;
+  font-style: oblique }
+
+span.classifier-delimiter {
+  font-family: sans-serif ;
+  font-weight: bold }
+
+span.interpreted {
+  font-family: sans-serif }
+
+span.option {
+  white-space: nowrap }
+
+span.pre {
+  white-space: pre }
+
+span.problematic {
+  color: red }
+
+span.section-subtitle {
+  /* font-size relative to parent (h1..h6 element) */
+  font-size: 80% }
+
+table.citation {
+  border-left: solid 1px gray;
+  margin-left: 1px }
+
+table.docinfo {
+  margin: 2em 4em }
+
+table.docutils {
+  margin-top: 0.5em ;
+  margin-bottom: 0.5em }
+
+table.footnote {
+  border-left: solid 1px black;
+  margin-left: 1px }
+
+table.docutils td, table.docutils th,
+table.docinfo td, table.docinfo th {
+  padding-left: 0.5em ;
+  padding-right: 0.5em ;
+  vertical-align: top }
+
+table.docutils th.field-name, table.docinfo th.docinfo-name {
+  font-weight: bold ;
+  text-align: left ;
+  white-space: nowrap ;
+  padding-left: 0 }
+
+h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
+h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+  font-size: 100% }
+
+ul.auto-toc {
+  list-style-type: none }
+
+</style>
+</head>
+<body>
+<div class="document" id="tailor-1-0">
+<h1 class="title">Tailor 1.0</h1>
+
+<!-- Hey! This is reStructuredText, where "*this*" notation means an -->
+<!-- italic "this" and similar oddities. See the notes at the end of -->
+<!-- this file for details. -->
+<div class="contents topic" id="contents">
+<p class="topic-title first">Contents</p>
+<ul class="simple">
+<li><a class="reference internal" href="#about" id="id30">About</a></li>
+<li><a class="reference internal" href="#installation" id="id31">Installation</a></li>
+<li><a class="reference internal" href="#testing" id="id32">Testing</a></li>
+<li><a class="reference internal" href="#operation" id="id33">Operation</a><ul>
+<li><a class="reference internal" href="#examples" id="id34">Examples</a></li>
+<li><a class="reference internal" href="#cvs-start-revision" id="id35">CVS start-revision</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#resolving-conflicts" id="id36">Resolving conflicts</a></li>
+<li><a class="reference internal" href="#shortcomings" id="id37">Shortcomings</a></li>
+<li><a class="reference internal" href="#config-file-format" id="id38">Config file format</a><ul>
+<li><a class="reference internal" href="#configuration-sections" id="id39">Configuration sections</a><ul>
+<li><a class="reference internal" href="#default" id="id40">Default</a></li>
+<li><a class="reference internal" href="#projects" id="id41">Projects</a></li>
+<li><a class="reference internal" href="#repositories" id="id42">Repositories</a><ul>
+<li><a class="reference internal" href="#common-options" id="id43">Common options</a></li>
+<li><a class="reference internal" href="#id12" id="id44">aegis</a></li>
+<li><a class="reference internal" href="#id13" id="id45">arx</a></li>
+<li><a class="reference internal" href="#id14" id="id46">baz</a></li>
+<li><a class="reference internal" href="#bzr" id="id47">bzr</a></li>
+<li><a class="reference internal" href="#cdv" id="id48">cdv</a></li>
+<li><a class="reference internal" href="#id15" id="id49">cvs</a></li>
+<li><a class="reference internal" href="#cvsps" id="id50">cvsps</a></li>
+<li><a class="reference internal" href="#id17" id="id51">darcs</a><ul>
+<li><a class="reference internal" href="#big-repositories" id="id52">Big repositories</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#git-target" id="id53">git target</a></li>
+<li><a class="reference internal" href="#hg" id="id54">hg</a></li>
+<li><a class="reference internal" href="#id19" id="id55">monotone</a></li>
+<li><a class="reference internal" href="#p4" id="id56">p4</a></li>
+<li><a class="reference internal" href="#svn" id="id57">svn</a></li>
+<li><a class="reference internal" href="#id20" id="id58">tla</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#disjunct-working-directories" id="id59">Disjunct working directories</a></li>
+<li><a class="reference internal" href="#using-a-python-script-as-configuration-file" id="id60">Using a Python script as configuration file</a><ul>
+<li><a class="reference internal" href="#pre-commit-and-post-commit-hooks" id="id61">Pre-commit and post-commit hooks</a><ul>
+<li><a class="reference internal" href="#example-1" id="id62">Example 1</a></li>
+<li><a class="reference internal" href="#example-2" id="id63">Example 2</a></li>
+<li><a class="reference internal" href="#example-3" id="id64">Example 3</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#state-file" id="id65">State file</a></li>
+<li><a class="reference internal" href="#logging" id="id66">Logging</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#further-help" id="id67">Further help</a></li>
+<li><a class="reference internal" href="#authors" id="id68">Authors</a><ul>
+<li><a class="reference internal" href="#aegis-support" id="id69">Aegis support</a></li>
+<li><a class="reference internal" href="#arx-support" id="id70">ArX support</a></li>
+<li><a class="reference internal" href="#bazaar-support" id="id71">Bazaar support</a></li>
+<li><a class="reference internal" href="#git-support" id="id72">Git support</a></li>
+<li><a class="reference internal" href="#monotone-support" id="id73">Monotone support</a></li>
+<li><a class="reference internal" href="#perforce-support" id="id74">Perforce support</a></li>
+<li><a class="reference internal" href="#tla-support" id="id75">Tla support</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#license" id="id76">License</a></li>
+<li><a class="reference internal" href="#about-this-document" id="id77">About this document</a></li>
+</ul>
+</div>
+<div class="section" id="about">
+<h1><a class="toc-backref" href="#id30">About</a></h1>
+<p>Tailor is a tool to migrate changesets between <a class="reference external" href="http://aegis.sourceforge.net/">Aegis</a>, <a class="reference external" href="http://www.nongnu.org/arx/">ArX</a>, <a class="reference external" href="http://bazaar-vcs.org/Baz1x">Baz</a>,
+<a class="reference external" href="http://bazaar-vcs.org/">Bazaar</a>, <a class="reference external" href="http://www.nongnu.org/cvs/">CVS</a>, <a class="reference external" href="http://www.codeville.org/">Codeville</a>, <a class="reference external" href="http://www.darcs.net/">Darcs</a>, <a class="reference external" href="http://git.or.cz/">Git</a>, <a class="reference external" href="http://www.selenic.com/mercurial/">Mercurial</a>, <a class="reference external" href="http://www.monotone.ca/">Monotone</a>,
+<a class="reference external" href="http://www.perforce.com/">Perforce</a>, <a class="reference external" href="http://subversion.tigris.org/">Subversion</a> and <a class="reference external" href="http://www.gnuarch.org/arch/index.html">Tla</a> <a class="footnote-reference" href="#id2" id="id1">[1]</a> repositories.</p>
+<p>This script makes it easier to keep the upstream changes merged in
+a branch of a product, storing needed information such as the upstream
+URI and revision in special properties on the branched directory.</p>
+<p>The following ascii-art illustrates the usual scenario:</p>
+<pre class="literal-block">
+                         +------------+            +------------+
++--------------+         | Immutable  |            | Working    |
+| Upstream CVS |--------&gt;| darcs      |-----------&gt;| darcs      |
+| repository   | tailor  | repository | darcs pull | repository |
++--------------+         +------------+            +------------+
+                                                         |^
+                                                         ||
+                                                         ||
+                                                         v|
+                                                        User
+</pre>
+<p>Ideally you should be able to swap and replace &quot;CVS server&quot; and &quot;darcs
+repository&quot; with any combination of the supported systems.</p>
+<p>It's still lacks the ability of doing a <a class="reference external" href="http://progetti.arstecnica.it/tailor/wiki/TwoWaySync">two way sync</a>.</p>
+<table class="docutils footnote" frame="void" id="id2" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td><p class="first">Aegis, ArX and Codeville systems may be used only as the <cite>target</cite>
+backend, since the <cite>source</cite> support isn't coded yet.
+Contributions on these backends will be very appreciated,
+since I do not use them enough to figure out the best way to
+get pending changes and build tailor ChangeSets out of them.</p>
+<p class="last">To the opposite, Baz (1.0, not Bazaar), Perforce and Tla
+are supported only as source systems.</p>
+</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="installation">
+<h1><a class="toc-backref" href="#id31">Installation</a></h1>
+<p>tailor is written in Python, and thus Python must be installed on
+your system to use it.  It has been successfully used with Python 2.3,
+2.4 and 2.5.</p>
+<p>Since it relies on external tools to do the real work such as <cite>cvs</cite>,
+<cite>darcs</cite> <a class="footnote-reference" href="#id4" id="id3">[2]</a> and <cite>svn</cite>, they need to be installed as well, although only
+those you will actually use.</p>
+<p>Make tailor executable:</p>
+<pre class="literal-block">
+$ chmod +x tailor
+</pre>
+<p>You can either run tailor where it is currently located, or move it
+along with the vcpx directory to a location in your PATH.</p>
+<p>There's even a standard setup.py that you may use to install the
+script using Python's conventional distutils.</p>
+<table class="docutils footnote" frame="void" id="id4" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id3">[2]</a></td><td>Darcs 1.0.2 is too old, 1.0.3 is good, 1.0.4 (the fourth
+release candidate is under final testing) is recommended since
+it's faster in most operations!</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="testing">
+<h1><a class="toc-backref" href="#id32">Testing</a></h1>
+<p>Tailor has more than 50 unit and operational tests, that you can
+run with the following command line:</p>
+<pre class="literal-block">
+$ tailor test -v
+</pre>
+<p>Since some tests take very long to complete, in particular the
+operational tests, you may prefer the execution of a single suite:</p>
+<pre class="literal-block">
+$ tailor test -v Darcs
+</pre>
+<p>or even a single test within a suite:</p>
+<pre class="literal-block">
+$ tailor test StateFile.testJournal
+</pre>
+<p>To obtain a list of the test, use <tt class="docutils literal"><span class="pre">--list</span></tt> option.  As usual with:</p>
+<pre class="literal-block">
+$ tailor test --help
+</pre>
+<p>you will get some more details.</p>
+<p>More recently, a suite of functional tests was added, in the directory
+<tt class="docutils literal"><span class="pre">./test-scripts</span></tt>: these are simple shell scripts that basically
+build a source repository, create a configuration file and run tailor,
+checking the result. You can execute them with:</p>
+<pre class="literal-block">
+$ sh test-svn2svn-simple.sh
+</pre>
+<p>or:</p>
+<pre class="literal-block">
+$ sh run-all-test.sh
+</pre>
+</div>
+<div class="section" id="operation">
+<h1><a class="toc-backref" href="#id33">Operation</a></h1>
+<p>tailor needs now a configuration file that collects the various bits
+of information it needs to do its job.</p>
+<p>The simplest way of starting out a new configuration is by omitting
+the <tt class="docutils literal"><span class="pre">--configfile</span></tt> command line option, and specifying the other as
+needed plus <tt class="docutils literal"><span class="pre">--verbose</span></tt>: in this situation, tailor will print out an
+equivalent configuration that you can redirect to a file, that you
+later will pass as <tt class="docutils literal"><span class="pre">--configfile</span></tt> (or simply <tt class="docutils literal"><span class="pre">-c</span></tt>).</p>
+<div class="section" id="examples">
+<h2><a class="toc-backref" href="#id34">Examples</a></h2>
+<ol class="arabic">
+<li><p class="first">Bootstrap a new tailored project, starting at upstream revision 10</p>
+<ol class="loweralpha">
+<li><p class="first">First create a config file:</p>
+<pre class="literal-block">
+$ tailor --verbose -s svn -R http://svn.server/path/to/svnrepo \
+         --module /Product/trunk -r 10 --subdir Product \
+         ~/darcs/MyProduct &gt; myproject.tailor
+</pre>
+</li>
+<li><p class="first">Modify it as you like (mostly adjusting root-directories and the
+like):</p>
+<pre class="literal-block">
+$ emacs myproject.tailor
+</pre>
+</li>
+<li><p class="first">Run tailor on it:</p>
+<pre class="literal-block">
+$ tailor --configfile myproject.tailor
+</pre>
+</li>
+</ol>
+</li>
+<li><p class="first">Bootstrap a new product, fetching its whole CVS repository and
+storing under SVN</p>
+<ol class="loweralpha">
+<li><p class="first">First create a config file:</p>
+<pre class="literal-block">
+$ tailor --verbose --source-kind cvs --target-kind svn \
+         --repository :pserver:cvs.zope.org:/cvs-repository \
+         --module CMF/CMFCore --revision INITIAL \
+         --target-repository file:///some/where/svnrepo \
+         --target-module / cmfcore &gt; cmfcore.tailor
+</pre>
+</li>
+<li><p class="first">Modify it as you like (mostly adjusting root-directories and the
+like):</p>
+<pre class="literal-block">
+$ emacs cmfcore.tailor
+</pre>
+</li>
+</ol>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p>By default, tailor uses &quot;.&quot; as <tt class="docutils literal"><span class="pre">subdir</span></tt>, to mean that
+it will extract upstream source directly inside the
+<tt class="docutils literal"><span class="pre">root-directory</span></tt>.</p>
+<p>This is known to cause problems with CVS as source, with
+which you could see some wierd error like</p>
+<pre class="literal-block">
+$ cvs -q -d ...:/cvsroot/mymodule checkout -d . ... mymodule
+cvs checkout: existing repository /cvsroot/mymodule does not match /cvsroot/mymodule/mymodule
+cvs checkout: ignoring module mymodule
+</pre>
+<p class="last">When this is the case, the culprit may be a CVS
+shortcoming not being able to handle <tt class="docutils literal"><span class="pre">-d</span> <span class="pre">.</span></tt> in the
+right way.  Specify a different <tt class="docutils literal"><span class="pre">subdir</span></tt> option to
+avoid the problem.</p>
+</div>
+<ol class="loweralpha" start="3">
+<li><p class="first">Run tailor on it once, to bootstrap the project:</p>
+<pre class="literal-block">
+$ tailor -D -v -c cmfcore.tailor
+</pre>
+<p>If the target repository is on the local filesystem (ie, it
+starts with <tt class="docutils literal"><span class="pre">file:///</span></tt>) and it does not exist, tailor
+creates a new empty Subversion repository at the specified
+location.</p>
+</li>
+</ol>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p>Before step d) below, you may want to install an
+appropriate hook in the repository to enable the
+propset command to operate on unversioned properties,
+as described in the <a class="reference external" href="http://svnbook.red-bean.com/en/1.0/ch05s02.html#svn-ch-5-sect-2.1">svn manual</a>. Then you can
+specify '--use-propset' option, and tailor will
+put the original author and timestamp in the proper
+svn metadata instead of appending them to the changelog.</p>
+<p class="last">Other than the annoying repository manual intervention,
+this <a class="reference external" href="http://svn.haxx.se/users/archive-2005-07/0605.shtml">thread</a> and this <a class="reference external" href="http://svn.haxx.se/users/archive-2005-03/0596.shtml">other</a> explain why using
+<tt class="docutils literal"><span class="pre">-r{DATE}</span></tt> may produce strange results with this setup.</p>
+</div>
+<ol class="loweralpha" start="4">
+<li><p class="first">Run tailor again and again, to sync up with latest changes:</p>
+<pre class="literal-block">
+$ tailor -v --configfile cmfcore.tailor
+</pre>
+</li>
+</ol>
+</li>
+</ol>
+<ol class="arabic" start="3">
+<li><p class="first">Given the configuration file shown below in <a class="reference internal" href="#config-file-format">Config file format</a>,
+the following command:</p>
+<pre class="literal-block">
+$ tailor --configfile example.tailor
+</pre>
+<p>is equivalent to this one:</p>
+<pre class="literal-block">
+$ tailor --configfile example.tailor tailor
+</pre>
+<p>in that they operate respectively on the default project(s) or
+the ones specified on the command line (and in this case there
+is just a single default project, tailor).</p>
+<p>This one instead:</p>
+<pre class="literal-block">
+$ tailor -c example.tailor tailor tailor-reverse
+</pre>
+<p>operates on both projects.</p>
+</li>
+</ol>
+</div>
+<div class="section" id="cvs-start-revision">
+<h2><a class="toc-backref" href="#id35">CVS start-revision</a></h2>
+<p>With CVS, you can specify a particular <em>point in time</em> specifying
+a <cite>start-revision</cite> with a timestamp like <tt class="docutils literal"><span class="pre">2001-12-25</span> <span class="pre">23:26:48</span> <span class="pre">UTC</span></tt>.</p>
+<p>To specify also a particular <cite>branch</cite>, prepend it before the
+timestamp, as in <tt class="docutils literal"><span class="pre">unstable-branch</span> <span class="pre">2001-12-25</span> <span class="pre">23:26:48</span> <span class="pre">UTC</span></tt>.</p>
+<p>To migrate the whole history of a specific <cite>branch</cite>, use something
+like <tt class="docutils literal"><span class="pre">somebranch</span> <span class="pre">INITIAL</span></tt>.</p>
+</div>
+</div>
+<div class="section" id="resolving-conflicts">
+<h1><a class="toc-backref" href="#id36">Resolving conflicts</a></h1>
+<p>Should one of the replayed changes generate any conflict, tailor
+will prompt the user to correct them. This is done after the upstream
+patch has been applied and before the final commit on the target
+system, so that manually tweaking the conflict can produce a clean
+patch.</p>
+</div>
+<div class="section" id="shortcomings">
+<h1><a class="toc-backref" href="#id37">Shortcomings</a></h1>
+<p>Tailor currently suffers of the following reported problems:</p>
+<ol class="loweralpha simple">
+<li>It does not handle &quot;empty&quot; CVS checkouts, in other words you cannot
+bootstrap a project that has nothing in its CVS upstream
+repository, or from a point in time where this condition was true.</li>
+<li>It's completely unsupported under Windows, evenif it now uses
+2.4's <a class="reference external" href="http://www.lysator.liu.se/~astrand/popen5/">subprocess</a> that seems able to hide Windows crazyness...</li>
+<li>ArX and Codeville are (currently) only supported as <em>target</em>;
+Baz and Tla only as <em>source</em>.</li>
+<li>Specifying <tt class="docutils literal"><span class="pre">--subdir</span> <span class="pre">.</span></tt> may not work, in particular when dealing
+with remote CVS repositories (it does when the CVS repository is
+on local machine).</li>
+</ol>
+<p>This list will always be incomplete, but I'll do my best to keep it
+short :-)</p>
+</div>
+<div class="section" id="config-file-format">
+<h1><a class="toc-backref" href="#id38">Config file format</a></h1>
+<p>When your project is composed by multiple upstream modules, it is
+easier to collect such information in a single file. This is done by
+specifying the <cite>--configfile</cite> option with a file name as argument. In
+this case, tailor will read the above information from a standard
+Python ConfigParser file.</p>
+<p>For example:</p>
+<pre class="literal-block">
+[DEFAULT]
+verbose = True
+projects = tailor
+
+[tailor]
+root-directory = /tmp/n9
+source = darcs:tailor
+target = svn:tailor
+state-file = tailor.state
+
+[tailor-reverse]
+root-directory = /tmp/n9
+source = svn:tailor
+target = darcs:tailor
+state-file = reverse.state
+
+[svn:tailor]
+repository = file:///tmp/testtai
+module = /project1
+subdir = svnside
+
+[darcs:tailor]
+repository = ~/WiP/cvsync
+subdir = darcside
+</pre>
+<p>The configuration may hold one or more <a class="reference internal" href="#projects">projects</a> and two or more
+<a class="reference internal" href="#repositories">repositories</a>: project names do not contains colons &quot;:&quot;,
+repository names must and the first part of the name before the
+colon specify the kind of the repository.  So, the above example
+contains two projects, one that goes from <cite>darcs</cite> to <cite>subversion</cite>, the
+other in the opposite direction.</p>
+<p>The <tt class="docutils literal"><span class="pre">[DEFAULT]</span></tt> section contains the default values, that will be
+used when a specific setting is missing from the particular section.</p>
+<p>You can specify on which project tailor should operate by
+giving its name on the command line, even more than one. When not
+explicitly given, tailor will look at <tt class="docutils literal"><span class="pre">projects</span></tt> in the
+<tt class="docutils literal"><span class="pre">[DEFAULT]</span></tt> section, and if its missing it will loop over all
+projects in the configuration.</p>
+<p>The following simpler config just go in one direction, for a single
+project, so no need neither for <tt class="docutils literal"><span class="pre">[DEFAULT].projects</span></tt> nor command
+line arguments. Also, notice the usage of the repository short cut:
+the <tt class="docutils literal"><span class="pre">source</span></tt> and <tt class="docutils literal"><span class="pre">target</span></tt> will be implicitly loaded from
+<cite>cvs:pxlib</cite> and <cite>hg:pxlib</cite> respectively:</p>
+<pre class="literal-block">
+[pxlib]
+source = cvs:
+target = hg:
+root-directory = ~/mypxlib
+start-revision = INITIAL
+subdir = pxlib
+
+[cvs:pxlib]
+repository = :pserver:anonymous&#64;cvs.sf.net:/cvsroot/pxlib
+module = pxlib
+
+[hg:pxlib]
+</pre>
+<p>This will use a single directory, <tt class="docutils literal"><span class="pre">pxlib</span></tt> to contain both the source
+and the target system. If you prefer keeping them separated, you just
+need to specify a different directory for each repository <a class="footnote-reference" href="#id9" id="id8">[3]</a>, as in:</p>
+<pre class="literal-block">
+[pxlib]
+source = cvs:pxlib
+target = hg:pxlib
+root-directory = ~/mypxlib
+start-revision = INITIAL
+
+[cvs:pxlib]
+repository = :pserver:anonymous&#64;cvs.sf.net:/cvsroot/pxlib
+module = pxlib
+subdir = original
+delay-before-apply = 10
+
+[hg:pxlib]
+subdir = migrated
+</pre>
+<p>This will extract upstream CVS sources into <tt class="docutils literal"><span class="pre">~/mypxlib/original</span></tt>,
+and create a new Mercurial repository in <tt class="docutils literal"><span class="pre">~/mypxlib/migrated</span></tt>.</p>
+<p>The following example shows the syntax of Baz sources:</p>
+<pre class="literal-block">
+[project]
+target = hg:target
+start-revision = base-0
+root-directory = /tmp/calife
+state-file = hidden
+source = baz:source
+
+[baz:source]
+module = calife--pam--3.0
+repository = roberto&#64;keltia.net--2003-depot
+subdir = tla
+
+[hg:target]
+repository = /tmp/HG/calife-pam
+subdir = hg
+</pre>
+<p>Note the usage of <tt class="docutils literal"><span class="pre">hidden</span></tt> for the state file name: given the
+importance of this file, that at the same time is of no interest by
+the user, this will store that information <cite>inside</cite> the same directory
+used by the target repository for its metadata, with the name
+<tt class="docutils literal"><span class="pre">tailor.state</span></tt>.  In this particular example, it will end up as
+<tt class="docutils literal"><span class="pre">/tmp/calife/hg/.hg/tailor.state</span></tt>.</p>
+<p>Last, a complete example used to migrate the whole <a class="reference external" href="http://www.monotone.ca/">Monotone</a> source
+repository under <a class="reference external" href="http://subversion.tigris.org/">Subversion</a>:</p>
+<pre class="literal-block">
+[DEFAULT]
+#debug = True
+#verbose = True
+start-revision = INITIAL
+root-directory = /tmp/rootdir-Monotone
+source = monotone:
+target = svn:
+source-repository = /home/user/Monotone/monotone-database.mtn
+target-repository = file:///tmp/svn-repository
+use-propset = True
+
+# Projects
+[net.venge.monotone.cvssync]
+
+[net.venge.monotone.cvssync.attrs]
+
+[net.venge.monotone.de]
+
+[net.venge.monotone.svn_import]
+
+[net.venge.monotone]
+
+
+# Sources
+[monotone:net.venge.monotone.cvssync]
+module = net.venge.monotone.cvssync
+subdir = mtnside-net.venge.monotone.cvssync
+
+[monotone:net.venge.monotone.cvssync.attrs]
+module = net.venge.monotone.cvssync.attrs
+subdir = mtnside-net.venge.monotone.cvssync.attrs
+
+[monotone:net.venge.monotone.de]
+module = net.venge.monotone.de
+subdir = mtnside-net.venge.monotone.de
+
+[monotone:net.venge.monotone.svn_import]
+module = net.venge.monotone.svn_import
+subdir = mtnside-net.venge.monotone.svn_import
+
+[monotone:net.venge.monotone]
+module = net.venge.monotone
+subdir = mtnside-net.venge.monotone
+
+
+# Targets
+[svn:net.venge.monotone.cvssync]
+module = branches/net.venge.monotone.cvssync
+subdir = svnside-net.venge.monotone.cvssync
+
+[svn:net.venge.monotone.cvssync.attrs]
+module = branches/net.venge.monotone.cvssync.attrs
+subdir = svnside-net.venge.monotone.cvssync.attrs
+
+[svn:net.venge.monotone.de]
+module = branches/net.venge.monotone.de
+subdir = svnside-net.venge.monotone.de
+
+[svn:net.venge.monotone.svn_import]
+module = branches/net.venge.monotone.svn_import
+subdir = svnside-net.venge.monotone.svn_import
+
+[svn:net.venge.monotone]
+module = trunk
+subdir = svnside-net.venge.monotone
+</pre>
+<table class="docutils footnote" frame="void" id="id9" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id8">[3]</a></td><td>NB: when the source and the target repositories specify
+different directories with the <tt class="docutils literal"><span class="pre">subdir</span></tt> option, tailor
+uses <tt class="docutils literal"><span class="pre">rsync</span></tt> to keep them in sync, so that tool needs
+to be installed.</td></tr>
+</tbody>
+</table>
+<div class="section" id="configuration-sections">
+<h2><a class="toc-backref" href="#id39">Configuration sections</a></h2>
+<div class="section" id="default">
+<h3><a class="toc-backref" href="#id40">Default</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">[DEFAULT]</span></tt> section in the configuration file may set the
+default value for any of the recognized options: when a value is
+missing from a specific section it is looked up in this section.</p>
+<p>One particular option, <tt class="docutils literal"><span class="pre">projects</span></tt>, is meaningful only in the
+<tt class="docutils literal"><span class="pre">[DEFAULT]</span></tt> section: it's a comma separated list of project names,
+the one that will be operated on by tailor when no project is
+specified on the command line.  When the there are no <tt class="docutils literal"><span class="pre">projects</span></tt>
+setting nor any on the command line, tailor activates all configured
+projects, in order of appearance in the config file.</p>
+</div>
+<div class="section" id="projects">
+<h3><a class="toc-backref" href="#id41">Projects</a></h3>
+<p>A project is identified by a section whose name does not contain any
+colon (&quot;:&quot;) character, and configured with the following values:</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">If a particular option is missing from the project section,
+its value is obtained looking up the same option in the
+<tt class="docutils literal"><span class="pre">[DEFAULT]</span></tt> section.</p>
+</div>
+<dl class="docutils">
+<dt>root-directory <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>This is where all the fun will happen: this directory will contain
+the source and the target working copy, and usually the state and
+the log file. It supports the conventional <cite>~user</cite> to indicate user's
+home directory and defaults to the current working directory.</dd>
+<dt>subdir <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>This is the subdirectory, relative to the <cite>root-directory</cite>, where
+tailor will extract the source working copy. It may be '.' for some
+backend kinds. The source and target backends will use this value
+if they don't explicitly override it.</dd>
+<dt>state-file <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>Name of the state file needed to store tailor last activity. When
+this is set to <tt class="docutils literal"><span class="pre">hidden</span></tt>, the state file will be named
+<tt class="docutils literal"><span class="pre">tailor.state</span></tt>, possibly under the target's <tt class="docutils literal"><span class="pre">METADIR</span></tt>.</dd>
+<dt>source <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>The source repository: a repository name is something like
+&quot;darcs:somename&quot;, that will be loaded from the homonymous section
+in the configuration. As a short cut, the &quot;somename&quot; part may be
+omitted: in that case, the project name will be appended to the
+specified prefix.</dd>
+<dt>target <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>The counterpart of <cite>source</cite>, the repository that will receive the
+changes coming from there.</dd>
+</dl>
+<p>Non mandatory options:</p>
+<dl class="docutils">
+<dt>verbose <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd>Print the commands as they are executed.</dd>
+<dt>debug <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd>Print also their output.</dd>
+<dt>before-commit <span class="classifier-delimiter">:</span> <span class="classifier">tuple</span></dt>
+<dd>This is a function name, or a sequence of function names enclosed
+by brackets, that will be executed on each changeset just before
+it get replayed on the target system: this may be used to perform
+any kind of alteration on the content of the changeset, or to skip
+some of them.</dd>
+<dt>after-commit <span class="classifier-delimiter">:</span> <span class="classifier">tuple</span></dt>
+<dd>This is a function name, or a sequence of function names enclosed
+by brackets, that will be executed on each changeset just after
+the commit on the target system: this may be used for example to
+create a tag.</dd>
+<dt>subdir <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>The name of the subdirectory, under <tt class="docutils literal"><span class="pre">root-directory</span></tt>, that will
+contain the source and target repositories/working directories.</dd>
+<dt>start-revision <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>This identifies from when tailor should start the migration. It can
+be either <tt class="docutils literal"><span class="pre">INITIAL</span></tt>, to indicate the start of the history, or
+<tt class="docutils literal"><span class="pre">HEAD</span></tt> to indicate the current latest changeset, or a backend
+specific way of indicate a particular revision/tag in the history.
+See also <a class="reference internal" href="#cvs-start-revision">CVS start-revision</a> above.</dd>
+<dt>patch-name-format <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd><p class="first">Some backends have a distinct notion of <cite>patch name</cite> and <cite>change
+log</cite>, others just suggest a policy that the first line of the
+message is a summary, the rest if present is a more detailed
+description of the change.  With this option you can control the
+format of the name, or of the first line of the changelog.</p>
+<p>The prototype may contain <tt class="docutils literal"><span class="pre">%(keyword)s</span></tt> such as 'author', 'date',
+'revision', 'firstlogline', 'remaininglog' or 'project'.  It
+defaults to <tt class="docutils literal"><span class="pre">[%(project)s</span> <span class="pre">&#64;</span> <span class="pre">%(revision)s]</span></tt> <a class="footnote-reference" href="#id11" id="id10">[4]</a>.</p>
+<p>When you set it empty, as in</p>
+<pre class="literal-block">
+[project]
+patch-name-format = &quot;&quot;
+</pre>
+<p class="last">tailor will keep the original changelog as is.</p>
+</dd>
+<dt>remove-first-log-line <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd><p class="first">Remove the first line of the upstream changelog. This is intended to
+go in pair with <tt class="docutils literal"><span class="pre">patch-name-format</span></tt>, when using its 'firstlogline'
+variable to build the name of the patch.  The default is <tt class="docutils literal"><span class="pre">False</span></tt>.</p>
+<p>A reasonable usage is:</p>
+<pre class="last literal-block">
+[DEFAULT]
+patch-name-format=[%(project)s &#64; %(revision)s]: %(firstlogline)s
+remove-first-log-line=True
+</pre>
+</dd>
+<dt>refill-changelogs <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd>Off by default, when active tailor reformats every changelog before
+committing on the target system.</dd>
+</dl>
+<table class="docutils footnote" frame="void" id="id11" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id10">[4]</a></td><td>Modifying the changelog may have subtle consequences!
+Under darcs, for example, you may hit <a class="reference external" href="http://bugs.darcs.net/issue772">issue772</a> by producing
+hash collisions, that happens when two distinct patches carry
+the same &quot;unique&quot; identifier (the hash is computed using
+<em>date</em>, <em>author</em>, <em>changelog</em> and other details, but <strong>not</strong>
+the actual content): the default setting, that adds a
+differentiating prefix, is safer from that point of view.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="repositories">
+<h3><a class="toc-backref" href="#id42">Repositories</a></h3>
+<p>All the section whose name contains at least one colon character
+denote a repository.  A single repository may be shared by zero, one or
+more projects.  The first part of the name up to the first colon
+indicates the <cite>kind</cite> of the repository, one of <tt class="docutils literal"><span class="pre">aegis</span></tt>, <tt class="docutils literal"><span class="pre">arx</span></tt>,
+<tt class="docutils literal"><span class="pre">baz</span></tt>, <tt class="docutils literal"><span class="pre">bzr</span></tt>, <tt class="docutils literal"><span class="pre">cdv</span></tt>, <tt class="docutils literal"><span class="pre">cvs</span></tt>, <tt class="docutils literal"><span class="pre">darcs</span></tt>, <tt class="docutils literal"><span class="pre">git</span></tt>, <tt class="docutils literal"><span class="pre">hg</span></tt>,
+<tt class="docutils literal"><span class="pre">monotone</span></tt>, <tt class="docutils literal"><span class="pre">p4</span></tt>,``svn`` and <tt class="docutils literal"><span class="pre">tla</span></tt>.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">If a particular option is missing from the repository section,
+its value is obtained looking up the same option in the
+section of the project <em>currently</em> using the repository,
+falling back to the <tt class="docutils literal"><span class="pre">[DEFAULT]</span></tt> section.</p>
+</div>
+<p>Some options may be shared with others repositories, like in the
+following example, where the common settings for the target monotone
+repository are set just once:</p>
+<pre class="literal-block">
+[DEFAULT]
+target-repository = /bigdisk/my-huge-repository.mtn
+target-keyid = test&#64;example.com
+target-passphrase = lala
+source-repository = http://svn.someserver.com
+
+[productA]
+target = monotone:productA
+source = svn:sourceA
+
+[productB]
+target = monotone:productB
+source = darcs:sourceB
+
+[productC]
+target = monotone:productC
+source = svn:sourceC
+
+[productC_darcs]
+target = darcs:
+source = svn:sourceC
+
+...
+
+[monotone:productA]
+module = every.thing.productA
+
+[monotone:productB]
+module = every.thing.productB
+
+[monotone:productC]
+module = every.thing.productC
+
+[svn:sourceA]
+module = /productA
+
+[darcs:sourceB]
+repository = http://some.server.com/darcs/productB
+
+[svn:sourceC]
+module = /productC
+</pre>
+<p>For some backends, for example for those that like <tt class="docutils literal"><span class="pre">darcs</span></tt> do not
+make a distinction between <cite>repository</cite> and <cite>working copy</cite> and thus
+the former may be assumed by <tt class="docutils literal"><span class="pre">root-directory</span></tt> (and possibly
+<tt class="docutils literal"><span class="pre">subdir</span></tt>), the config section may be completely omitted, as done for
+<cite>productC_darcs</cite> above.</p>
+<div class="section" id="common-options">
+<h4><a class="toc-backref" href="#id43">Common options</a></h4>
+<dl class="docutils">
+<dt>repository <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>When a repository is used as a <cite>source</cite>, it must indicate its origin
+with <tt class="docutils literal"><span class="pre">repository</span></tt>, and for some backends also a <tt class="docutils literal"><span class="pre">module</span></tt>, but
+are not required when it's a target system, even if some backend may
+use the information to create the target repository (like <tt class="docutils literal"><span class="pre">svn</span></tt>
+backend does).</dd>
+<dt>subdir <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd><p class="first">When the <cite>source</cite> and <cite>target</cite> repositories use different
+subdirectories, tailor uses <tt class="docutils literal"><span class="pre">rsync</span></tt> 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.</p>
+<p class="last">This defaults to the project's setting.</p>
+</dd>
+<dt>command <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>Backends based on external command line tool such as <em>svn</em> or
+<em>darcs</em> offers this option to impose a particular external binary to
+be used, as done below in the example about <a class="reference internal" href="#disjunct-working-directories">disjunct working
+directories</a>.</dd>
+<dt>python-path <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>For pythonique backends such as <em>bzr</em> and <em>hg</em> this indicates
+where the respective library is located.</dd>
+<dt>encoding <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd><p class="first">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:</p>
+<pre class="last literal-block">
+python -m locale
+</pre>
+</dd>
+<dt>encoding-errors-policy <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>By default is <em>strict</em>, that means that Python will raise an
+exception on Unicode conversion errors. Valid options are <em>ignore</em>
+that simply skips offending glyphs and <em>replace</em> where unrecognized
+entities are replaced with a place holder.</dd>
+<dt>delay-before-apply <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
+<dd><p class="first">Sometime the migration is fast enough to put the upstream server
+under an excessive load. When this is the case, you may specify
+<tt class="docutils literal"><span class="pre">delay-before-apply</span> <span class="pre">=</span> <span class="pre">5</span></tt>, that is the number of seconds tailor
+will wait before applying each changeset.</p>
+<p class="last">It defaults to <em>None</em>, ie no delay at all.</p>
+</dd>
+<dt>post-commit-check <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd><p class="first">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.</p>
+<p class="last"><em>True</em> by default.</p>
+</dd>
+</dl>
+</div>
+<div class="section" id="id12">
+<h4><a class="toc-backref" href="#id44">aegis</a></h4>
+<!-- no specific option -->
+<p>Sample config fragment:</p>
+<pre class="literal-block">
+[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
+</pre>
+</div>
+<div class="section" id="id13">
+<h4><a class="toc-backref" href="#id45">arx</a></h4>
+<!-- no specific options -->
+</div>
+<div class="section" id="id14">
+<h4><a class="toc-backref" href="#id46">baz</a></h4>
+<!-- no specific options -->
+</div>
+<div class="section" id="bzr">
+<h4><a class="toc-backref" href="#id47">bzr</a></h4>
+<!-- no specific options -->
+</div>
+<div class="section" id="cdv">
+<h4><a class="toc-backref" href="#id48">cdv</a></h4>
+<!-- no specific options -->
+</div>
+<div class="section" id="id15">
+<h4><a class="toc-backref" href="#id49">cvs</a></h4>
+<dl class="docutils">
+<dt>changeset-threshold <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
+<dd><p class="first">Maximum number of seconds allowed to separated commits to different
+files for them to be considered part of the same changeset.</p>
+<p class="last">180 by default.</p>
+</dd>
+<dt>freeze-keywords <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd><p class="first">With this enabled (it is off by default) tailor will use <tt class="docutils literal"><span class="pre">-kk</span></tt> flag
+on <cite>checkouts</cite> and <cite>updates</cite> to turn off the keyword expansion. This
+may help minimizing the chance of spurious conflicts with later
+merges between different branches.</p>
+<p class="last"><em>False</em> by default.</p>
+</dd>
+<dt>tag-entries <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd><p class="first">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 <tt class="docutils literal"><span class="pre">tag_entries</span> <span class="pre">=</span> <span class="pre">False</span></tt>.</p>
+<p class="last"><em>True</em> by default.</p>
+</dd>
+<dt>trim-module-components <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
+<dd><p class="first">When the checked out tree involves <a class="reference external" href="http://ximbiot.com/cvs/wiki/index.php?title=CVS--Concurrent_Versions_System_v1.12.12.1:_Reference_manual_for_Administrative_files#The_modules_file">CVS modules</a> on the server
+Tailor fails to build up the ChangeSets view from the <tt class="docutils literal"><span class="pre">cvs</span> <span class="pre">rlog</span></tt>
+output, since in that case the paths that Tailor finds in the log
+refers to the real location of the entries <em>on the server</em>, 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.</p>
+<p>Given that most of the time it's simply a matter of a common prefix,
+this option offers the so called &quot;far-from-perfect-poor-man-workaround&quot;
+to the CVS/Tailor shortcoming, until a better solution arises.</p>
+<p>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.</p>
+<p class="last"><em>0 (zero)</em> by default.</p>
+</dd>
+</dl>
+</div>
+<div class="section" id="cvsps">
+<h4><a class="toc-backref" href="#id50">cvsps</a></h4>
+<dl class="docutils">
+<dt>freeze-keywords <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd><p class="first">With this enabled (it is off by default) tailor will use <tt class="docutils literal"><span class="pre">-kk</span></tt> flag
+on <cite>checkouts</cite> and <cite>updates</cite> to turn off the keyword expansion. This
+may help minimizing the chance of spurious conflicts with later
+merges between different branches.</p>
+<p class="last"><em>False</em> by default.</p>
+</dd>
+<dt>tag-entries <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd><p class="first">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 <tt class="docutils literal"><span class="pre">tag_entries</span> <span class="pre">=</span> <span class="pre">False</span></tt>.</p>
+<p class="last"><em>True</em> by default.</p>
+</dd>
+</dl>
+</div>
+<div class="section" id="id17">
+<h4><a class="toc-backref" href="#id51">darcs</a></h4>
+<dl class="docutils">
+<dt>init-options <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>By default empty, may specify options used to initialize the
+target repository, for example to use the newer <tt class="docutils literal"><span class="pre">darcs-2</span></tt>.</dd>
+<dt>look-for-adds <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd>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 <tt class="docutils literal"><span class="pre">record</span> <span class="pre">--look-for-adds</span></tt>.</dd>
+<dt>replace-badchars <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd><p class="first">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:</p>
+<pre class="last literal-block">
+{
+  '\xc1': '&amp;#193;',
+  '\xc9': '&amp;#201;',
+  '\xcd': '&amp;#205;',
+  '\xd3': '&amp;#211;',
+  '\xd6': '&amp;#214;',
+  '\xd5': '&amp;#336;',
+  '\xda': '&amp;#218;',
+  '\xdc': '&amp;#220;',
+  '\xdb': '&amp;#368;',
+  '\xe1': '&amp;#225;',
+  '\xe9': '&amp;#233;',
+  '\xed': '&amp;#237;',
+  '\xf3': '&amp;#243;',
+  '\xf6': '&amp;#246;',
+  '\xf5': '&amp;#337;',
+  '\xfa': '&amp;#250;',
+  '\xfc': '&amp;#252;',
+  '\xfb': '&amp;#369;',
+  '\xf1': '&amp;#241;',
+  '\xdf': '&amp;#223;',
+  '\xe5': '&amp;#229;'
+}
+</pre>
+</dd>
+<dt>start-revision <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd><p class="first">Under darcs this may be either the name of a tag or the hash of an
+arbitrary patch in the repository, plus the ordinary <tt class="docutils literal"><span class="pre">INITIAL</span></tt> or
+<tt class="docutils literal"><span class="pre">HEAD</span></tt> symbols.</p>
+<div class="note last">
+<p class="first admonition-title">Note</p>
+<p class="last">If you want to start from a particular patch, giving its
+hash value as <tt class="docutils literal"><span class="pre">start-revision</span></tt>, you <strong>must</strong> use a
+<tt class="docutils literal"><span class="pre">subdir</span></tt> different from <tt class="docutils literal"><span class="pre">&quot;.&quot;</span></tt>. <a class="footnote-reference" href="#id21" id="id18">[5]</a></p>
+</div>
+</dd>
+<dt>split-initial-changeset-level <span class="classifier-delimiter">:</span> <span class="classifier">integer</span></dt>
+<dd><p class="first">Sometime it's desiderable to avoid the impact of the huge patch
+produced by the bootstrap step, that's basically a snapshot of the
+<em>whole</em> 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 <em>tag</em> will comprehend all the changesets.</p>
+<p class="last"><em>0</em> by default.</p>
+</dd>
+</dl>
+<div class="section" id="big-repositories">
+<h5><a class="toc-backref" href="#id52">Big repositories</a></h5>
+<p>To migrate a big darcs repository it is faster doing a <em>chunked
+approach</em>, that is using an intermediary repository where you pull say
+a couple of hundreds patches at a time from the real source
+repository, and then run tailor, in a loop. The following script
+illustrates the method:</p>
+<pre class="literal-block">
+mkdir /tmp/intermediary-repo
+cd /tmp/intermediary-repo
+darcs init --darcs-2
+while python -c &quot;print 'y'*200+'d'&quot; | darcs pull --quiet real-source-repo
+do
+  tailor -c from-intermediary.tailor
+done
+</pre>
+<p>When darcs is the <em>target</em>, consider setting a value of 1 or even 2
+for the option <cite>split-initial-changeset-level</cite>.</p>
+</div>
+</div>
+<div class="section" id="git-target">
+<h4><a class="toc-backref" href="#id53">git target</a></h4>
+<dl class="docutils">
+<dt>parent-repo <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd><p class="first">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 <tt class="docutils literal"><span class="pre">repository</span></tt> is not set either, the branch has no
+parent.</p>
+<p class="last">The alternative is to specify a <tt class="docutils literal"><span class="pre">repository</span></tt> parameter, to contain
+all git branches.  The .git directory in the working copy for each
+branch will then only contain the <tt class="docutils literal"><span class="pre">.git/index</span></tt> file.</p>
+</dd>
+<dt>branch <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>The name of the branch to which to commit.  It is only used in
+single-repository mode (using <tt class="docutils literal"><span class="pre">repository</span></tt>, see above).  The
+default is to use the &quot;master&quot; branch.</dd>
+<dt>branchpoint <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd><p class="first">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 &quot;tag~2&quot;, if you want to
+correct the idea of where the branchpoint is).</p>
+<p class="last">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.</p>
+</dd>
+<dt>overwrite-tags <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd><p class="first">By default the backend does <em>not</em> 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.</p>
+<p class="last"><em>False</em> by default.</p>
+</dd>
+</dl>
+</div>
+<div class="section" id="hg">
+<h4><a class="toc-backref" href="#id54">hg</a></h4>
+<!-- no specific options -->
+</div>
+<div class="section" id="id19">
+<h4><a class="toc-backref" href="#id55">monotone</a></h4>
+<dl class="docutils">
+<dt>keyid <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>Monotone key id to use for commits. The specified key
+must exist on keystore. Takes precedence
+over keygenid.</dd>
+<dt>keygenid <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>Id of a new keypair to generate and store in the
+repository.
+The keypair is used for commits. Ignored if keyid is
+specified.</dd>
+<dt>passphrase <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>Passphrase to use for commits. Must be specified unless you have one
+on your .monotonerc file</dd>
+<dt>custom-lua <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd>Optional custom lua script. If present, is written into _MTN/monotonerc.</dd>
+</dl>
+</div>
+<div class="section" id="p4">
+<h4><a class="toc-backref" href="#id56">p4</a></h4>
+<dl class="docutils">
+<dt>depot-path <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd><p class="first">The path within the depot indicating the root of all files that will be
+replicated.</p>
+<p>This is used both for determining changes as well as mapping
+file locations from changesets to the filesystem.</p>
+<p class="last">Example:  <tt class="docutils literal"><span class="pre">//depot/project/main/</span></tt></p>
+</dd>
+<dt>p4-client <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd><p class="first">The perforce client spec to use.</p>
+<p class="last">Example:  <tt class="docutils literal"><span class="pre">myhostname-tailor</span></tt></p>
+</dd>
+<dt>p4-port <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd><p class="first">The address of the perforce server.</p>
+<p class="last">Example: <tt class="docutils literal"><span class="pre">perforce.mycompany.com:1666</span></tt></p>
+</dd>
+</dl>
+</div>
+<div class="section" id="svn">
+<h4><a class="toc-backref" href="#id57">svn</a></h4>
+<dl class="docutils">
+<dt>filter-badchars <span class="classifier-delimiter">:</span> <span class="classifier">bool (or string)</span></dt>
+<dd><p class="first">Activate (with <em>True</em>) or activate and specify (with a <em>string</em>) the
+filter on the svn log to eliminate illegal XML characters.</p>
+<p><em>False</em> by default, when set to <em>True</em> the following characters are
+washed out from the upstream changes:</p>
+<pre class="literal-block">
+allbadchars = &quot;\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09&quot; \
+              &quot;\x0B\x0C\x0E\x0F\x10\x11\x12\x13\x14\x15&quot; \
+              &quot;\x16\x17\x18\x19\x1A\x1B\x1C\x1D\x1E\x1F\x7f&quot;
+</pre>
+<p>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:</p>
+<pre class="last literal-block">
+filter-badchars=\x00\x01
+</pre>
+</dd>
+<dt>use-propset <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd><p class="first">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
+<tt class="docutils literal"><span class="pre">hooks/pre-revprop-change</span></tt> script inside the repository, so no
+other intervention is needed.</p>
+<p class="last"><em>False</em> by default.</p>
+</dd>
+<dt>propset-date <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd>By default <em>True</em>, can be used to avoid setting the <tt class="docutils literal"><span class="pre">svn:date</span></tt>
+property on the Subversion revision, and thus problem with
+<tt class="docutils literal"><span class="pre">-r{DATE}</span></tt> mentioned above.  When this is <em>False</em>, the original
+timestamp gets appended to the revision log.</dd>
+<dt>use-limit <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd>By default <em>True</em>, should be set to <em>False</em> when using old
+Subversion clients, since <tt class="docutils literal"><span class="pre">log</span> <span class="pre">--limit</span></tt> was introduced with
+version 1.2. By using this option tailor can fetch just the
+revision it needs, instead of transfering whole history log.</dd>
+<dt>commit-all-files <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd>By default <em>True</em>, commits all files from current changeset. Lets
+Subversion check the changes self.
+Set it to <em>False</em>, then whish to commits only changed files, that
+tailor detects, perhaps a network speedup.  But a  <em>False</em> 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 <em>True</em>.</dd>
+<dt>trust-root <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd>Tailor by default verifies that the specified <tt class="docutils literal"><span class="pre">repository</span></tt>
+effectively points to the root of a Subversion repository,
+eventually splitting it and adjusting <tt class="docutils literal"><span class="pre">module</span></tt> accordingly.  This
+is sometimes undesiderable, for example when the root isn't public
+and cannot be listed.  Setting this option to <em>True</em> disable the
+check and tailor takes the given <tt class="docutils literal"><span class="pre">repository</span></tt> and <tt class="docutils literal"><span class="pre">module</span></tt> as-is.</dd>
+<dt>ignore-externals <span class="classifier-delimiter">:</span> <span class="classifier">bool</span></dt>
+<dd>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.</dd>
+<dt>svn-tags <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd><p class="first">Name of the directory used for tags: tailor will copy tagged
+revisions under this directory.</p>
+<p class="last"><tt class="docutils literal"><span class="pre">/tags</span></tt> by default.</p>
+</dd>
+<dt>svn-branches <span class="classifier-delimiter">:</span> <span class="classifier">string</span></dt>
+<dd><p class="first">Name of the directory used for branches: tailor will copy branches
+under that directory.</p>
+<p><tt class="docutils literal"><span class="pre">/branches</span></tt> by default.</p>
+<div class="note last">
+<p class="first admonition-title">Note</p>
+<p>Target module for branches <strong>must</strong> start with <tt class="docutils literal"><span class="pre">branches/</span></tt>.
+Every branch must configure in a single-repository mode.</p>
+<p class="last">Example: <tt class="docutils literal"><span class="pre">module</span> <span class="pre">=</span> <span class="pre">branches/branch.name</span></tt></p>
+</div>
+</dd>
+</dl>
+</div>
+<div class="section" id="id20">
+<h4><a class="toc-backref" href="#id58">tla</a></h4>
+<!-- no specific options -->
+<table class="docutils footnote" frame="void" id="id21" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id18">[5]</a></td><td>This is because when you use <tt class="docutils literal"><span class="pre">subdir</span> <span class="pre">=</span> <span class="pre">.</span></tt> tailor uses
+<tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">pull</span></tt> instead of <tt class="docutils literal"><span class="pre">darcs</span> <span class="pre">get</span></tt>, and the former does
+not accept the option <tt class="docutils literal"><span class="pre">--to-match</span></tt>.</td></tr>
+</tbody>
+</table>
+</div>
+</div>
+</div>
+<div class="section" id="disjunct-working-directories">
+<h2><a class="toc-backref" href="#id59">Disjunct working directories</a></h2>
+<p>A particular case happens when the <tt class="docutils literal"><span class="pre">subdir</span></tt> specified in the
+<em>source</em> is different from the one in <em>target</em> as in:</p>
+<pre class="literal-block">
+[tailor-d1-to-d2]
+patch-name-format = ''
+source = darcs:source
+target = darcs:target
+start-revision = INITIAL
+
+[darcs:source]
+repository = http://darcs.arstecnica.it/tailor
+subdir = tailor_d1
+
+[darcs:target]
+darcs-command = /usr/local/bin/darcs2
+init-options = --darcs-2
+subdir = tailor_d2
+</pre>
+<p>In this particular case, the <em>kind</em> may be the same, allowing
+particular migrations between the same kind of VC, as showed.</p>
+<p>Tailor will use <tt class="docutils literal"><span class="pre">rsync</span></tt> to move the changes applied in the
+source subdirectory to the target one.</p>
+</div>
+<div class="section" id="using-a-python-script-as-configuration-file">
+<h2><a class="toc-backref" href="#id60">Using a Python script as configuration file</a></h2>
+<p>Instead of executing <tt class="docutils literal"><span class="pre">tailor</span> <span class="pre">--configfile</span> <span class="pre">project.tailor.conf</span></tt>
+you can prepend the following signature to the config itself:</p>
+<pre class="literal-block">
+#!/usr/bin/env /path/to/tailor
+</pre>
+<p>Giving execute mode to it will permit the launch of the tailor
+process by running the config script directly:</p>
+<pre class="literal-block">
+$ ./project.tailor.conf
+</pre>
+<p>When a config file is signed in this way <a class="footnote-reference" href="#id24" id="id22">[6]</a>, either you pass it as
+argument to <tt class="docutils literal"><span class="pre">--configfile</span></tt> or executed as above, tailor will
+actually execute it as a full fledged Python script, that may define
+functions that alter the behaviour of tailor itself.</p>
+<div class="section" id="pre-commit-and-post-commit-hooks">
+<h3><a class="toc-backref" href="#id61">Pre-commit and post-commit hooks</a></h3>
+<p>A common usage of this functionality is to define so called <cite>hooks</cite>,
+sequences of functions that are executed at particular points in
+the tailorization process.</p>
+<div class="section" id="example-1">
+<h4><a class="toc-backref" href="#id62">Example 1</a></h4>
+<p>Just to illustrate the functionality, consider the following example:</p>
+<pre class="literal-block">
+#!/usr/bin/env tailor
+
+&quot;&quot;&quot;
+[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
+&quot;&quot;&quot;
+
+def before(wd, changeset):
+    print &quot;BEFORE&quot;, changeset
+    changeset.author = &quot;LELE&quot;
+    return changeset
+
+def after(wd, changeset):
+    print &quot;AFTER&quot;, changeset
+</pre>
+<p>With the above in a <cite>script</cite> called say <tt class="docutils literal"><span class="pre">tester</span></tt>, just doing:</p>
+<pre class="literal-block">
+$ chmod 755 tester
+$ ./tester
+</pre>
+<p>will migrate the history from a darcs repository to a Bazaar one,
+forcing the author to a well-known name :-)</p>
+</div>
+<div class="section" id="example-2">
+<h4><a class="toc-backref" href="#id63">Example 2</a></h4>
+<p>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:</p>
+<pre class="literal-block">
+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
+</pre>
+<p>It uses zooko's pyutil <a class="footnote-reference" href="#id25" id="id23">[7]</a> toolset.  Another approach would be looping
+over changeset.entries and operating only on added or changed entries.</p>
+</div>
+<div class="section" id="example-3">
+<h4><a class="toc-backref" href="#id64">Example 3</a></h4>
+<p>This loops over the file touched by a particular changeset and tries
+to reindent it if it's a Python file:</p>
+<pre class="literal-block">
+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 &quot;got an exception from attempt to reindent&quot; \
+                  &quot; (maybe that file wasn't Python code?):&quot; \
+                  &quot; changeset entry: %s, exception:&quot; \
+                  &quot; %s %s %s&quot; % (entry, type(le), repr(le),
+                                 hasattr(le, 'args') and le.args,)
+            raise le
+    return True
+</pre>
+<p>You have to find reindent.py in your Python distribution and put it
+in your python path. <strong>Beware</strong> that this has some drawbacks: be sure
+to read <a class="reference external" href="http://progetti.arstecnica.it/tailor/ticket/8">ticket 8</a> annotations if you use it.</p>
+<table class="docutils footnote" frame="void" id="id24" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id22">[6]</a></td><td>Tailor does actually read just the first two bytes from the
+file, and compare them with &quot;#!&quot;, so you are free to choose
+whatever syntax works in your environment.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id25" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id23">[7]</a></td><td>Available either at <a class="reference external" href="https://yumyum.zooko.com:19144/pub/repos/pyutil">https://yumyum.zooko.com:19144/pub/repos/pyutil</a>
+or <a class="reference external" href="http://zooko.com/repos/pyutil">http://zooko.com/repos/pyutil</a>.</td></tr>
+</tbody>
+</table>
+</div>
+</div>
+</div>
+<div class="section" id="state-file">
+<h2><a class="toc-backref" href="#id65">State file</a></h2>
+<p>The state file stores two things: the last upstream revision that
+has been applied to the tree, and a sequence of pending (not yet
+applied) changesets, that may be empty. In the latter case, tailor
+will fetch latest changes from the upstream repository.</p>
+</div>
+<div class="section" id="logging">
+<h2><a class="toc-backref" href="#id66">Logging</a></h2>
+<p>Tailor uses the Python's logging module to emit noise. Its basic
+configuration is hardwired and corresponds to the following:</p>
+<pre class="literal-block">
+[formatters]
+keys = console
+
+[formatter_console]
+format =  %(asctime)s [%(levelname).1s] %(message)s
+datefmt = %H:%M:%S
+
+[loggers]
+keys = root
+
+[logger_root]
+level = INFO
+handlers = console
+
+[handlers]
+keys = console
+
+[handler_console]
+class = StreamHandler
+formatter = console
+args = (sys.stdout,)
+level = INFO
+</pre>
+<p>Another handler is added at runtime that appends any message in a file
+named <tt class="docutils literal"><span class="pre">projectname.log</span></tt> inside the root directory. This file
+contains much more details than those usually reaching the console,
+and may be of some help to understand what went wrong.</p>
+<p>However, you can completely override the default adding a
+<em>supersection</em> <tt class="docutils literal"><span class="pre">[[logging]]</span></tt> to the configuration file, something
+like:</p>
+<pre class="literal-block">
+# ... usual tailor config ...
+[project]
+source = bzr:source
+target = hg:target
+
+# Here ends tailor config, and start the one for the logging
+# module
+
+[[logging]]
+
+[logger_tailor.BzrRepository]
+level = DEBUG
+handlers = tailor.source
+
+[handler_tailor.source]
+class = SMTPHandler
+args = ('localhost', 'from&#64;abc', ['tailor&#64;abc'], 'Tailor log')
+</pre>
+</div>
+</div>
+<div class="section" id="further-help">
+<h1><a class="toc-backref" href="#id67">Further help</a></h1>
+<p>See the output of <tt class="docutils literal"><span class="pre">tailor</span> <span class="pre">-h</span></tt> for some further tips.  The official
+documentation is available as a set of <a class="reference external" href="http://progetti.arstecnica.it/tailor/">wiki pages</a> managed by a
+<a class="reference external" href="http://trac.edgewall.org/">Trac</a> instance, but there is also <a class="reference external" href="http://www.darcs.net/DarcsWiki/Tailor">this page</a> on the Darcs wiki
+that may give you some other hints.</p>
+<p>The development of Tailor is mainly driven by user requests at this
+point, and the preferred comunication medium is the dedicated <a class="reference external" href="http://lists.zooko.com/mailman/listinfo/tailor">mailing
+list</a> <a class="footnote-reference" href="#id27" id="id26">[8]</a>.</p>
+<p>I will be more than happy to answer any doubt, question or suggestion
+you may have on it. I'm usually hanging out as &quot;lelit&quot; on the
+<tt class="docutils literal"><span class="pre">#tailor</span></tt> IRC channel on the <cite>freenode.net</cite> network. Do not hesitate
+to contact me either by email or chatting there.</p>
+<table class="docutils footnote" frame="void" id="id27" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id26">[8]</a></td><td>I wish to say a big <cite>Thank you</cite> to <a class="reference external" href="mailto:zooko&#64;zooko.com">Zooko</a>,
+for hosting the ML and for supporting Tailor in several ways,
+from suggestions to bug reporting and fixing.</td></tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="authors">
+<h1><a class="toc-backref" href="#id68">Authors</a></h1>
+<p>Lele Gaifax &lt;<a class="reference external" href="mailto:lele&#64;nautilus.homeip.net">lele&#64;nautilus.homeip.net</a>&gt;</p>
+<p>Since I'm not currently using all the supported systems (so little
+time, so many VCSs...) I'm not in position to test them out properly,
+but I'll do my best to keep them in sync, maybe with your support :-)</p>
+<div class="section" id="aegis-support">
+<h2><a class="toc-backref" href="#id69">Aegis support</a></h2>
+<p><a class="reference external" href="http://aegis.sourceforge.net/">Aegis</a> support was contributed by <a class="reference external" href="mailto:walter.franzini&#64;gmail.com">Walter Franzini</a>.</p>
+</div>
+<div class="section" id="arx-support">
+<h2><a class="toc-backref" href="#id70">ArX support</a></h2>
+<p><a class="reference external" href="http://www.nongnu.org/arx/">ArX</a> support was contributed by <a class="reference external" href="mailto:wlandry&#64;caltech.edu">Walter Landry</a>.</p>
+</div>
+<div class="section" id="bazaar-support">
+<h2><a class="toc-backref" href="#id71">Bazaar support</a></h2>
+<p><a class="reference external" href="http://bazaar-vcs.org/">Bazaar</a> support was contributed by <a class="reference external" href="mailto:jrydberg&#64;gnu.org">Johan Rydberg</a>.  Nowadays it's being maintained by <a class="reference external" href="mailto:lalo.martins&#64;gmail.com">Lalo Martins</a>.</p>
+</div>
+<div class="section" id="git-support">
+<h2><a class="toc-backref" href="#id72">Git support</a></h2>
+<p><a class="reference external" href="http://git.or.cz/">Git</a> support was contributed by <a class="reference external" href="mailto:tmokros&#64;tmokros.net">Todd Mokros</a>.</p>
+</div>
+<div class="section" id="monotone-support">
+<h2><a class="toc-backref" href="#id73">Monotone support</a></h2>
+<p><a class="reference external" href="http://www.monotone.ca/">Monotone</a> support was kindly contributed by <a class="reference external" href="mailto:markus&#64;bluegap.ch">Markus Schiltknecht</a> and further developed by <a class="reference external" href="mailto:birrachiara&#64;tin.it">rghetta</a>, that was able to linearize the multi-headed
+monotone history into something tailor groks. Kudos!
+More recently, <a class="reference external" href="mailto:henry&#64;bigfoot.de">Henry Nestler</a> contributed
+various enhancements, like using <tt class="docutils literal"><span class="pre">automate</span></tt> instead <tt class="docutils literal"><span class="pre">list</span></tt> and tag
+support.</p>
+</div>
+<div class="section" id="perforce-support">
+<h2><a class="toc-backref" href="#id74">Perforce support</a></h2>
+<p><a class="reference external" href="http://www.perforce.com/">Perforce</a> support was kindly contributed by <a class="reference external" href="mailto:dustin&#64;spy.net">Dustin Sallings</a>.</p>
+</div>
+<div class="section" id="tla-support">
+<h2><a class="toc-backref" href="#id75">Tla support</a></h2>
+<p><a class="reference external" href="http://www.gnuarch.org/arch/index.html">Tla</a> support was contributed by <a class="reference external" href="mailto:robin.farine&#64;terminus.org">Robin Farine</a>.</p>
+</div>
+</div>
+<div class="section" id="license">
+<h1><a class="toc-backref" href="#id76">License</a></h1>
+<p>Tailor is <a class="reference external" href="http://www.gnu.org/philosophy/free-sw.html">free software</a>: you can redistribute it and/or modify
+it under the terms of the <cite>GNU General Public License</cite> as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.</p>
+<p>This program is distributed in the hope that it will be useful,
+but <strong>without any warranty</strong>; without even the implied warranty of
+<strong>merchantability</strong> or <strong>fitness for a particular purpose</strong>.  See the
+GNU General Public License for more details.</p>
+<p>You should have received a copy of the GNU General Public License
+along with this program in the file <tt class="docutils literal"><span class="pre">COPYING</span></tt>.  If not, see <a class="reference external" href="http://www.fsf.org/licensing/licenses/gpl.html">this
+web page</a>.</p>
+</div>
+<div class="section" id="about-this-document">
+<h1><a class="toc-backref" href="#id77">About this document</a></h1>
+<p>This document and most of the internal documentation use the
+reStructuredText format so that it can be easily converted into other
+formats, such as HTML.  For more information about this, please see:</p>
+<blockquote>
+<a class="reference external" href="http://docutils.sourceforge.net/rst.html">http://docutils.sourceforge.net/rst.html</a></blockquote>
+<!-- vim:ft=rest -->
+<!-- Local Variables: -->
+<!-- mode: rst -->
+<!-- End: -->
+</div>
+</div>
+</body>
+</html>