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