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