@matheusbsbs / matheus-bagliano / commits / cd976f5c52
Fork 0

Documentation: reorganize cvs-migration.txt

Modify cvs-migration.txt so it explains first how to develop against a shared repository, then how to set up a shared repository, then how to import a repository from cvs. Though this seems chronologically backwards, it's still readable in this order, and it puts the more commonly needed material closer to the front. Remove the annotate/pickaxe section; perhaps it can find a place elsewhere in the future. Remove most of the "why git is better than cvs" stuff from the introduction. Add some minor clarifications, including two that have come up several times on the mailing list: 1. Recommend committing any changes before running pull. 2. Note that changes must be commited before they can be pushed. Update the clone discussion to reflect the new --use-separate-remotes default, and add a brief mention of git-cvsserver. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu> Signed-off-by: Junio C Hamano <junkio@cox.net>

J. Bruce Fields committed Dec 6, 2006 at 23:18 UTC cd976f5c52694acb4b23c3f2425ed4f0a47ec799
1 file changed +104 -245
Documentation/cvs-migration.txt
+104 -245
@@ -1,121 +1,21 @@
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
@@ -129,7 +29,8 @@ $ git pull origin
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 ================================
@@ -137,8 +38,8 @@ The first `git clone` places the following in the
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
@@ -161,21 +62,76 @@ in the local repository. So the last `push` can be done with either of:
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 -------------------------------------
@@ -188,127 +144,30 @@ You can enforce finer grained permissions using update hooks. See
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.