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