www/cvs2bzr.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml">
   4 <head>
   5 <style type="text/css"> /* <![CDATA[ */
   6   @import "tigris-branding/css/tigris.css";
   7   @import "tigris-branding/css/inst.css";
   8   /* ]]> */</style>
   9 <link rel="stylesheet" type="text/css" media="print"
  10   href="tigris-branding/css/print.css"/>
  11 <script type="text/javascript" src="tigris-branding/scripts/tigris.js"></script>
  12 <title>cvs2bzr Documentation</title>
  13 </head>
  14
  15 <body id="bodycol">
  16 <div class="app">
  17
  18 <h1>cvs2bzr</h1>
  19
  20 <h2>Index</h2>
  21
  22 <ul>
  23
  24   <li><a href="#intro">Introduction</a></li>
  25
  26   <li><a href="#reqs">Requirements</a></li>
  27
  28   <li><a href="#status">Development status</a></li>
  29
  30   <li><a href="#docs">Documentation</a></li>
  31
  32   <li><a href="#usage">Usage</a></li>
  33
  34 </ul>
  35
  36 <hr />
  37
  38 <h2><a name="intro">Introduction</a></h2>
  39
  40 <p>cvs2svn/cvs2bzr is a tool that can be used to migrate CVS
  41 repositories to newer version control tools, including <a
  42     href="http://bazaar-vcs.org/">Bazaar</a>.  Bazaar is an adaptive
  43 version control system that supports both centralised and distributed
  44 version control. It is most famous for being used for Ubuntu and
  45 MySQL development. The program used to convert to Bazaar, called
  46 cvs2bzr, is distributed as part of the cvs2svn project.</p>
  47
  48 <p><strong>If you are reading this documentation on the <a
  49 href="http://cvs2svn.tigris.org">cvs2svn website</a>, then please be
  50 aware that it describes the current trunk version of cvs2svn, which
  51 may be different than the most recent released version.  Please refer
  52 to the documentation that was included with your version of cvs2svn.
  53 </strong></p>
  54
  55 <p>Conversion to Bazaar was added in release 2.3 of cvs2svn and may have
  56 improved significantly since then.  Please make sure you are using an
  57 up-to-date version of cvs2svn--perhaps even the development trunk
  58 version.</p>
  59
  60
  61 <h2><a name="reqs">Requirements</a></h2>
  62
  63 <p>cvs2bzr requires the following:</p>
  64
  65 <ul>
  66
  67   <li>Direct (filesystem) access to a copy of the CVS repository that
  68     you want to convert.  cvs2bzr parses the files in the CVS
  69     repository directly, so it is not enough to have remote CVS
  70     access.  See the <a href="faq.html#repoaccess">FAQ</a> for more
  71     information and a possible workaround.</li>
  72
  73   <li>Python 2, version 2.4 or later.  See <a
  74     href="http://www.python.org/">http://www.python.org/</a>.
  75     (cvs2bzr does <strong>not</strong> work with Python 3.x.)</li>
  76
  77   <li>If you use the <tt>--use-rcs</tt> option, then RCS's `co'
  78     program is required.  The RCS home page is
  79     <a href="http://www.cs.purdue.edu/homes/trinkle/RCS/"
  80             >http://www.cs.purdue.edu/homes/trinkle/RCS/</a>.
  81     See the <a href="cvs2svn.html#use-rcs"><tt>--use-rcs</tt> flag</a> for more
  82     details.</li>
  83
  84   <li>If you use the <tt>--use-cvs</tt> option, then the `cvs' command
  85     is required.  The CVS home page is
  86     <a href="http://ccvs.cvshome.org/">http://ccvs.cvshome.org/</a>.
  87     See the <a href="cvs2svn.html#use-cvs"><tt>--use-cvs</tt> flag</a> for more
  88     details.</li>
  89
  90   <li> Bazaar version 1.13 or later.</li>
  91
  92   <li> The bzr-fastimport plugin version 0.9 or later.</li>
  93
  94 </ul>
  95
  96
  97 <h2><a name="status">Development status</a></h2>
  98
  99 <p>Most of the work of converting a repository from CVS to a more
 100 modern version control system is inferring the most likely history
 101 given the incomplete information that CVS records.  cvs2svn has a long
 102 history of making sense of even the most convoluted CVS repositories,
 103 and cvs2bzr uses this same machinery.  Therefore, cvs2bzr inherits the
 104 robustness and many of the <a href="features.html">features of
 105 cvs2svn</a>.  cvs2svn can convert just about every CVS repository we
 106 have ever seen, and includes a plethora of options for customizing
 107 your conversion.</p>
 108
 109 <p>The output of cvs2bzr is a "fastimport" dump file that can be
 110 imported into Bazaar using the <a
 111     href="https://launchpad.net/bzr-fastimport/">bzr-fastimport</a>
 112 plugin.</p>
 113
 114 <p>Although cvs2bzr is considerably newer than cvs2svn, and much less
 115 well tested, it is believed that cvs2bzr can (cautiously) be used for
 116 production conversions. If you use cvs2bzr, please let us know how it
 117 worked for you!</p>
 118
 119
 120 <h2><a name="limitations">cvs2bzr limitations</a></h2>
 121
 122 <p>cvs2bzr still has many limitations compared to cvs2svn.  The main
 123 cvs2svn developer has limited Bazaar experience and very limited time, so
 124 <strong>help would be much appreciated!</strong> Some of these missing
 125 features would be pretty easy to program, and I'd be happy to help you
 126 get started.</p>
 127
 128 <ul>
 129
 130   <li>The cvs2bzr documentation is still rather thin.  See <a
 131     href="#docs">below</a> for more references.</li>
 132
 133   <li>CVS allows a branch to be created from arbitrary combinations of
 134     source revisions and/or source branches.  cvs2bzr tries to create
 135     a branch from a single source, but if it can't figure out how to,
 136     it creates the branch using "merge" from multiple sources.  In
 137     pathological situations, the number of merge sources for a branch
 138     can be arbitrarily large.</li>
 139
 140   <li>There are no checks that CVS branch and tag names are legal
 141     names in Bazaar. This is unlikely to be a problem because Bazaar
 142     uses paths for branch names similar to CVS and Subversion. Tag
 143     naming in Bazaar is also more flexible than in git, say.</li>
 144
 145   <li>Only single projects can be converted at a time.  Given the way
 146     Bazaar is typically used, I don't think that this is a significant
 147     limitation.</li>
 148
 149   <li>cvs2bzr is not especially fast.  Among other things, it still
 150     uses RCS or CVS to extract the contents of the CVS revisions.
 151     Implementing the <tt>--internal-co</tt> option for cvs2bzr (using
 152     code that already exists in cvs2svn) might improve the conversion
 153     speed considerably.</li>
 154
 155   <li>The cvs2svn test suite does not include meaningful tests of
 156     Bazaar output.</li>
 157
 158   <li>cvs2bzr makes no attempt to convert <tt>.cvsignore</tt> files
 159     into <tt>.bzrignore</tt> files.</li>
 160
 161   <li>cvs2bzr, like cvs2svn, does not support incremental conversion
 162     (i.e., tracking a live CVS repository).  However, this <a
 163     href="http://www.oak.homeunix.org/~marcel/blog/2009/06/03/tracking-cvs-with-git-using-cvs2git">possible
 164     workaround</a> for using cvs2git along those lines might provide
 165     some assistance for anyone wanting to try doing that using
 166     cvs2bzr.</li>
 167
 168 </ul>
 169
 170
 171 <h2><a name="docs">Documentation</a></h2>
 172
 173 <p>There is some documentation specific to cvs2bzr, and much of the
 174 cvs2svn documentation also applies fairly straightforwardly to
 175 cvs2bzr.  See the following sources:</p>
 176
 177 <ul>
 178
 179   <li>This document.</li>
 180
 181   <li>The cvs2bzr man page and the output of <tt>cvs2bzr
 182     --help</tt>.</li>
 183
 184   <li><a href="cvs2svn.html#intro">The cvs2svn documentation</a> and
 185     <a href="faq.html">the cvs2svn FAQ</a>, which contain much general
 186     discussion and describe many features that can also be used for
 187     cvs2bzr.</li>
 188
 189   <li><tt>cvs2bzr-example.options</tt> in the cvs2svn source tree,
 190     which is an example of an options file that can be used to
 191     configure a cvs2bzr conversion.  The file is extensively
 192     documented.</li>
 193
 194   <li>The cvs2svn mailing lists, IRC channel, etc., as described in <a
 195     href="faq.html#gettinghelp">the cvs2svn FAQ</a>.</li>
 196
 197   <li>The <a href="http://doc.bazaar-vcs.org/migration/en/data-migration/">
 198     Bazaar Data Migration Guide</a>.</li>
 199
 200 </ul>
 201
 202
 203 <h2><a name="usage">Usage</a></h2>
 204
 205 <p>This section outlines the steps needed to convert a CVS repository
 206 to Bazaar using cvs2bzr.</p>
 207
 208 <ol>
 209
 210   <li>Be sure that you have the <a href="#reqs">requirements</a>,
 211     including either RCS or CVS (used to read revision contents from
 212     the CVS repository).</li>
 213
 214   <li>Obtain a copy of cvs2svn/cvs2bzr version 2.3 or newer.  It is
 215     recommended that you use the most recent version available, or
 216     even the development version.
 217
 218     <ul>
 219
 220       <li>To install cvs2svn from a <a
 221         href="http://cvs2svn.tigris.org/servlets/ProjectDocumentList">tarball</a>,
 222         simply unpack the tarball into a directory on your conversion
 223         computer (cvs2bzr can be run directly from this
 224         directory).</li>
 225
 226       <li>
 227
 228         <p>To check out the current trunk version of cvs2svn, make
 229           sure that you have Subversion installed and then run:</p>
 230
 231 <pre>
 232 svn co --username=guest --password="" http://cvs2svn.tigris.org/svn/cvs2svn/trunk cvs2svn-trunk
 233 cd cvs2svn-trunk
 234 make man # If you want to create manpages for the main programs
 235 make check # ...optional
 236 </pre>
 237
 238         <p>Please note that the test suite includes tests that are
 239           marked "XFAIL" (expected failure); these are known and are
 240           not considered serious problems.</p>
 241
 242       </li>
 243
 244     </ul>
 245
 246   </li>
 247
 248   <li>
 249
 250     Configure cvs2bzr for your conversion.  This can be done via
 251     command-line options or via an options file:
 252
 253     <ul>
 254
 255       <li>The command-line options for running cvs2bzr are documented
 256         in the cvs2bzr man page and in the output of <tt>cvs2bzr
 257         --help</tt>.</li>
 258
 259       <li>
 260
 261         <p>The more flexible <a
 262           href="cvs2svn.html#cmd-vs-options">options-file method</a>
 263           requires you to create an options file, then start cvs2bzr
 264           with</p>
 265
 266 <pre>
 267 cvs2bzr --options=OPTIONS-FILE
 268 </pre>
 269
 270         <p>Use <tt>cvs2bzr-example.options</tt> in the cvs2svn source
 271           tree as your starting point; the file contains lots of
 272           documentation.</p>
 273
 274       </li>
 275
 276     </ul>
 277
 278   </li>
 279
 280   <li>
 281
 282     <p>Run cvs2bzr.  This creates an output file in <a
 283         href="http://www.kernel.org/pub/software/scm/git/docs/git-fast-import.html">fast-import</a>
 284     format.  The name of this file is specified by
 285     your options file or a command-line argument.  In the example,
 286     the file is named <tt>cvs2svn-tmp/dumpfile.fi</tt>.</p>
 287
 288   </li>
 289
 290   <li>
 291
 292     <p>Load the dump file using bzr fast-import:</p>
 293
 294 <pre>
 295 bzr fast-import cvs2svn-tmp/dumpfile.fi project.bzr
 296 </pre>
 297
 298   </li>
 299
 300 </ol>
 301
 302 <p>Feedback would be much appreciated, including reports of success
 303   using cvs2bzr.  Please send comments, bug reports, and patches to
 304   the <a
 305   href="http://cvs2svn.tigris.org/servlets/ProjectMailingListList">cvs2svn
 306   mailing lists</a>.</p>
 307
 308 </div>
 309 </body>
 310 </html>