path: root/Documentation/gitcvs-migration.txt
diff options
authorChristian Couder <>2008-05-24 18:56:44 (GMT)
committerJunio C Hamano <>2008-05-25 05:28:16 (GMT)
commitb27a23e35d8e532e47661595bda642ef3a7375f1 (patch)
treef41cfc5f9cd8011504195a61e11c27766568f4b0 /Documentation/gitcvs-migration.txt
parent0b0b8cd7c2c3df72fc3959805b035e55e1bb1270 (diff)
Documentation: convert tutorials to man pages
This patch renames the following documents and at the same time converts them to the man page format: cvs-migration.txt -> gitcvs-migration.txt tutorial.txt -> gittutorial.txt tutorial-2.txt -> gittutorial-2.txt These new man pages are put in section 7, and other documents that reference the above ones are change accordingly. [jc: with help from Nanako to clean things up] Signed-off-by: Christian Couder <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/gitcvs-migration.txt')
1 files changed, 193 insertions, 0 deletions
diff --git a/Documentation/gitcvs-migration.txt b/Documentation/gitcvs-migration.txt
new file mode 100644
index 0000000..c410805
--- /dev/null
+++ b/Documentation/gitcvs-migration.txt
@@ -0,0 +1,193 @@
+gitcvs-migration - git for CVS users
+git cvsimport *
+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. This
+linkgit:gittutorial[7][tutorial introduction to git] and the
+link:glossary.html[git glossary] should be sufficient.
+Developing against a shared repository
+Suppose a shared repository is set up in /pub/repo.git on the host Then as an individual committer you can clone the shared
+repository over ssh with:
+$ git clone 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.
+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 linkgit:git-push[1] 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
+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 the
+linkgit:gittutorial[7][tutorial]), 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
+$ 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
+First, install version 2.1 or higher of cvsps from
+link:[] 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
+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][Hooks used by git].
+You can enforce finer grained permissions using update hooks. See
+link:howto/update-hook-example.txt[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
+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.
+linkgit:gittutorial[7], linkgit:gittutorial-2[7],
+link:everyday.html[Everyday Git],
+link:user-manual.html[The Git User's Manual]
+Part of the linkgit:git[7] suite.