X-Git-Url: https://git.verplant.org/?a=blobdiff_plain;ds=sidebyside;f=cvs-migration.html;h=1ff9c4ecbec1f6437dfd8290230ecad0ccb44d2e;hb=f0a85daaf3d624dcf841cad8d5d243e6da55ea70;hp=d3ccbe1474abac5dacbccf4fba0905ca9e2255f7;hpb=1a4e841b439ba014b365999c3a6b9e2be3740bd8;p=git.git

diff --git a/cvs-migration.html b/cvs-migration.html
index d3ccbe14..1ff9c4ec 100644
--- a/cvs-migration.html
+++ b/cvs-migration.html
@@ -3,7 +3,7 @@
 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
-<meta name="generator" content="AsciiDoc 7.0.1" />
+<meta name="generator" content="AsciiDoc 7.0.2" />
 <style type="text/css">
 /* Debug borders */
 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
@@ -263,124 +263,185 @@ div.exampleblock-content {
 </div>
 <div id="preamble">
 <div class="sectionbody">
-<p>Ok, so you're a CVS user. That's ok, it's a treatable condition, and the
-first step to recovery is admitting you have a problem. The fact that
-you are reading this file means that you may be well on that path
-already.</p>
-<p>The thing about CVS is that it absolutely sucks as a source control
-manager, and you'll thus be happy with almost anything else. git,
-however, may be a bit <em>too</em> different (read: "good") for your taste, and
-does a lot of things differently.</p>
-<p>One particular suckage of CVS is very hard to work around: CVS is
-basically a tool for tracking <em>file</em> history, while git is a tool for
-tracking <em>project</em> history.  This sometimes causes problems if you are
-used to doing very strange things in CVS, in particular if you're doing
-things like making branches of just a subset of the project.  git can't
-track that, since git never tracks things on the level of an individual
-file, only on the whole project level.</p>
-<p>The good news is that most people don't do that, and in fact most sane
-people think it's a bug in CVS that makes it tag (and check in changes)
-one file at a time.  So most projects you'll ever see will use CVS
-<em>as if</em> it was sane.  In which case you'll find it very easy indeed to
-move over to git.</p>
-<p>First off: this is not a git tutorial. See
-<a href="tutorial.html">Documentation/tutorial.txt</a> for how git
-actually works. This is more of a random collection of gotcha's
-and notes on converting from CVS to git.</p>
-<p>Second: CVS has the notion of a "repository" as opposed to the thing
-that you're actually working in (your working directory, or your
-"checked out tree").  git does not have that notion at all, and all git
-working directories <em>are</em> the repositories.  However, you can easily
-emulate the CVS model by having one special "global repository", which
-people can synchronize with.  See details later, but in the meantime
-just keep in mind that with git, every checked out working tree will
-have a full revision control history of its own.</p>
-</div>
-</div>
-<h2>Importing a CVS archive</h2>
-<div class="sectionbody">
-<p>Ok, you have an old project, and you want to at least give git a chance
-to see how it performs. The first thing you want to do (after you've
-gone through the git tutorial, and generally familiarized yourself with
-how to commit stuff etc in git) is to create a git'ified version of your
-CVS archive.</p>
-<p>Happily, that's very easy indeed. git will do it for you, although git
-will need the help of a program called "cvsps":</p>
-<div class="literalblock">
-<div class="content">
-<pre><tt>http://www.cobite.com/cvsps/</tt></pre>
-</div></div>
-<p>which is not actually related to git at all, but which makes CVS usage
-look almost sane (ie you almost certainly want to have it even if you
-decide to stay with CVS). However, git will want <em>at least</em> version 2.1
-of cvsps (available at the address above), and in fact will currently
-refuse to work with anything else.</p>
-<p>Once you've gotten (and installed) cvsps, you may or may not want to get
-any more familiar with it, but make sure it is in your path. After that,
-the magic command line is</p>
-<div class="literalblock">
-<div class="content">
-<pre><tt>git cvsimport -v -d &lt;cvsroot&gt; -C &lt;destination&gt; &lt;module&gt;</tt></pre>
-</div></div>
-<p>which will do exactly what you'd think it does: it will create a git
-archive of the named CVS module. The new archive will be created in the
-subdirectory named &lt;destination&gt;; it'll be created if it doesn't exist.
-Default is the local directory.</p>
-<p>It can take some time to actually do the conversion for a large archive
-since it involves checking out from CVS every revision of every file,
-and the conversion script is reasonably chatty unless you omit the <em>-v</em>
-option, but on some not very scientific tests it averaged about twenty
-revisions per second, so a medium-sized project should not take more
-than a couple of minutes.  For larger projects or remote repositories,
-the process may take longer.</p>
-<p>After the (initial) import is done, the CVS archive's current head
-revision will be checked out &#8212; thus, you can start adding your own
-changes right away.</p>
-<p>The import is incremental, i.e. if you call it again next month it'll
-fetch any CVS updates that have been happening in the meantime. The
-cut-off is date-based, so don't change the branches that were imported
-from CVS.</p>
-<p>You can merge those updates (or, in fact, a different CVS branch) into
-your main branch:</p>
-<div class="literalblock">
-<div class="content">
-<pre><tt>git resolve HEAD origin "merge with current CVS HEAD"</tt></pre>
-</div></div>
-<p>The HEAD revision from CVS is named "origin", not "HEAD", because git
-already uses "HEAD". (If you don't like <em>origin</em>, use cvsimport's
-<em>-o</em> option to change it.)</p>
-</div>
-<h2>Emulating CVS behaviour</h2>
-<div class="sectionbody">
-<p>So, by now you are convinced you absolutely want to work with git, but
-at the same time you absolutely have to have a central repository.
-Step back and think again. Okay, you still need a single central
-repository? There are several ways to go about that:</p>
-<ol>
+<p>So you're a CVS user. That's OK, it's a treatable condition.  The job of
+this document is to put you on the road to recovery, by helping you
+convert an existing cvs repository to git, and by showing you how to use a
+git repository in a cvs-like fashion.</p>
+<p>Some basic familiarity with git is required.  This
+<a href="tutorial.html">tutorial introduction to git</a> should be sufficient.</p>
+<p>First, note some ways that git differs from CVS:</p>
+<ul>
 <li>
 <p>
