1
git for CVS users
2
=================
3
4
-So you're a CVS user. That's OK, it's a treatable condition. The job of
5
-this document is to put you on the road to recovery, by helping you
6
-convert an existing cvs repository to git, and by showing you how to use a
7
-git repository in a cvs-like fashion.
4
+Git differs from CVS in that every working tree contains a repository with
5
+a full copy of the project history, and no repository is inherently more
6
+important than any other. However, you can emulate the CVS model by
7
+designating a single shared repository which people can synchronize with;
8
+this document explains how to do that.
9
10
Some basic familiarity with git is required. This
11
link:tutorial.html[tutorial introduction to git] should be sufficient.
12
12
-First, note some ways that git differs from CVS:
13
+Developing against a shared repository
14
+--------------------------------------
15
14
- * Commits are atomic and project-wide, not per-file as in CVS.
15
-
16
- * Offline work is supported: you can make multiple commits locally,
17
- then submit them when you're ready.
18
-
19
- * Branching is fast and easy.
20
-
21
- * Every working tree contains a repository with a full copy of the
22
- project history, and no repository is inherently more important than
23
- any other. However, you can emulate the CVS model by designating a
24
- single shared repository which people can synchronize with; see below
25
- for details.
26
-
27
- * Since every working tree contains a repository, a commit in your
28
- private repository will not publish your changes; it will only create
29
- a revision. You have to "push" your changes to a public repository to
30
- make them visible to others.
31
-
32
-Importing a CVS archive
33
------------------------
34
-
35
-First, install version 2.1 or higher of cvsps from
36
-link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make
37
-sure it is in your path. The magic command line is then
38
-
39
--------------------------------------------
40
-$ git cvsimport -v -d <cvsroot> -C <destination> <module>
41
--------------------------------------------
42
-
43
-This puts a git archive of the named CVS module in the directory
44
-<destination>, which will be created if necessary. The -v option makes
45
-the conversion script very chatty.
46
-
47
-The import checks out from CVS every revision of every file. Reportedly
48
-cvsimport can average some twenty revisions per second, so for a
49
-medium-sized project this should not take more than a couple of minutes.
50
-Larger projects or remote repositories may take longer.
51
-
52
-The main trunk is stored in the git branch named `origin`, and additional
53
-CVS branches are stored in git branches with the same names. The most
54
-recent version of the main trunk is also left checked out on the `master`
55
-branch, so you can start adding your own changes right away.
56
-
57
-The import is incremental, so if you call it again next month it will
58
-fetch any CVS updates that have been made in the meantime. For this to
59
-work, you must not modify the imported branches; instead, create new
60
-branches for your own changes, and merge in the imported branches as
61
-necessary.
62
-
63
-Development Models
64
-------------------
65
-
66
-CVS users are accustomed to giving a group of developers commit access to
67
-a common repository. In the next section we'll explain how to do this
68
-with git. However, the distributed nature of git allows other development
69
-models, and you may want to first consider whether one of them might be a
70
-better fit for your project.
71
-
72
-For example, you can choose a single person to maintain the project's
73
-primary public repository. Other developers then clone this repository
74
-and each work in their own clone. When they have a series of changes that
75
-they're happy with, they ask the maintainer to pull from the branch
76
-containing the changes. The maintainer reviews their changes and pulls
77
-them into the primary repository, which other developers pull from as
78
-necessary to stay coordinated. The Linux kernel and other projects use
79
-variants of this model.
80
-
81
-With a small group, developers may just pull changes from each other's
82
-repositories without the need for a central maintainer.
83
-
84
-Creating a Shared Repository
85
-----------------------------
86
-
87
-Start with an ordinary git working directory containing the project, and
88
-remove the checked-out files, keeping just the bare .git directory:
89
-
90
-------------------------------------------------
91
-$ mv project/.git /pub/repo.git
92
-$ rm -r project/
93
-------------------------------------------------
94
-
95
-Next, give every team member read/write access to this repository. One
96
-easy way to do this is to give all the team members ssh access to the
97
-machine where the repository is hosted. If you don't want to give them a
98
-full shell on the machine, there is a restricted shell which only allows
99
-users to do git pushes and pulls; see gitlink:git-shell[1].
100
-
101
-Put all the committers in the same group, and make the repository
102
-writable by that group:
103
-
104
-------------------------------------------------
105
-$ chgrp -R $group repo.git
106
-$ find repo.git -mindepth 1 -type d |xargs chmod ug+rwx,g+s
107
-$ GIT_DIR=repo.git git repo-config core.sharedrepository true
108
-------------------------------------------------
109
-
110
-Make sure committers have a umask of at most 027, so that the directories
111
-they create are writable and searchable by other group members.
112
-
113
-Performing Development on a Shared Repository
114
----------------------------------------------
115
-
116
-Suppose a repository is now set up in /pub/repo.git on the host
16
+Suppose a shared repository is set up in /pub/repo.git on the host
17
foo.com. Then as an individual committer you can clone the shared
118
-repository:
18
+repository over ssh with:
19
20
------------------------------------------------
21
$ git clone foo.com:/pub/repo.git/ my-project
29
------------------------------------------------
30
31
which merges in any work that others might have done since the clone
132
-operation.
32
+operation. If there are uncommitted changes in your working tree, commit
33
+them first before running git pull.
34
35
[NOTE]
36
================================
38
`my-project/.git/remotes/origin` file, and that's why the previous step
39
and the next step both work.
40
------------
140
-URL: foo.com:/pub/project.git/ my-project
141
-Pull: master:origin
41
+URL: foo.com:/pub/project.git/
42
+Pull: refs/heads/master:refs/remotes/origin/master
43
------------
44
================================
45
62
63
------------
64
$ git push origin
164
-$ git push repo.shared.xz:/pub/scm/project.git/
65
+$ git push foo.com:/pub/project.git/
66
------------
67
68
as long as the shared repository does not have any branches
69
other than `master`.
70
170
-[NOTE]
171
-============
172
-Because of this behavior, if the shared repository and the developer's
173
-repository both have branches named `origin`, then a push like the above
174
-attempts to update the `origin` branch in the shared repository from the
175
-developer's `origin` branch. The results may be unexpected, so it's
176
-usually best to remove any branch named `origin` from the shared
177
-repository.
178
-============
71
+Setting Up a Shared Repository
72
+------------------------------
73
+
74
+We assume you have already created a git repository for your project,
75
+possibly created from scratch or from a tarball (see the
76
+link:tutorial.html[tutorial]), or imported from an already existing CVS
77
+repository (see the next section).
78
+
79
+If your project's working directory is /home/alice/myproject, you can
80
+create a shared repository at /pub/repo.git with:
81
+
82
+------------------------------------------------
83
+$ git clone -bare /home/alice/myproject /pub/repo.git
84
+------------------------------------------------
85
+
86
+Next, give every team member read/write access to this repository. One
87
+easy way to do this is to give all the team members ssh access to the
88
+machine where the repository is hosted. If you don't want to give them a
89
+full shell on the machine, there is a restricted shell which only allows
90
+users to do git pushes and pulls; see gitlink:git-shell[1].
91
+
92
+Put all the committers in the same group, and make the repository
93
+writable 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
+
102
+Make sure committers have a umask of at most 027, so that the directories
103
+they create are writable and searchable by other group members.
104
+
105
+Importing a CVS archive
106
+-----------------------
107
+
108
+First, install version 2.1 or higher of cvsps from
109
+link:http://www.cobite.com/cvsps/[http://www.cobite.com/cvsps/] and make
110
+sure it is in your path. The magic command line is then
111
+
112
+-------------------------------------------
113
+$ git cvsimport -v -d <cvsroot> -C <destination> <module>
114
+-------------------------------------------
115
+
116
+This puts a git archive of the named CVS module in the directory
117
+<destination>, which will be created if necessary. The -v option makes
118
+the conversion script very chatty.
119
+
120
+The import checks out from CVS every revision of every file. Reportedly
121
+cvsimport can average some twenty revisions per second, so for a
122
+medium-sized project this should not take more than a couple of minutes.
123
+Larger projects or remote repositories may take longer.
124
+
125
+The main trunk is stored in the git branch named `origin`, and additional
126
+CVS branches are stored in git branches with the same names. The most
127
+recent version of the main trunk is also left checked out on the `master`
128
+branch, so you can start adding your own changes right away.
129
+
130
+The import is incremental, so if you call it again next month it will
131
+fetch any CVS updates that have been made in the meantime. For this to
132
+work, you must not modify the imported branches; instead, create new
133
+branches for your own changes, and merge in the imported branches as
134
+necessary.
135
136
Advanced Shared Repository Management
137
-------------------------------------
144
link:howto/update-hook-example.txt[Controlling access to branches using
145
update hooks].
146
191
-CVS annotate
192
-------------
147
+Providing CVS Access to a git Repository
148
+----------------------------------------
149
+
150
+It is also possible to provide true CVS access to a git repository, so
151
+that developers can still use CVS; see gitlink:git-cvsserver[1] for
152
+details.
153
+
154
+Alternative Development Models
155
+------------------------------
156
+
157
+CVS users are accustomed to giving a group of developers commit access to
158
+a common repository. As we've seen, this is also possible with git.
159
+However, the distributed nature of git allows other development models,
160
+and you may want to first consider whether one of them might be a better
161
+fit for your project.
162
+
163
+For example, you can choose a single person to maintain the project's
164
+primary public repository. Other developers then clone this repository
165
+and each work in their own clone. When they have a series of changes that
166
+they're happy with, they ask the maintainer to pull from the branch
167
+containing the changes. The maintainer reviews their changes and pulls
168
+them into the primary repository, which other developers pull from as
169
+necessary to stay coordinated. The Linux kernel and other projects use
170
+variants of this model.
171
194
-So, something has gone wrong, and you don't know whom to blame, and
195
-you're an ex-CVS user and used to do "cvs annotate" to see who caused
196
-the breakage. You're looking for the "git annotate", and it's just
197
-claiming not to find such a script. You're annoyed.
198
-
199
-Yes, that's right. Core git doesn't do "annotate", although it's
200
-technically possible, and there are at least two specialized scripts out
201
-there that can be used to get equivalent information (see the git
202
-mailing list archives for details).
203
-
204
-git has a couple of alternatives, though, that you may find sufficient
205
-or even superior depending on your use. One is called "git-whatchanged"
206
-(for obvious reasons) and the other one is called "pickaxe" ("a tool for
207
-the software archaeologist").
208
-
209
-The "git-whatchanged" script is a truly trivial script that can give you
210
-a good overview of what has changed in a file or a directory (or an
211
-arbitrary list of files or directories). The "pickaxe" support is an
212
-additional layer that can be used to further specify exactly what you're
213
-looking for, if you already know the specific area that changed.
214
-
215
-Let's step back a bit and think about the reason why you would
216
-want to do "cvs annotate a-file.c" to begin with.
217
-
218
-You would use "cvs annotate" on a file when you have trouble
219
-with a function (or even a single "if" statement in a function)
220
-that happens to be defined in the file, which does not do what
221
-you want it to do. And you would want to find out why it was
222
-written that way, because you are about to modify it to suit
223
-your needs, and at the same time you do not want to break its
224
-current callers. For that, you are trying to find out why the
225
-original author did things that way in the original context.
226
-
227
-Many times, it may be enough to see the commit log messages of
228
-commits that touch the file in question, possibly along with the
229
-patches themselves, like this:
230
-
231
- $ git-whatchanged -p a-file.c
232
-
233
-This will show log messages and patches for each commit that
234
-touches a-file.
235
-
236
-This, however, may not be very useful when this file has many
237
-modifications that are not related to the piece of code you are
238
-interested in. You would see many log messages and patches that
239
-do not have anything to do with the piece of code you are
240
-interested in. As an example, assuming that you have this piece
241
-of code that you are interested in in the HEAD version:
242
-
243
- if (frotz) {
244
- nitfol();
245
- }
246
-
247
-you would use git-rev-list and git-diff-tree like this:
248
-
249
- $ git-rev-list HEAD |
250
- git-diff-tree --stdin -v -p -S'if (frotz) {
251
- nitfol();
252
- }'
253
-
254
-We have already talked about the "\--stdin" form of git-diff-tree
255
-command that reads the list of commits and compares each commit
256
-with its parents (otherwise you should go back and read the tutorial).
257
-The git-whatchanged command internally runs
258
-the equivalent of the above command, and can be used like this:
259
-
260
- $ git-whatchanged -p -S'if (frotz) {
261
- nitfol();
262
- }'
263
-
264
-When the -S option is used, git-diff-tree command outputs
265
-differences between two commits only if one tree has the
266
-specified string in a file and the corresponding file in the
267
-other tree does not. The above example looks for a commit that
268
-has the "if" statement in it in a file, but its parent commit
269
-does not have it in the same shape in the corresponding file (or
270
-the other way around, where the parent has it and the commit
271
-does not), and the differences between them are shown, along
272
-with the commit message (thanks to the -v flag). It does not
273
-show anything for commits that do not touch this "if" statement.
274
-
275
-Also, in the original context, the same statement might have
276
-appeared at first in a different file and later the file was
277
-renamed to "a-file.c". CVS annotate would not help you to go
278
-back across such a rename, but git would still help you in such
279
-a situation. For that, you can give the -C flag to
280
-git-diff-tree, like this:
281
-
282
- $ git-whatchanged -p -C -S'if (frotz) {
283
- nitfol();
284
- }'
285
-
286
-When the -C flag is used, file renames and copies are followed.
287
-So if the "if" statement in question happens to be in "a-file.c"
288
-in the current HEAD commit, even if the file was originally
289
-called "o-file.c" and then renamed in an earlier commit, or if
290
-the file was created by copying an existing "o-file.c" in an
291
-earlier commit, you will not lose track. If the "if" statement
292
-did not change across such a rename or copy, then the commit that
293
-does rename or copy would not show in the output, and if the
294
-"if" statement was modified while the file was still called
295
-"o-file.c", it would find the commit that changed the statement
296
-when it was in "o-file.c".
297
-
298
-NOTE: The current version of "git-diff-tree -C" is not eager
299
- enough to find copies, and it will miss the fact that a-file.c
300
- was created by copying o-file.c unless o-file.c was somehow
301
- changed in the same commit.
302
-
303
-You can use the --pickaxe-all flag in addition to the -S flag.
304
-This causes the differences from all the files contained in
305
-those two commits, not just the differences between the files
306
-that contain this changed "if" statement:
307
-
308
- $ git-whatchanged -p -C -S'if (frotz) {
309
- nitfol();
310
- }' --pickaxe-all
311
-
312
-NOTE: This option is called "--pickaxe-all" because -S
313
- option is internally called "pickaxe", a tool for software
314
- archaeologists.
172
+With a small group, developers may just pull changes from each other's
173
+repositories without the need for a central maintainer.