diff options
Diffstat (limited to 'third_party/git/Documentation/gitcvs-migration.txt')
| -rw-r--r-- | third_party/git/Documentation/gitcvs-migration.txt | 206 |
1 files changed, 206 insertions, 0 deletions
diff --git a/third_party/git/Documentation/gitcvs-migration.txt b/third_party/git/Documentation/gitcvs-migration.txt new file mode 100644 index 000000000000..1cd1283d0f81 --- /dev/null +++ b/third_party/git/Documentation/gitcvs-migration.txt @@ -0,0 +1,206 @@ +gitcvs-migration(7) +=================== + +NAME +---- +gitcvs-migration - Git for CVS users + +SYNOPSIS +-------- +[verse] +'git cvsimport' * + +DESCRIPTION +----------- + +Git differs from CVS in that every working tree contains a repository with +a full copy of the project history, and no repository is inherently more +important than any other. However, you can emulate the CVS model by +designating a single shared repository which people can synchronize with; +this document explains how to do that. + +Some basic familiarity with Git is required. Having gone through +linkgit:gittutorial[7] and +linkgit:gitglossary[7] should be sufficient. + +Developing against a shared repository +-------------------------------------- + +Suppose a shared repository is set up in /pub/repo.git on the host +foo.com. Then as an individual committer you can clone the shared +repository over ssh with: + +------------------------------------------------ +$ git clone foo.com:/pub/repo.git/ my-project +$ cd my-project +------------------------------------------------ + +and hack away. The equivalent of 'cvs update' is + +------------------------------------------------ +$ git pull origin +------------------------------------------------ + +which merges in any work that others might have done since the clone +operation. If there are uncommitted changes in your working tree, commit +them first before running git pull. + +[NOTE] +================================ +The 'pull' command knows where to get updates from because of certain +configuration variables that were set by the first 'git clone' +command; see `git config -l` and the linkgit:git-config[1] man +page for details. +================================ + +You can update the shared repository with your changes by first committing +your changes, and then using the 'git push' command: + +------------------------------------------------ +$ git push origin master +------------------------------------------------ + +to "push" those commits to the shared repository. If someone else has +updated the repository more recently, 'git push', like 'cvs commit', will +complain, in which case you must pull any changes before attempting the +push again. + +In the 'git push' command above we specify the name of the remote branch +to update (`master`). If we leave that out, 'git push' tries to update +any branches in the remote repository that have the same name as a branch +in the local repository. So the last 'push' can be done with either of: + +------------ +$ git push origin +$ git push foo.com:/pub/project.git/ +------------ + +as long as the shared repository does not have any branches +other than `master`. + +Setting Up a Shared Repository +------------------------------ + +We assume you have already created a Git repository for your project, +possibly created from scratch or from a tarball (see +linkgit:gittutorial[7]), or imported from an already existing CVS +repository (see the next section). + +Assume your existing repo is at /home/alice/myproject. Create a new "bare" +repository (a repository without a working tree) and fetch your project into +it: + +------------------------------------------------ +$ mkdir /pub/my-repo.git +$ cd /pub/my-repo.git +$ git --bare init --shared +$ git --bare fetch /home/alice/myproject master:master +------------------------------------------------ + +Next, give every team member read/write access to this repository. One +easy way to do this is to give all the team members ssh access to the +machine where the repository is hosted. If you don't want to give them a +full shell on the machine, there is a restricted shell which only allows +users to do Git pushes and pulls; see linkgit:git-shell[1]. + +Put all the committers in the same group, and make the repository +writable by that group: + +------------------------------------------------ +$ chgrp -R $group /pub/my-repo.git +------------------------------------------------ + +Make sure committers have a umask of at most 027, so that the directories +they create are writable and searchable by other group members. + +Importing a CVS archive +----------------------- + +NOTE: These instructions use the `git-cvsimport` script which ships with +git, but other importers may provide better results. See the note in +linkgit:git-cvsimport[1] for other options. + +First, install version 2.1 or higher of cvsps from +https://github.com/andreyvit/cvsps[https://github.com/andreyvit/cvsps] and make +sure it is in your path. Then cd to a checked out CVS working directory +of the project you are interested in and run linkgit:git-cvsimport[1]: + +------------------------------------------- +$ git cvsimport -C <destination> <module> +------------------------------------------- + +This puts a Git archive of the named CVS module in the directory +<destination>, which will be created if necessary. + +The import checks out from CVS every revision of every file. Reportedly +cvsimport can average some twenty revisions per second, so for a +medium-sized project this should not take more than a couple of minutes. +Larger projects or remote repositories may take longer. + +The main trunk is stored in the Git branch named `origin`, and additional +CVS branches are stored in Git branches with the same names. The most +recent version of the main trunk is also left checked out on the `master` +branch, so you can start adding your own changes right away. + +The import is incremental, so if you call it again next month it will +fetch any CVS updates that have been made in the meantime. For this to +work, you must not modify the imported branches; instead, create new +branches for your own changes, and merge in the imported branches as +necessary. + +If you want a shared repository, you will need to make a bare clone +of the imported directory, as described above. Then treat the imported +directory as another development clone for purposes of merging +incremental imports. + +Advanced Shared Repository Management +------------------------------------- + +Git allows you to specify scripts called "hooks" to be run at certain +points. You can use these, for example, to send all commits to the shared +repository to a mailing list. See linkgit:githooks[5]. + +You can enforce finer grained permissions using update hooks. See +link:howto/update-hook-example.html[Controlling access to branches using +update hooks]. + +Providing CVS Access to a Git Repository +---------------------------------------- + +It is also possible to provide true CVS access to a Git repository, so +that developers can still use CVS; see linkgit:git-cvsserver[1] for +details. + +Alternative Development Models +------------------------------ + +CVS users are accustomed to giving a group of developers commit access to +a common repository. As we've seen, this is also possible with Git. +However, the distributed nature of Git allows other development models, +and you may want to first consider whether one of them might be a better +fit for your project. + +For example, you can choose a single person to maintain the project's +primary public repository. Other developers then clone this repository +and each work in their own clone. When they have a series of changes that +they're happy with, they ask the maintainer to pull from the branch +containing the changes. The maintainer reviews their changes and pulls +them into the primary repository, which other developers pull from as +necessary to stay coordinated. The Linux kernel and other projects use +variants of this model. + +With a small group, developers may just pull changes from each other's +repositories without the need for a central maintainer. + +SEE ALSO +-------- +linkgit:gittutorial[7], +linkgit:gittutorial-2[7], +linkgit:gitcore-tutorial[7], +linkgit:gitglossary[7], +linkgit:giteveryday[7], +link:user-manual.html[The Git User's Manual] + +GIT +--- +Part of the linkgit:git[1] suite |