www/cvs2git.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>cvs2git Documentation</title>
  13 </head>
  14
  15 <body id="bodycol">
  16 <div class="app">
  17
  18 <h1>cvs2git</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/cvs2git is a tool that can be used to migrate CVS
  41 repositories to newer version control tools, including <a
  42 href="http://git.or.cz/">git</a>.  git is a distributed version
  43 control system most famous for being used for Linux kernel
  44 development.  The program used to convert to git, called cvs2git, is
  45 distributed as part of the cvs2svn project.</p>
  46
  47 <p><strong>If you are reading this documentation on the <a
  48 href="http://cvs2svn.tigris.org">cvs2svn website</a>, then please be
  49 aware that it describes the current trunk version of cvs2svn, which
  50 may be different than the most recent released version.  Please refer
  51 to the documentation that was included with your version of cvs2svn.
  52 </strong></p>
  53
  54 <p>Conversion to git was added in release 2.1 of cvs2svn and has
  55 improved significantly since then.  Please make sure you are using an
  56 up-to-date version of cvs2svn--perhaps even the development trunk
  57 version.</p>
  58
  59
  60 <h2><a name="reqs">Requirements</a></h2>
  61
  62 <p>cvs2git requires the following:</p>
  63
  64 <ul>
  65
  66   <li>Direct (filesystem) access to a copy of the CVS repository that
  67     you want to convert.  cvs2git parses the files in the CVS
  68     repository directly, so it is not enough to have remote CVS
  69     access.  See the <a href="faq.html#repoaccess">FAQ</a> for more
  70     information and a possible workaround.</li>
  71
  72   <li>Python 2, version 2.4 or later.  See <a
  73     href="http://www.python.org/">http://www.python.org/</a>.
  74     (cvs2git does <strong>not</strong> work with Python 3.x.)</li>
  75
  76   <li>If you use the <tt>--use-rcs</tt> option, then RCS's `co'
  77     program is required.  The RCS home page is
  78     <a href="http://www.cs.purdue.edu/homes/trinkle/RCS/"
  79             >http://www.cs.purdue.edu/homes/trinkle/RCS/</a>.
  80     See the <a href="cvs2svn.html#use-rcs"><tt>--use-rcs</tt> flag</a> for more
  81     details.</li>
  82
  83   <li>If you use the <tt>--use-cvs</tt> option, then the `cvs' command
  84     is required.  The CVS home page is
  85     <a href="http://ccvs.cvshome.org/">http://ccvs.cvshome.org/</a>.
  86     See the <a href="cvs2svn.html#use-cvs"><tt>--use-cvs</tt> flag</a> for more
  87     details.</li>
  88
  89   <li>GNU sort, which is part of the coreutils package, see <a
  90     href="http://www.gnu.org/software/coreutils/"
  91          >http://www.gnu.org/software/coreutils/</a>.  Binaries for
  92     Win32 can be found at <a href="http://unxutils.sourceforge.net/"
  93                                   >http://unxutils.sourceforge.net/</a>.
  94     Windows <tt>sort.exe</tt> is <b>not</b> adequate.</li>
  95
  96   <li> Git version 1.5.4.4 or later (earlier versions have a bug in
  97     "git fast-import" that prevent them from loading the files
  98     generated by cvs2git).</li>
  99
 100 </ul>
 101
 102
 103 <h2><a name="status">Development status</a></h2>
 104
 105 <p>Most of the work of converting a repository from CVS to a more
 106 modern version control system is inferring the most likely history
 107 given the incomplete information that CVS records.  cvs2svn has a long
 108 history of making sense of even the most convoluted CVS repositories,
 109 and cvs2git uses this same machinery.  Therefore, cvs2git inherits the
 110 robustness and many of the <a href="features.html">features of
 111 cvs2svn</a>.  cvs2svn can convert just about every CVS repository we
 112 have ever seen, and includes a plethora of options for customizing
 113 your conversion.</p>
 114
 115 <p>The output of cvs2git is one or more dump files that can be
 116 imported into git using the excellent <a
 117 href="http://www.kernel.org/pub/software/scm/git/docs/git
 118 fast-import.html">git fast-import</a> tool.</p>
 119
 120 <p>Although cvs2git is considerably newer than cvs2svn, and much less
 121 well tested, it is believed that cvs2git can (cautiously) be used for
 122 production conversions.  If you use cvs2git, please let us know how it
 123 worked for you!</p>
 124
 125
 126 <h2><a name="limitations">cvs2git limitations</a></h2>
 127
 128 <p>cvs2git still has many limitations compared to cvs2svn.  The main
 129 cvs2svn developer has limited git experience and very limited time, so
 130 <strong>help would be much appreciated!</strong> Some of these missing
 131 features would be pretty easy to program, and I'd be happy to help you
 132 get started.</p>
 133
 134 <ul>
 135
 136   <li>The cvs2git documentation is still rather thin.  See <a
 137     href="#docs">below</a> for more references.</li>
 138
 139   <li>CVS allows a branch to be created from arbitrary combinations of
 140     source revisions and/or source branches.  cvs2git tries to create
 141     a branch from a single source, but if it can't figure out how to,
 142     it creates the branch using "merge" from multiple sources.  In
 143     pathological situations, the number of merge sources for a branch
 144     can be arbitrarily large.</li>
 145
 146   <li>If cvs2git cannot determine that a CVS tag can be created from a
 147     single revision, then it creates a <a
 148     href="http://www.kernel.org/pub/software/scm/git/docs/git-fast-import.html">tag
 149     fixup branch</a> named <tt>TAG.FIXUP</tt>, then tags this branch.
 150     (This is a necessary workaround for the fact that CVS tags are
 151     fundamentally different than git tags.)  The <tt>TAG.FIXUP</tt>
 152     branch is cleared at the end of the conversion, but not deleted.
 153     There are some situations when a tag <em>could</em> be created
 154     from a single revision, but cvs2git does not realize it and
 155     creates a superfluous tag fixup branch.  It is possible to delete
 156     all superfluous tag fixup branches after the conversion, by
 157     running the <tt>contrib/git-move-tags.py</tt> script within the
 158     resulting git repository.</li>
 159
 160   <li>There are no checks that CVS branch and tag names are legal git
 161     names.  There are probably other git constraints that should also
 162     be checked.</li>
 163
 164   <li>The data that should be fed to git fast-import are written to
 165     two files, which have to be loaded into git fast-import manually.
 166     These files might grow to very large size.  It would be nice to
 167     add an option to invoke git fast-import automatically and pipe the
 168     output directly into git fast-import; this should also speed up
 169     the conversion.</li>
 170
 171   <li>Only single projects can be converted at a time.  Given the way
 172     git is typically used, I don't think that this is a significant
 173     limitation.</li>
 174
 175   <li>cvs2git is not especially fast.  Among other things, it still
 176     uses RCS or CVS to extract the contents of the CVS revisions.
 177     Implementing the <tt>--internal-co</tt> option for cvs2git (using
 178     code that already exists in cvs2svn) might improve the conversion
 179     speed considerably.</li>
 180
 181   <li>The cvs2svn test suite does not include meaningful tests of git
 182     output.</li>
 183
 184   <li>cvs2git makes no attempt to convert <tt>.cvsignore</tt> files
 185     into <tt>.gitignore</tt> files.</li>
 186
 187   <li>cvs2git, like cvs2svn, does not support incremental conversion
 188     (i.e., tracking a live CVS repository).  However, at least one
 189     person has documented a <a
 190     href="http://www.oak.homeunix.org/~marcel/blog/2009/06/03/tracking-cvs-with-git-using-cvs2git">possible
 191     workaround</a>.</li>
 192
 193 </ul>
 194
 195
 196 <h2><a name="docs">Documentation</a></h2>
 197
 198 <p>There is some documentation specific to cvs2git, and much of the
 199 cvs2svn documentation also applies fairly straightforwardly to
 200 cvs2git.  See the following sources:</p>
 201
 202 <ul>
 203
 204   <li>This document.</li>
 205
 206   <li>The cvs2git man page and the output of <tt>cvs2git
 207     --help</tt>.</li>
 208
 209   <li><a href="cvs2svn.html#intro">The cvs2svn documentation</a> and
 210     <a href="faq.html">the cvs2svn FAQ</a>, which contain much general
 211     discussion and describe many features that can also be used for
 212     cvs2git.</li>
 213
 214   <li><tt>cvs2git-example.options</tt> in the cvs2svn source tree,
 215     which is an example of an options file that can be used to
 216     configure a cvs2git conversion.  The file is extensively
 217     documented.</li>
 218
 219   <li>The cvs2svn mailing lists, IRC channel, etc., as described in <a
 220     href="faq.html#gettinghelp">the cvs2svn FAQ</a>.</li>
 221
 222 </ul>
 223
 224
 225 <h2><a name="usage">Usage</a></h2>
 226
 227 <p>This section outlines the steps needed to convert a CVS repository
 228 to git using cvs2git.</p>
 229
 230 <ol>
 231
 232   <li>Be sure that you have the <a href="#reqs">requirements</a>,
 233     including either RCS or CVS (used to read revision contents from
 234     the CVS repository).</li>
 235
 236   <li>Obtain a copy of cvs2svn/cvs2git version 2.1 or newer.  It is
 237     recommended that you use the most recent version available, or
 238     even the development version.
 239
 240     <ul>
 241
 242       <li>To install cvs2svn from a <a
 243         href="http://cvs2svn.tigris.org/servlets/ProjectDocumentList">tarball</a>,
 244         simply unpack the tarball into a directory on your conversion
 245         computer (cvs2git can be run directly from this
 246         directory).</li>
 247
 248       <li>
 249
 250         <p>To check out the current trunk version of cvs2svn, make
 251           sure that you have Subversion installed and then run:</p>
 252
 253 <pre>
 254 svn co --username=guest http://cvs2svn.tigris.org/svn/cvs2svn/trunk cvs2svn-trunk
 255 # The password is empty; i.e., just press return.
 256 cd cvs2svn-trunk
 257 make man # If you want to create manpages for the main programs
 258 make check # ...optional
 259 </pre>
 260
 261         <p>Please note that the test suite includes tests that are
 262           marked "XFAIL" (expected failure); these are known and are
 263           not considered serious problems.</p>
 264
 265       </li>
 266
 267     </ul>
 268
 269   </li>
 270
 271   <li>
 272
 273     Configure cvs2git for your conversion.  This can be done via
 274     command-line options or via an options file:
 275
 276     <ul>
 277
 278       <li>The command-line options for running cvs2git are documented
 279         in the cvs2git man page and in the output of <tt>cvs2git
 280         --help</tt>.</li>
 281
 282       <li>
 283
 284         <p>The more flexible <a
 285           href="cvs2svn.html#cmd-vs-options">options-file method</a>
 286           requires you to create an options file, then start cvs2git
 287           with</p>
 288
 289 <pre>
 290 cvs2git --options=OPTIONS-FILE
 291 </pre>
 292
 293         <p>Use <tt>cvs2git-example.options</tt> in the cvs2svn source
 294           tree as your starting point; the file contains lots of
 295           documentation.</p>
 296
 297       </li>
 298
 299     </ul>
 300
 301   </li>
 302
 303   <li>
 304
 305     <p>Run cvs2git.  This creates two output files in <a
 306     href="http://www.kernel.org/pub/software/scm/git/docs/git-fast-import.html">git
 307     fast-import</a> format.  The names of these files are specified by
 308     your options file or command-line arguments.  In the example,
 309     these files are named <tt>cvs2svn-tmp/git-blob.dat</tt> and
 310     <tt>cvs2svn-tmp/git-dump.dat</tt>.</p>
 311
 312   </li>
 313
 314   <li>
 315
 316     <p>Initialize a git repository, and load the dump files using
 317       git fast-import:</p>
 318
 319 <pre>
 320 git init
 321 cat cvs2svn-tmp/git-blob.dat | git fast-import --export-marks=cvs2svn-tmp/git-marks.dat
 322 cat cvs2svn-tmp/git-dump.dat | git fast-import --import-marks=cvs2svn-tmp/git-marks.dat
 323 </pre>
 324
 325     <p>This can, of course, be shortened to:</p>
 326
 327 <pre>
 328 git init
 329 cat cvs2svn-tmp/git-blob.dat cvs2svn-tmp/git-dump.dat | git fast-import
 330 </pre>
 331
 332   </li>
 333
 334   <li>If you want to get rid of unnecessary tag fixup branches, then
 335     run the <tt>contrib/git-move-tags.py</tt> script from within the
 336     git repository.</li>
 337
 338 </ol>
 339
 340 <p>Feedback would be much appreciated, including reports of success
 341   using cvs2git.  Please send comments, bug reports, and patches to
 342   the <a
 343   href="http://cvs2svn.tigris.org/servlets/ProjectMailingListList">cvs2svn
 344   mailing lists</a>.</p>
 345
 346 </div>
 347 </body>
 348 </html>