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