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