-Designate a person responsible to pull all branches. Make the
-repository of this person public, and make every team member
-pull regularly from it.
+Commits are atomic and project-wide, not per-file as in CVS.
 </p>
 </li>
 <li>
 <p>
-Set up a public repository with read/write access for every team
-member. Use "git pull/push" as you used "cvs update/commit".  Be
-sure that your repository is up to date before pushing, just
-like you used to do with "cvs commit"; your push will fail if
-what you are pushing is not up to date.
+Offline work is supported: you can make multiple commits locally,
+    then submit them when you're ready.
 </p>
 </li>
 <li>
 <p>
-Make the repository of every team member public. It is the
-responsibility of each single member to pull from every other
-team member.
+Branching is fast and easy.
 </p>
 </li>
-</ol>
+<li>
+<p>
+Every working tree contains a repository with a full copy of the
+    project history, and no repository is inherently more important than
+    any other.  However, you can emulate the CVS model by designating a
+    single shared repository which people can synchronize with; see below
+    for details.
+</p>
+</li>
+</ul>
+</div>
+</div>
+<h2>Importing a CVS archive</h2>
+<div class="sectionbody">
+<p>First, install version 2.1 or higher of cvsps from
+<a href="http://www.cobite.com/cvsps/">http://www.cobite.com/cvsps/</a> and make
+sure it is in your path.  The magic command line is then</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git cvsimport -v -d &lt;cvsroot&gt; -C &lt;destination&gt; &lt;module&gt;</tt></pre>
+</div></div>
+<p>This puts a git archive of the named CVS module in the directory
+&lt;destination&gt;, which will be created if necessary.  The -v option makes
+the conversion script very chatty.</p>
+<p>The import checks out from CVS every revision of every file.  Reportedly
+cvsimport can average some twenty revisions per second, so for a
+medium-sized project this should not take more than a couple of minutes.
+Larger projects or remote repositories may take longer.</p>
+<p>The main trunk is stored in the git branch named <tt>origin</tt>, and additional
+CVS branches are stored in git branches with the same names.  The most
+recent version of the main trunk is also left checked out on the <tt>master</tt>
+branch, so you can start adding your own changes right away.</p>
+<p>The import is incremental, so if you call it again next month it will
+fetch any CVS updates that have been made in the meantime.  For this to
+work, you must not modify the imported branches; instead, create new
+branches for your own changes, and merge in the imported branches as
+necessary.</p>
+</div>
+<h2>Development Models</h2>
+<div class="sectionbody">
+<p>CVS users are accustomed to giving a group of developers commit access to
+a common repository.  In the next section we'll explain how to do this
+with git.  However, the distributed nature of git allows other development
+models, and you may want to first consider whether one of them might be a
+better fit for your project.</p>
+<p>For example, you can choose a single person to maintain the project's
+primary public repository.  Other developers then clone this repository
+and each work in their own clone.  When they have a series of changes that
+they're happy with, they ask the maintainer to pull from the branch
+containing the changes.  The maintainer reviews their changes and pulls
+them into the primary repository, which other developers pull from as
+necessary to stay coordinated.  The Linux kernel and other projects use
+variants of this model.</p>
+<p>With a small group, developers may just pull changes from each other's
+repositories without the need for a central maintainer.</p>
+</div>
+<h2>Emulating the CVS Development Model</h2>
+<div class="sectionbody">
+<p>Start with an ordinary git working directory containing the project, and
+remove the checked-out files, keeping just the bare .git directory:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ mv project/.git /pub/repo.git
+$ rm -r project/</tt></pre>
+</div></div>
+<p>Next, give every team member read/write access to this repository.  One
+easy way to do this is to give all the team members ssh access to the
+machine where the repository is hosted.  If you don't want to give them a
+full shell on the machine, there is a restricted shell which only allows
+users to do git pushes and pulls; see <a href="git-shell.html">git-shell(1)</a>.</p>
+<p>Put all the committers should in the same group, and make the repository
+writable by that group:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ chgrp -R $group repo.git
+$ find repo.git -mindepth 1 -type d |xargs chmod ug+rwx,g+s
+$ GIT_DIR=repo.git git repo-config core.sharedrepository true</tt></pre>
+</div></div>
+<p>Make sure committers have a umask of at most 027, so that the directories
+they create are writable and searchable by other group members.</p>
+<p>Suppose this repository is now set up in /pub/repo.git on the host
+foo.com.  Then as an individual commiter you can clone the shared
+repository:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git clone foo.com:/pub/repo.git/ my-project
+$ cd my-project</tt></pre>
+</div></div>
+<p>and hack away.  The equivalent of <tt>cvs update</tt> is</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git pull origin</tt></pre>
+</div></div>
+<p>which merges in any work that others might have done since the clone
+operation.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
+<p>The first <tt>git clone</tt> places the following in the
+<tt>my-project/.git/remotes/origin</tt> file, and that's why the previous step
+and the next step both work.</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>URL: foo.com:/pub/project.git/ my-project
+Pull: master:origin</tt></pre>
+</div></div>
+</td>
+</tr></table>
+</div>
+<p>You can update the shared repository with your changes using:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git push origin master</tt></pre>
+</div></div>
+<p>If someone else has updated the repository more recently, <tt>git push</tt>, like
+<tt>cvs commit</tt>, will complain, in which case you must pull any changes
+before attempting the push again.</p>
+<p>In the <tt>git push</tt> command above we specify the name of the remote branch
+to update (<tt>master</tt>).  If we leave that out, <tt>git push</tt> tries to update
+any branches in the remote repository that have the same name as a branch
+in the local repository.  So the last <tt>push</tt> can be done with either of:</p>
+<div class="listingblock">
+<div class="content">
+<pre><tt>$ git push origin
+$ git push repo.shared.xz:/pub/scm/project.git/</tt></pre>
+</div></div>
+<p>as long as the shared repository does not have any branches
+other than <tt>master</tt>.</p>
+<div class="admonitionblock">
+<table><tr>
+<td class="icon">
+<div class="title">Note</div>
+</td>
+<td class="content">
+<p>Because of this behavior, if the shared repository and the developer's
+repository both have branches named <tt>origin</tt>, then a push like the above
+attempts to update the <tt>origin</tt> branch in the shared repository from the
+developer's <tt>origin</tt> branch.  The results may be unexpected, so it's
+usually best to remove any branch named <tt>origin</tt> from the shared
+repository.</p>
+</td>
+</tr></table>
+</div>
+</div>
+<h2>Advanced Shared Repository Management</h2>
+<div class="sectionbody">
+<p>Git allows you to specify scripts called "hooks" to be run at certain
+points.  You can use these, for example, to send all commits to the shared
+repository to a mailing list.  See <a href="hooks.txt">Hooks used by git</a>.</p>
+<p>You can enforce finer grained permissions using update hooks.  See
+<a href="howto/update-hook-example.txt">Controlling access to branches using
+update hooks</a>.</p>
 </div>
 <h2>CVS annotate</h2>
 <div class="sectionbody">
@@ -395,7 +456,7 @@ mailing list archives for details).</p>
 <p>git has a couple of alternatives, though, that you may find sufficient
 or even superior depending on your use.  One is called "git-whatchanged"
 (for obvious reasons) and the other one is called "pickaxe" ("a tool for
-the software archeologist").</p>
+the software archaeologist").</p>
 <p>The "git-whatchanged" script is a truly trivial script that can give you
 a good overview of what has changed in a file or a directory (or an
 arbitrary list of files or directories).  The "pickaxe" support is an
@@ -518,7 +579,7 @@ that contain this changed "if" statement:</p>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 27-Dec-2005 00:17:06 PDT
+Last updated 04-Jun-2006 07:24:38 UTC
 </div>
 </div>
 </body>
