Inline select_k_option() method.
[cvs2svn.git] / www / cvs2bzr.html
blob63f155c54e419b1b99f0931caa4d04f3a7ed8fa9
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>
15 <body id="bodycol">
16 <div class="app">
18 <h1>cvs2bzr</h1>
20 <h2>Index</h2>
22 <ul>
24 <li><a href="#intro">Introduction</a></li>
26 <li><a href="#reqs">Requirements</a></li>
28 <li><a href="#status">Development status</a></li>
30 <li><a href="#docs">Documentation</a></li>
32 <li><a href="#usage">Usage</a></li>
34 </ul>
36 <hr />
38 <h2><a name="intro">Introduction</a></h2>
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>
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>
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>
61 <h2><a name="reqs">Requirements</a></h2>
63 <p>cvs2bzr requires the following:</p>
65 <ul>
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>
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>
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>
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>
90 <li> Bazaar version 1.13 or later.</li>
92 <li> The bzr-fastimport plugin version 0.9 or later.</li>
94 </ul>
97 <h2><a name="status">Development status</a></h2>
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>
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>
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>
120 <h2><a name="limitations">cvs2bzr limitations</a></h2>
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>
128 <ul>
130 <li>The cvs2bzr documentation is still rather thin. See <a
131 href="#docs">below</a> for more references.</li>
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>
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>
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>
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>
155 <li>The cvs2svn test suite does not include meaningful tests of
156 Bazaar output.</li>
158 <li>cvs2bzr makes no attempt to convert <tt>.cvsignore</tt> files
159 into <tt>.bzrignore</tt> files.</li>
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>
168 </ul>
171 <h2><a name="docs">Documentation</a></h2>
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>
177 <ul>
179 <li>This document.</li>
181 <li>The cvs2bzr man page and the output of <tt>cvs2bzr
182 --help</tt>.</li>
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>
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>
194 <li>The cvs2svn mailing lists, IRC channel, etc., as described in <a
195 href="faq.html#gettinghelp">the cvs2svn FAQ</a>.</li>
197 <li>The <a href="http://doc.bazaar-vcs.org/migration/en/data-migration/">
198 Bazaar Data Migration Guide</a>.</li>
200 </ul>
203 <h2><a name="usage">Usage</a></h2>
205 <p>This section outlines the steps needed to convert a CVS repository
206 to Bazaar using cvs2bzr.</p>
208 <ol>
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>
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.
218 <ul>
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>
226 <li>
228 <p>To check out the current trunk version of cvs2svn, make
229 sure that you have Subversion installed and then run:</p>
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>
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>
242 </li>
244 </ul>
246 </li>
248 <li>
250 Configure cvs2bzr for your conversion. This can be done via
251 command-line options or via an options file:
253 <ul>
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>
259 <li>
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>
266 <pre>
267 cvs2bzr --options=OPTIONS-FILE
268 </pre>
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>
274 </li>
276 </ul>
278 </li>
280 <li>
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>
288 </li>
290 <li>
292 <p>Load the dump file using bzr fast-import:</p>
294 <pre>
295 bzr fast-import cvs2svn-tmp/dumpfile.fi project.bzr
296 </pre>
298 </li>
300 </ol>
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>
308 </div>
309 </body>
310 </html>