Documentation/cvs-migration.txt

   1 git for CVS users
   2 =================
   3
   4 Git differs from CVS in that every working tree contains a repository with
   5 a full copy of the project history, and no repository is inherently more
   6 important than any other.  However, you can emulate the CVS model by
   7 designating a single shared repository which people can synchronize with;
   8 this document explains how to do that.
   9
  10 Some basic familiarity with git is required.  This
  11 link:tutorial.html[tutorial introduction to git] and the
  12 link:glossary.html[git glossary] should be sufficient.
  13
  14 Developing against a shared repository
  15 --------------------------------------
  16
  17 Suppose a shared repository is set up in /pub/repo.git on the host
  18 foo.com.  Then as an individual committer you can clone the shared
  19 repository over ssh with:
  20
  21 ------------------------------------------------
  22 $ git clone foo.com:/pub/repo.git/ my-project
  23 $ cd my-project
  24 ------------------------------------------------
  25
  26 and hack away.  The equivalent of `cvs update` is
  27
  28 ------------------------------------------------
  29 $ git pull origin
  30 ------------------------------------------------
  31
  32 which merges in any work that others might have done since the clone
  33 operation.  If there are uncommitted changes in your working tree, commit
  34 them first before running git pull.
  35
  36 [NOTE]
  37 ================================
  38 The `pull` command knows where to get updates from because of certain
  39 configuration variables that were set by the first `git clone`
  40 command; see `git config -l` and the linkgit:git-config[1] man
  41 page for details.
  42 ================================
  43
  44 You can update the shared repository with your changes by first committing
  45 your changes, and then using the linkgit:git-push[1] command:
  46
  47 ------------------------------------------------
  48 $ git push origin master
  49 ------------------------------------------------
  50
  51 to "push" those commits to the shared repository.  If someone else has
  52 updated the repository more recently, `git push`, like `cvs commit`, will
  53 complain, in which case you must pull any changes before attempting the
  54 push again.
  55
  56 In the `git push` command above we specify the name of the remote branch
  57 to update (`master`).  If we leave that out, `git push` tries to update
  58 any branches in the remote repository that have the same name as a branch
  59 in the local repository.  So the last `push` can be done with either of:
  60
  61 ------------
  62 $ git push origin
  63 $ git push foo.com:/pub/project.git/
  64 ------------
  65
  66 as long as the shared repository does not have any branches
  67 other than `master`.
  68
  69 Setting Up a Shared Repository
  70 ------------------------------
  71
  72 We assume you have already created a git repository for your project,
  73 possibly created from scratch or from a tarball (see the
  74 link:tutorial.html[tutorial]), or imported from an already existing CVS
  75 repository (see the next section).
  76
  77 Assume your existing repo is at /home/alice/myproject.  Create a new "bare"
  78 repository (a repository without a working tree) and fetch your project into
  79 it:
  80
  81 ------------------------------------------------
  82 $ mkdir /pub/my-repo.git
  83 $ cd /pub/my-repo.git
  84 $ git --bare init --shared
  85 $ git --bare fetch /home/alice/myproject master:master
  86 ------------------------------------------------
  87
  88 Next, give every team member read/write access to this repository.  One
  89 easy way to do this is to give all the team members ssh access to the
  90 machine where the repository is hosted.  If you don't want to give them a
  91 full shell on the machine, there is a restricted shell which only allows
  92 users to do git pushes and pulls; see linkgit:git-shell[1].
  93
  94 Put all the committers in the same group, and make the repository
  95 writable by that group:
  96
  97 ------------------------------------------------
  98 $ chgrp -R $group /pub/my-repo.git
  99 ------------------------------------------------
 100
 101 Make sure committers have a umask of at most 027, so that the directories
 102 they create are writable and searchable by other group members.
 103
 104 Importing a CVS archive
 105 -----------------------
 106
 107 First, install version 2.1 or higher of cvsps from
 108 link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make
 109 sure it is in your path.  Then cd to a checked out CVS working directory
 110 of the project you are interested in and run linkgit:git-cvsimport[1]:
 111
 112 -------------------------------------------
 113 $ git cvsimport -C <destination> <module>
 114 -------------------------------------------
 115
 116 This puts a git archive of the named CVS module in the directory
 117 <destination>, which will be created if necessary.
 118
 119 The import checks out from CVS every revision of every file.  Reportedly
 120 cvsimport can average some twenty revisions per second, so for a
 121 medium-sized project this should not take more than a couple of minutes.
 122 Larger projects or remote repositories may take longer.
 123
 124 The main trunk is stored in the git branch named `origin`, and additional
 125 CVS branches are stored in git branches with the same names.  The most
 126 recent version of the main trunk is also left checked out on the `master`
 127 branch, so you can start adding your own changes right away.
 128
 129 The import is incremental, so if you call it again next month it will
 130 fetch any CVS updates that have been made in the meantime.  For this to
 131 work, you must not modify the imported branches; instead, create new
 132 branches for your own changes, and merge in the imported branches as
 133 necessary.
 134
 135 Advanced Shared Repository Management
 136 -------------------------------------
 137
 138 Git allows you to specify scripts called "hooks" to be run at certain
 139 points.  You can use these, for example, to send all commits to the shared
 140 repository to a mailing list.  See linkgit:githooks[5][Hooks used by git].
 141
 142 You can enforce finer grained permissions using update hooks.  See
 143 link:howto/update-hook-example.txt[Controlling access to branches using
 144 update hooks].
 145
 146 Providing CVS Access to a git Repository
 147 ----------------------------------------
 148
 149 It is also possible to provide true CVS access to a git repository, so
 150 that developers can still use CVS; see linkgit:git-cvsserver[1] for
 151 details.
 152
 153 Alternative Development Models
 154 ------------------------------
 155
 156 CVS users are accustomed to giving a group of developers commit access to
 157 a common repository.  As we've seen, this is also possible with git.
 158 However, the distributed nature of git allows other development models,
 159 and you may want to first consider whether one of them might be a better
 160 fit for your project.
 161
 162 For example, you can choose a single person to maintain the project's
 163 primary public repository.  Other developers then clone this repository
 164 and each work in their own clone.  When they have a series of changes that
 165 they're happy with, they ask the maintainer to pull from the branch
 166 containing the changes.  The maintainer reviews their changes and pulls
 167 them into the primary repository, which other developers pull from as
 168 necessary to stay coordinated.  The Linux kernel and other projects use
 169 variants of this model.
 170
 171 With a small group, developers may just pull changes from each other's
 172 repositories without the need for a central maintainer.