| 1 | About |
|---|
| 2 | ===== |
|---|
| 3 | |
|---|
| 4 | tailor.py is a tool to migrate changesets between CVS, Subversion, and |
|---|
| 5 | darcs repositories. |
|---|
| 6 | |
|---|
| 7 | This script makes it easier to keep the upstream changes merged in |
|---|
| 8 | a branch of a product, storing needed information such as the upstream |
|---|
| 9 | URI and revision in special properties on the branched directory. |
|---|
| 10 | |
|---|
| 11 | The following ascii-art illustrates the usual scenario:: |
|---|
| 12 | |
|---|
| 13 | +------------+ +------------+ |
|---|
| 14 | +--------------+ | Immutable | | Working | |
|---|
| 15 | | Upstream CVS |-------->| darcs |----------->| darcs | |
|---|
| 16 | | repository | tailor | repository | darcs pull | repository | |
|---|
| 17 | +--------------+ +------------+ +------------+ |
|---|
| 18 | |^ |
|---|
| 19 | || |
|---|
| 20 | || |
|---|
| 21 | v| |
|---|
| 22 | User |
|---|
| 23 | |
|---|
| 24 | Ideally you should be able to swap and replace "CVS server" and "darcs |
|---|
| 25 | repository" with any combination of `CVS`, `Subversion` and `darcs`. |
|---|
| 26 | |
|---|
| 27 | |
|---|
| 28 | Installation |
|---|
| 29 | ============ |
|---|
| 30 | |
|---|
| 31 | tailor.py is written in Python, and thus Python must be installed on |
|---|
| 32 | your system to use it. It has been successfully used with Python 2.3 |
|---|
| 33 | and 2.4. |
|---|
| 34 | |
|---|
| 35 | Since it relays on external tools to do the real work such as `cvs`, |
|---|
| 36 | `darcs` and `svn`, they need to be installed as well. |
|---|
| 37 | |
|---|
| 38 | Make tailor.py executable:: |
|---|
| 39 | |
|---|
| 40 | $ chmod +x tailor.py |
|---|
| 41 | |
|---|
| 42 | You can either run tailor.py where it is currently located, or move it |
|---|
| 43 | along with the vcpx directory to a location in your PATH. |
|---|
| 44 | |
|---|
| 45 | |
|---|
| 46 | Examples |
|---|
| 47 | ======== |
|---|
| 48 | |
|---|
| 49 | 1. Bootstrap a new tailored project, starting at upstream revision 10:: |
|---|
| 50 | |
|---|
| 51 | $ tailor.py -b -s svn -R http://svn.server/path/to/svnrepo \ |
|---|
| 52 | --module /Product/trunk -r 10 --subdir Product ~/darcs/MyProduct |
|---|
| 53 | |
|---|
| 54 | 2. Bootstrap a new product, fetching from CVS and storing under SVN: |
|---|
| 55 | this will create the directory "~/svnwc/cmfcore"; "~/svnwc" must be |
|---|
| 56 | already under SVN:: |
|---|
| 57 | |
|---|
| 58 | $ tailor.py --source-kind cvs --target-kind svn --bootstrap \ |
|---|
| 59 | --repository :pserver:cvs.zope.org:/cvs-repository \ |
|---|
| 60 | --module CMF/CMFCore ~/svnwc/cmfcore |
|---|
| 61 | |
|---|
| 62 | 3. Showing each command bootstrap a new DARCS repos in |
|---|
| 63 | "~/darcs/cmftopic" under which the upstream module will be |
|---|
| 64 | extracted as "CMFTopic" (ie, the last component of the module |
|---|
| 65 | name):: |
|---|
| 66 | |
|---|
| 67 | $ tailor.py -D -b -R :pserver:anonymous@cvs.zope.org:/cvs-repository/ \ |
|---|
| 68 | -m CMF/CMFTopic ~/darcs/cmftopic |
|---|
| 69 | |
|---|
| 70 | 4. Merge upstream changes since last update/bootstrap:: |
|---|
| 71 | |
|---|
| 72 | $ tailor.py ~/svnwc/MyProduct |
|---|
| 73 | |
|---|
| 74 | 5. Migrate a whole SVN repository, starting from the beginning:: |
|---|
| 75 | |
|---|
| 76 | $ tailor.py -b -s svn -R svn+ssh://caia/tmp/svn/repo --module / \ |
|---|
| 77 | --subdir testsvn --revision 1 testdir |
|---|
| 78 | |
|---|
| 79 | .. warning:: When using --revision with a SVN source repository, be |
|---|
| 80 | sure that the path your are tracking was there at that |
|---|
| 81 | revision, otherwise svn will exit with an error. |
|---|
| 82 | |
|---|
| 83 | |
|---|
| 84 | Resolving conflicts |
|---|
| 85 | =================== |
|---|
| 86 | |
|---|
| 87 | Should one of the replayed changes generate any conflict, tailor.py |
|---|
| 88 | will prompt the user to correct them. This is done after the upstream |
|---|
| 89 | patch has been applied and before the final commit on the target |
|---|
| 90 | system, so that manually tweaking the conflict can produce a clean |
|---|
| 91 | patch. |
|---|
| 92 | |
|---|
| 93 | |
|---|
| 94 | Shortcomings |
|---|
| 95 | ============ |
|---|
| 96 | |
|---|
| 97 | Tailor currently suffers of the following reported problems: |
|---|
| 98 | |
|---|
| 99 | a) It does not handle "empty" CVS checkouts, in other words you cannot |
|---|
| 100 | bootstrap a project that has nothing in its CVS upstream |
|---|
| 101 | repository, or from a point in time where this condition was true. |
|---|
| 102 | |
|---|
| 103 | b) It does not work under Windows (no, that's not a feature :-). Maybe |
|---|
| 104 | replacing the shwrap machinery with something built on top of |
|---|
| 105 | subprocess_ that seems able to hide Windows crazyness... |
|---|
| 106 | |
|---|
| 107 | This list will always be incomplete, but I'll do my best to keep it |
|---|
| 108 | short :-) |
|---|
| 109 | |
|---|
| 110 | .. _subprocess: http://www.lysator.liu.se/~astrand/popen5/ |
|---|
| 111 | |
|---|
| 112 | |
|---|
| 113 | Tailor's metadata |
|---|
| 114 | ================= |
|---|
| 115 | |
|---|
| 116 | To do its work, tailor needs some information about your source tree, |
|---|
| 117 | such as the upstream repository URL and the current revision of the |
|---|
| 118 | sources on your harddisk. |
|---|
| 119 | |
|---|
| 120 | In the simpler case, tailor keeps this information in a file called |
|---|
| 121 | `tailor.info`, one for each tailored project, that is a very simple |
|---|
| 122 | text document, with the following information, one per line: |
|---|
| 123 | |
|---|
| 124 | 1. Upstream repository kind (either "cvs", "darcs" or "svn) |
|---|
| 125 | 2. Target repository kind (the same as above) |
|---|
| 126 | 3. The name of the "module" that's been tailored |
|---|
| 127 | 4. The URL of the upstream repository (that may not be an URL, for cvs...) |
|---|
| 128 | 5. The current revision, from the upstream point of view, of the sources |
|---|
| 129 | 6. The subdirectory that contains the checked out upstream tree, |
|---|
| 130 | either that given with with the `--subdir` option or computed |
|---|
| 131 | taking the last part of the module name. |
|---|
| 132 | |
|---|
| 133 | This is everything tailor needs, to be able to keep going from where it |
|---|
| 134 | left last time. |
|---|
| 135 | |
|---|
| 136 | |
|---|
| 137 | Config file format |
|---|
| 138 | ------------------ |
|---|
| 139 | |
|---|
| 140 | When your project is composed by multiple upstream modules, it is |
|---|
| 141 | easier to collect such information in a single file. This is done by |
|---|
| 142 | specifying the `--configfile` option with a file name as argument. In |
|---|
| 143 | this case, tailor will read/write the above information from a |
|---|
| 144 | standard Python dictionary stored in the given file. |
|---|
| 145 | |
|---|
| 146 | The dictionary is keyed on the relative position of each project, and |
|---|
| 147 | each entry carries the same information described above. |
|---|
| 148 | |
|---|
| 149 | Here's an example config file entry:: |
|---|
| 150 | |
|---|
| 151 | {'plone/atcontenttypes': {'module': 'ATContentTypes', |
|---|
| 152 | 'source_kind': 'cvs', |
|---|
| 153 | 'subdir': 'ATContentTypes', |
|---|
| 154 | 'target_kind': 'darcs', |
|---|
| 155 | 'upstream_repos': ':ext:cvs.sourceforge.net:/cvsroot/collective', |
|---|
| 156 | 'upstream_revision': '2004-11-24 19:42:06 by ctheune'}} |
|---|
| 157 | |
|---|
| 158 | By convention, config files are named with the extension ".tailor", |
|---|
| 159 | but this is not enforced. |
|---|
| 160 | |
|---|
| 161 | In the example above, 'plone/atcontenttypes' is a directory where the |
|---|
| 162 | target source will be stored. The keys such 'module', 'source_kind', |
|---|
| 163 | etc correspond to options of the same name. |
|---|
| 164 | |
|---|
| 165 | When using a config file, tailor will perform its job on each project |
|---|
| 166 | contained in the dictionary. |
|---|
| 167 | |
|---|
| 168 | |
|---|
| 169 | Further help |
|---|
| 170 | ============ |
|---|
| 171 | |
|---|
| 172 | See the output of tailor.py -h for some further tips. There's also a |
|---|
| 173 | `wiki page`_ that may give you some other hints. |
|---|
| 174 | |
|---|
| 175 | .. _wiki page: |
|---|
| 176 | http://www.scannedinavian.org/DarcsWiki/ConvertingFromSubversion |
|---|
| 177 | |
|---|
| 178 | I will be more than happy to answer any doubt, question or suggestion |
|---|
| 179 | you may have on it. I'm usually hanging as "lelit" on the IRC channel |
|---|
| 180 | devoted to darcs on the `freenode.net` network. Do not hesitate to |
|---|
| 181 | contact me either by email or chatting there. |
|---|
| 182 | |
|---|
| 183 | |
|---|
| 184 | Author |
|---|
| 185 | ====== |
|---|
| 186 | |
|---|
| 187 | Lele Gaifax <lele@nautilus.homeip.net> |
|---|
| 188 | |
|---|
| 189 | |
|---|
| 190 | About this document |
|---|
| 191 | =================== |
|---|
| 192 | |
|---|
| 193 | This document and most of the internal documention use the |
|---|
| 194 | reStructuredText format so that it can be easily converted into other |
|---|
| 195 | formats, such as HTML. For more information about this, please see: |
|---|
| 196 | |
|---|
| 197 | http://docutils.sourceforge.net/rst.html |
|---|
| 198 | |
|---|
| 199 | |
|---|
| 200 | .. vim:ft=rest |
|---|
| 201 | .. Local Variables: |
|---|
| 202 | .. mode: rst |
|---|
| 203 | .. End: |
|---|
