1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
\r
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
\r
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
\r
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
\r
6 <meta name="generator" content="AsciiDoc 7.0.1" />
\r
7 <style type="text/css">
\r
9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
\r
11 border: 1px solid red;
\r
16 margin: 1em 5% 1em 5%;
\r
20 a:visited { color: fuchsia; }
\r
34 h1, h2, h3, h4, h5, h6 {
\r
36 font-family: sans-serif;
\r
38 margin-bottom: 0.5em;
\r
43 border-bottom: 2px solid silver;
\r
46 border-bottom: 2px solid silver;
\r
56 border: 1px solid silver;
\r
61 margin-bottom: 0.5em;
\r
71 font-family: sans-serif;
\r
78 font-family: sans-serif;
\r
82 font-family: sans-serif;
\r
84 border-top: 2px solid silver;
\r
90 padding-bottom: 0.5em;
\r
94 padding-bottom: 0.5em;
\r
98 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
\r
99 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
\r
100 div.admonitionblock {
\r
103 margin-bottom: 1.5em;
\r
105 div.admonitionblock {
\r
107 margin-bottom: 2.5em;
\r
110 div.content { /* Block element content. */
\r
114 /* Block element titles. */
\r
115 div.title, caption.title {
\r
116 font-family: sans-serif;
\r
120 margin-bottom: 0.5em;
\r
126 td div.title:first-child {
\r
129 div.content div.title:first-child {
\r
132 div.content + div.title {
\r
136 div.sidebarblock > div.content {
\r
137 background: #ffffee;
\r
138 border: 1px solid silver;
\r
142 div.listingblock > div.content {
\r
143 border: 1px solid silver;
\r
144 background: #f4f4f4;
\r
148 div.quoteblock > div.content {
\r
149 padding-left: 2.0em;
\r
151 div.quoteblock .attribution {
\r
155 div.admonitionblock .icon {
\r
156 vertical-align: top;
\r
159 text-decoration: underline;
\r
161 padding-right: 0.5em;
\r
163 div.admonitionblock td.content {
\r
164 padding-left: 0.5em;
\r
165 border-left: 2px solid silver;
\r
168 div.exampleblock > div.content {
\r
169 border-left: 2px solid silver;
\r
173 div.verseblock div.content {
\r
177 div.imageblock div.content { padding-left: 0; }
\r
178 div.imageblock img { border: 1px solid silver; }
\r
179 span.image img { border-style: none; }
\r
183 margin-bottom: 0.8em;
\r
188 font-style: italic;
\r
190 dd > *:first-child {
\r
195 list-style-position: outside;
\r
198 list-style-type: lower-alpha;
\r
201 div.tableblock > table {
\r
202 border-color: #527bbd;
\r
206 font-family: sans-serif;
\r
215 margin-bottom: 0.8em;
\r
218 vertical-align: top;
\r
219 font-style: italic;
\r
220 padding-right: 0.8em;
\r
223 vertical-align: top;
\r
227 div#footer-badges { display: none; }
\r
229 /* Workarounds for IE6's broken and incomplete CSS2. */
\r
231 div.sidebar-content {
\r
232 background: #ffffee;
\r
233 border: 1px solid silver;
\r
236 div.sidebar-title, div.image-title {
\r
237 font-family: sans-serif;
\r
240 margin-bottom: 0.5em;
\r
243 div.listingblock div.content {
\r
244 border: 1px solid silver;
\r
245 background: #f4f4f4;
\r
249 div.quoteblock-content {
\r
250 padding-left: 2.0em;
\r
253 div.exampleblock-content {
\r
254 border-left: 2px solid silver;
\r
255 padding-left: 0.5em;
\r
258 <title>git for CVS users</title>
\r
262 <h1>git for CVS users</h1>
\r
264 <div id="preamble">
\r
265 <div class="sectionbody">
\r
266 <p>Ok, so you're a CVS user. That's ok, it's a treatable condition, and the
\r
267 first step to recovery is admitting you have a problem. The fact that
\r
268 you are reading this file means that you may be well on that path
\r
270 <p>The thing about CVS is that it absolutely sucks as a source control
\r
271 manager, and you'll thus be happy with almost anything else. git,
\r
272 however, may be a bit <em>too</em> different (read: "good") for your taste, and
\r
273 does a lot of things differently.</p>
\r
274 <p>One particular suckage of CVS is very hard to work around: CVS is
\r
275 basically a tool for tracking <em>file</em> history, while git is a tool for
\r
276 tracking <em>project</em> history. This sometimes causes problems if you are
\r
277 used to doing very strange things in CVS, in particular if you're doing
\r
278 things like making branches of just a subset of the project. git can't
\r
279 track that, since git never tracks things on the level of an individual
\r
280 file, only on the whole project level.</p>
\r
281 <p>The good news is that most people don't do that, and in fact most sane
\r
282 people think it's a bug in CVS that makes it tag (and check in changes)
\r
283 one file at a time. So most projects you'll ever see will use CVS
\r
284 <em>as if</em> it was sane. In which case you'll find it very easy indeed to
\r
285 move over to git.</p>
\r
286 <p>First off: this is not a git tutorial. See
\r
287 <a href="tutorial.html">Documentation/tutorial.txt</a> for how git
\r
288 actually works. This is more of a random collection of gotcha's
\r
289 and notes on converting from CVS to git.</p>
\r
290 <p>Second: CVS has the notion of a "repository" as opposed to the thing
\r
291 that you're actually working in (your working directory, or your
\r
292 "checked out tree"). git does not have that notion at all, and all git
\r
293 working directories <em>are</em> the repositories. However, you can easily
\r
294 emulate the CVS model by having one special "global repository", which
\r
295 people can synchronize with. See details later, but in the meantime
\r
296 just keep in mind that with git, every checked out working tree will
\r
297 have a full revision control history of its own.</p>
\r
300 <h2>Importing a CVS archive</h2>
\r
301 <div class="sectionbody">
\r
302 <p>Ok, you have an old project, and you want to at least give git a chance
\r
303 to see how it performs. The first thing you want to do (after you've
\r
304 gone through the git tutorial, and generally familiarized yourself with
\r
305 how to commit stuff etc in git) is to create a git'ified version of your
\r
307 <p>Happily, that's very easy indeed. git will do it for you, although git
\r
308 will need the help of a program called "cvsps":</p>
\r
309 <div class="literalblock">
\r
310 <div class="content">
\r
311 <pre><tt>http://www.cobite.com/cvsps/</tt></pre>
\r
313 <p>which is not actually related to git at all, but which makes CVS usage
\r
314 look almost sane (ie you almost certainly want to have it even if you
\r
315 decide to stay with CVS). However, git will want <em>at least</em> version 2.1
\r
316 of cvsps (available at the address above), and in fact will currently
\r
317 refuse to work with anything else.</p>
\r
318 <p>Once you've gotten (and installed) cvsps, you may or may not want to get
\r
319 any more familiar with it, but make sure it is in your path. After that,
\r
320 the magic command line is</p>
\r
321 <div class="literalblock">
\r
322 <div class="content">
\r
323 <pre><tt>git cvsimport -v -d <cvsroot> -C <destination> <module></tt></pre>
\r
325 <p>which will do exactly what you'd think it does: it will create a git
\r
326 archive of the named CVS module. The new archive will be created in the
\r
327 subdirectory named <destination>; it'll be created if it doesn't exist.
\r
328 Default is the local directory.</p>
\r
329 <p>It can take some time to actually do the conversion for a large archive
\r
330 since it involves checking out from CVS every revision of every file,
\r
331 and the conversion script is reasonably chatty unless you omit the <em>-v</em>
\r
332 option, but on some not very scientific tests it averaged about twenty
\r
333 revisions per second, so a medium-sized project should not take more
\r
334 than a couple of minutes. For larger projects or remote repositories,
\r
335 the process may take longer.</p>
\r
336 <p>After the (initial) import is done, the CVS archive's current head
\r
337 revision will be checked out — thus, you can start adding your own
\r
338 changes right away.</p>
\r
339 <p>The import is incremental, i.e. if you call it again next month it'll
\r
340 fetch any CVS updates that have been happening in the meantime. The
\r
341 cut-off is date-based, so don't change the branches that were imported
\r
343 <p>You can merge those updates (or, in fact, a different CVS branch) into
\r
344 your main branch:</p>
\r
345 <div class="literalblock">
\r
346 <div class="content">
\r
347 <pre><tt>git resolve HEAD origin "merge with current CVS HEAD"</tt></pre>
\r
349 <p>The HEAD revision from CVS is named "origin", not "HEAD", because git
\r
350 already uses "HEAD". (If you don't like <em>origin</em>, use cvsimport's
\r
351 <em>-o</em> option to change it.)</p>
\r
353 <h2>Emulating CVS behaviour</h2>
\r
354 <div class="sectionbody">
\r
355 <p>So, by now you are convinced you absolutely want to work with git, but
\r
356 at the same time you absolutely have to have a central repository.
\r
357 Step back and think again. Okay, you still need a single central
\r
358 repository? There are several ways to go about that:</p>
\r
362 Designate a person responsible to pull all branches. Make the
\r
363 repository of this person public, and make every team member
\r
364 pull regularly from it.
\r
369 Set up a public repository with read/write access for every team
\r
370 member. Use "git pull/push" as you used "cvs update/commit". Be
\r
371 sure that your repository is up to date before pushing, just
\r
372 like you used to do with "cvs commit"; your push will fail if
\r
373 what you are pushing is not up to date.
\r
378 Make the repository of every team member public. It is the
\r
379 responsibility of each single member to pull from every other
\r
385 <h2>CVS annotate</h2>
\r
386 <div class="sectionbody">
\r
387 <p>So, something has gone wrong, and you don't know whom to blame, and
\r
388 you're an ex-CVS user and used to do "cvs annotate" to see who caused
\r
389 the breakage. You're looking for the "git annotate", and it's just
\r
390 claiming not to find such a script. You're annoyed.</p>
\r
391 <p>Yes, that's right. Core git doesn't do "annotate", although it's
\r
392 technically possible, and there are at least two specialized scripts out
\r
393 there that can be used to get equivalent information (see the git
\r
394 mailing list archives for details).</p>
\r
395 <p>git has a couple of alternatives, though, that you may find sufficient
\r
396 or even superior depending on your use. One is called "git-whatchanged"
\r
397 (for obvious reasons) and the other one is called "pickaxe" ("a tool for
\r
398 the software archaeologist").</p>
\r
399 <p>The "git-whatchanged" script is a truly trivial script that can give you
\r
400 a good overview of what has changed in a file or a directory (or an
\r
401 arbitrary list of files or directories). The "pickaxe" support is an
\r
402 additional layer that can be used to further specify exactly what you're
\r
403 looking for, if you already know the specific area that changed.</p>
\r
404 <p>Let's step back a bit and think about the reason why you would
\r
405 want to do "cvs annotate a-file.c" to begin with.</p>
\r
406 <p>You would use "cvs annotate" on a file when you have trouble
\r
407 with a function (or even a single "if" statement in a function)
\r
408 that happens to be defined in the file, which does not do what
\r
409 you want it to do. And you would want to find out why it was
\r
410 written that way, because you are about to modify it to suit
\r
411 your needs, and at the same time you do not want to break its
\r
412 current callers. For that, you are trying to find out why the
\r
413 original author did things that way in the original context.</p>
\r
414 <p>Many times, it may be enough to see the commit log messages of
\r
415 commits that touch the file in question, possibly along with the
\r
416 patches themselves, like this:</p>
\r
417 <div class="literalblock">
\r
418 <div class="content">
\r
419 <pre><tt>$ git-whatchanged -p a-file.c</tt></pre>
\r
421 <p>This will show log messages and patches for each commit that
\r
422 touches a-file.</p>
\r
423 <p>This, however, may not be very useful when this file has many
\r
424 modifications that are not related to the piece of code you are
\r
425 interested in. You would see many log messages and patches that
\r
426 do not have anything to do with the piece of code you are
\r
427 interested in. As an example, assuming that you have this piece
\r
428 of code that you are interested in in the HEAD version:</p>
\r
429 <div class="literalblock">
\r
430 <div class="content">
\r
431 <pre><tt>if (frotz) {
\r
435 <p>you would use git-rev-list and git-diff-tree like this:</p>
\r
436 <div class="literalblock">
\r
437 <div class="content">
\r
438 <pre><tt>$ git-rev-list HEAD |
\r
439 git-diff-tree --stdin -v -p -S'if (frotz) {
\r
443 <p>We have already talked about the "--stdin" form of git-diff-tree
\r
444 command that reads the list of commits and compares each commit
\r
445 with its parents (otherwise you should go back and read the tutorial).
\r
446 The git-whatchanged command internally runs
\r
447 the equivalent of the above command, and can be used like this:</p>
\r
448 <div class="literalblock">
\r
449 <div class="content">
\r
450 <pre><tt>$ git-whatchanged -p -S'if (frotz) {
\r
454 <p>When the -S option is used, git-diff-tree command outputs
\r
455 differences between two commits only if one tree has the
\r
456 specified string in a file and the corresponding file in the
\r
457 other tree does not. The above example looks for a commit that
\r
458 has the "if" statement in it in a file, but its parent commit
\r
459 does not have it in the same shape in the corresponding file (or
\r
460 the other way around, where the parent has it and the commit
\r
461 does not), and the differences between them are shown, along
\r
462 with the commit message (thanks to the -v flag). It does not
\r
463 show anything for commits that do not touch this "if" statement.</p>
\r
464 <p>Also, in the original context, the same statement might have
\r
465 appeared at first in a different file and later the file was
\r
466 renamed to "a-file.c". CVS annotate would not help you to go
\r
467 back across such a rename, but git would still help you in such
\r
468 a situation. For that, you can give the -C flag to
\r
469 git-diff-tree, like this:</p>
\r
470 <div class="literalblock">
\r
471 <div class="content">
\r
472 <pre><tt>$ git-whatchanged -p -C -S'if (frotz) {
\r
476 <p>When the -C flag is used, file renames and copies are followed.
\r
477 So if the "if" statement in question happens to be in "a-file.c"
\r
478 in the current HEAD commit, even if the file was originally
\r
479 called "o-file.c" and then renamed in an earlier commit, or if
\r
480 the file was created by copying an existing "o-file.c" in an
\r
481 earlier commit, you will not lose track. If the "if" statement
\r
482 did not change across such a rename or copy, then the commit that
\r
483 does rename or copy would not show in the output, and if the
\r
484 "if" statement was modified while the file was still called
\r
485 "o-file.c", it would find the commit that changed the statement
\r
486 when it was in "o-file.c".</p>
\r
487 <div class="admonitionblock">
\r
490 <div class="title">Note</div>
\r
492 <td class="content">The current version of "git-diff-tree -C" is not eager
\r
493 enough to find copies, and it will miss the fact that a-file.c
\r
494 was created by copying o-file.c unless o-file.c was somehow
\r
495 changed in the same commit.</td>
\r
498 <p>You can use the —pickaxe-all flag in addition to the -S flag.
\r
499 This causes the differences from all the files contained in
\r
500 those two commits, not just the differences between the files
\r
501 that contain this changed "if" statement:</p>
\r
502 <div class="literalblock">
\r
503 <div class="content">
\r
504 <pre><tt>$ git-whatchanged -p -C -S'if (frotz) {
\r
506 }' --pickaxe-all</tt></pre>
\r
508 <div class="admonitionblock">
\r
511 <div class="title">Note</div>
\r
513 <td class="content">This option is called "—pickaxe-all" because -S
\r
514 option is internally called "pickaxe", a tool for software
\r
515 archaeologists.</td>
\r
520 <div id="footer-text">
\r
521 Last updated 06-Jan-2006 17:12:56 PDT
\r
projects / git.git / blob