course/cvs.html

   1 <?xml version="1.0" encoding="iso-8859-1" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   3         "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   5 <head>
   6         <title>Git - CVS Crash Course</title>
   7         <meta name="description" content="CVS to Git crash course tutorial" />
   8         <meta name="author" content="Petr Baudis" />
   9         <meta http-equiv="reply-to" content="pasky@suse.cz" />
  10         <meta http-equiv="content-language" content="en" />
  11         <meta http-equiv="content-type" content="text/html; charset=iso-8859-1" />
  12         <link type="text/css" rel="stylesheet" media="screen" href="../stylesheets/screen.css" />
  13         <link type="text/css" title="Default" rel="stylesheet" media="screen" href="../stylesheets/screen-default.css" />
  14         <link type="text/css" title="Gitweb Gray" rel="alternate stylesheet" media="screen" href="../stylesheets/screen-gitweb-gray.css" />
  15         <link type="text/css" title="Blue" rel="alternate stylesheet" media="screen" href="../stylesheets/screen-blue.css" />
  16         <link type="text/css" title="Green" rel="alternate stylesheet" media="screen" href="../stylesheets/screen-green.css" />
  17         <link rel="icon" href="favicon.png" type="image/png" />
  18 </head>
  19
  20 <body>
  21
  22 <table border="1" summary="Navigation links" class="header" width="100%"><tr><td>
  23         <a href="../index.html" id="top"><img src="../git-logo.png" width="72" height="27" alt="Git"
  24                 style="border-width:0px;"/></a>
  25         <span class="hide">:</span>
  26         <span class="menu">
  27                 <a href="../index.html">Home</a> |
  28                 <a href="http://www.kernel.org/pub/software/scm/git/docs/">Documentation</a> |
  29                 <a href="http://git.or.cz/gitwiki">Wiki</a> |
  30                 <a href="http://www.kernel.org/pub/software/scm/git/">Download Site</a> |
  31                 <a href="http://www.kernel.org/git/?p=git/git.git;a=summary">Git's Gitweb</a>
  32         </span>
  33 </td></tr></table>
  34
  35 <h1>Git - CVS Crash Course</h1>
  36
  37 <p>Welcome to the Git version control system! Here we will briefly
  38 introduce to Git usage based on your current CVS knowledge. You will
  39 need the latest <a href="http://git.or.cz/">Git</a> and Cogito packages installed;
  40 <a href="http://git.or.cz/cogito/">Cogito</a> is a user
  41 interface for Git which extends it for easier use, while you can still
  42 use directly Git for more advanced operations; you can also perform all of the
  43 below using Git commands, but the core Git interface is more elaborate and complicated.
  44 There is also <a href="http://www.kernel.org/pub/software/scm/git/docs/cvs-migration.html">a
  45 more technical CVS to Git migration HOWTO</a> in the Git documentation
  46 which uses Git commands only, but covers only some specific differences.</p>
  47
  48 <ul>
  49         <li><a href="#read">How to Read Me</a></li>
  50         <li><a href="#know">Things You Should Know</a></li>
  51         <li><a href="#own">Your Very Own</a></li>
  52         <li><a href="#branch">Tagging and Branching</a></li>
  53         <li><a href="#remote">Going Remote</a></li>
  54 </ul>
  55
  56 <div align="center"><table class="relnotes" style="border: 1px">
  57 <tr><td>
  58 <p style="margin: 0em 0.4em">If you are just after tracking someone else's project,
  59 this is to get you started quickly:</p>
  60 <p/>
  61 <div align="center">
  62 <table class="ccmd" style="margin:0em"><tr><td class="g">cg clone <em>url</em><br />cg update</td><td>cvs&nbsp;-d<em>root</em>&nbsp;checkout&nbsp;<em>module</em><br />cvs update -dP</td></tr></table>
  63 </div>
  64 </td></tr>
  65 </table></div>
  66
  67
  68 <hr />
  69
  70 <h2 id="read">How to Read Me</h2>
  71
  72 <p>In those small tables, at the left we always list the Cogito/Git commands
  73 for the task, while at the right the corresponding CVS commands you would use
  74 for the job are listed.  If you are in hurry, just skimming over them should
  75 give you a good idea about the Cogito usage basics.</p>
  76
  77 <p>Before running any command the first time, it's recommended that you
  78 at least quickly skim through its manual page. Many of the commands have
  79 very useful and interesting features (that we won't list here) and sometimes
  80 there are some extra notes you might want to know. There's a quick usage
  81 help available for the Cogito commands if you pass them the <code>--help</code>
  82 switch.</p>
  83
  84
  85 <h2 id="know">Things You Should Know</h2>
  86
  87 <p>There is couple of important concepts it is good to know when
  88 starting with Git. If you are in hurry though, you can skip this
  89 section and only get back to it when you get seriously confused;
  90 it should be possible to pick up with just using your intuition.</p>
  91
  92 <p>With CVS, for each project there is a single repository at some
  93 detached central place where all the history is and which you checkout
  94 and commit into. Git works differently, each copy of the project tree
  95 (we call that the <em>working copy</em>) carries its own repository
  96 around (in the <code>.git</code> subdirectory in the project tree root).
  97 You can alos have a so-called <em>bare repository</em> which is not
  98 attached to a working copy; that is useful especially when you want
  99 to publish your repository. We will get to that.</p>
 100
 101 <p>CVS has the repositories partitioned to <em>modules</em>;
 102 there is no such thing in Git, you just create several separate
 103 repositories.</p>
 104
 105 <p>CVS identifies revisions with the RCS ids - few numbers delimited
 106 with dots. That is impractical in distributed systems like Git. Git
 107 identifies revisions with SHA1 ids, which are long 128bit numbers
 108 written in hex. It may look scary at first, but in practice it is
 109 not a big hurdle - you can refer to the latest revision by <code>HEAD</code>
 110 and its parent as <code>HEAD^</code> (you can go on adding carrets),
 111 cut'n'paste helps a lot and you can write only the few leading digits
 112 of a revision - as long as it is unique, Git will guess the rest.
 113 (You can do even more advanced stuff with revision specifiers, see the
 114 <a href="http://www.kernel.org/pub/software/scm/git/docs/git-rev-parse.html">git-rev-parse manpage</a> for details.)</p>
 115
 116 <p>Each commit has an <em>author</em> and a <em>committer</em> field,
 117 which record who and when <em>created</em> the change and who <em>committed</em> it
 118 (Git is designed to work well with patches coming by mail - in that case,
 119 the author and the committer will be different). Git will try to guess
 120 your realname and email, but especially with email it is likely to get it wrong.
 121 You can check it using <code class="g">git-var -l</code>; see
 122 <a href="http://www.kernel.org/pub/software/scm/cogito/docs/cg-commit.1.html">cg-commit manpage</a>
 123 on various ways of overriding it.</p>
 124
 125 <p>The Cogito commands are in the form <code>cg command</code>,
 126 the Git commands take the form of <code>git command</code>.
 127 In both cases, you can interchangeably use the <code>cg-command</code>
 128 and <code>git-command</code> form as well.</p>
 129
 130 <p>Cogito can produce colourful output with some commands; since
 131 some people hate colors way more than the rest likes them, by default
 132 the colors are turned off. If you would like to have colors in your
 133 output, create <code>~/.cgrc</code> and put this inside:
 134 <pre>
 135 cg-diff -c
 136 cg-help -c
 137 cg-log -c
 138 </pre>
 139 The format and purpose is the same as of the <code>~/.cvsrc</code>
 140 file; you can add other commands and switches there later if you wish
 141 (my tip is <code>-f</code> for <code>cg-log</code>).</p>
 142
 143 <p>Also, you may find it convenient to watch your repository using
 144 the <code class="g">gitk</code> repository as you go.</p>
 145
 146
 147 <h2 id="own">Your Very Own</h2>
 148
 149 <p>For the first introduction, let's make your project tracked by Git
 150 and see how we get around to do daily development in it. Let's
 151 <code>cd</code> to the directory with your project and initialize
 152 a brand new Git repository with it:</p>
 153
 154 <table class="ccmd"><tr><td class="g">cg init</td>
 155 <td>cvs -d<em>repo</em> init<br/>cvs import <em>FOO BAR</em></td></tr></table>
 156
 157 <p>As we already mentioned, there are no modules; due to superior
 158 branching support in Git. There is no vendor branch in Git either
 159 (we will cover how to do vendor tracking in Git at a later time in
 160 the <a href="stgit.html">StGit Crash Course</a>). Thus there
 161 is no need for two separate commands and <code>cg init</code>
 162 will both initialize the repository and create the initial import.
 163 </p>
 164
 165 <p>Now your tree is officially tracked by Git. You can explore the
 166 <code class="g">.git</code> subdirectory a bit if you want, or don't if you
 167 don't care. Do some random changes to your tree now - poke into few
 168 files or such. Let's check what we've done:</p>
 169
 170 <table class="ccmd"><tr><td class="g">cg diff</td><td>cvs diff -u | less</td></tr></table>
 171
 172 <p>That's it. This is one of the more powerful commands; just like
 173 with CVS, you can pass <code>-r</code>s, limit the diff to specific
 174 directories or files and so on. Git embeds special information in
 175 the diffs about adds, removals and mode changes:</p>
 176
 177 <table class="ccmd"><tr><td class="g">cg patch</td><td>patch -p0</td></tr></table>
 178
 179 <p>That will apply the patch while telling Git about and performing
 180 those "meta-changes".</p>
 181
 182 <p>There is a more conscise changes representation available:</p>
 183
 184 <table class="ccmd"><tr><td class="g">cg status</td><td>(cvs update)</td></tr></table>
 185
 186 <p><code>cg status</code> will not update your working copy, though,
 187 only show the conscise changes summary as well as list any files
 188 that you haven't either ignored or told Git about. In addition,
 189 it will also show some cryptic line at the top (with "<code>master</code>"
 190 inside) - ignore it for now, we'll learn more about it later.</p>
 191
 192 <p>While we are at the status command, over time plenty of the
 193 "? lines" will get in there, denoting files not tracked by Git.
 194 Wait a moment if you want to add them, run <code class="g">cg clean</code>
 195 if you want to get rid all of them, or add them to the <code class="g">.gitignore</code>
 196 file if you want to keep them around untracked (works the same as <code>.cvsignore</code>).
 197
 198 <p>Another thing <code>cvs update</code> would do is restoring
 199 files you've accidentally removed. The command for that in Cogito
 200 is <code class="g">cg restore</code>; you can restore everything, just
 201 specified files, force it to overwrite missing files.
 202
 203 <p>So, just like in CVS, you need to tell Git when you add or
 204 remove any files. Additionaly, you can tell it when you <em>move</em>
 205 files around:</p>
 206
 207 <table class="ccmd"><tr>
 208 <td class="g">cg add <em>file</em><br />cg rm <em>file</em><br />cg mv <em>file</em></td>
 209 <td>cvs add <em>file</em><br />cvs remove</td></tr></table>
 210
 211 <p>Cogito is more promising than CVS here; especially, you can
 212 remove files that are yet present in the working directory
 213 (<code>cg rm</code> can remove them for you if you pass it
 214 the <code>-f</code> switch) - saves a lot of annoyance when
 215 removing files matching to a wildcard.  You can also recursively
 216 add/remove whole directories and so on; Cogito's cool!</p>
 217
 218 <p>So, it's about time we committed our changes. Big surprise
 219 about the command:</p>
 220
 221 <table class="ccmd"><tr><td class="g">cg commit</td><td>cvs commit</td></tr></table>
 222
 223 <p>As with CVS, you can limit the commit only to specified files
 224 and so on. Few words on the commit message: it is <em>customary</em>
 225 to have a short commit summary as the first line of the message,
 226 because various tools listing commits frequently show only the
 227 first line of the message You can specify the commit message
 228 using the <code>-m</code> parameter as you are used, but there're
 229 two differences - the text gets autoformatted to paragraphs and
 230 you can pass several <code>-m</code> arguments and they will create
 231 separate paragraphs in the commit message:</p>
 232
 233 <pre>
 234 cg commit -m"Short one-line description" -m"And here can come \
 235 your longer description of the commit, and it gets split out \
 236 and reflown to wrapped paragraphs just right."
 237 </pre>
 238
 239 <p>If you don't pass any <code>-m</code> parameter or pass
 240 the <code>-e</code> parameter, your favorite <code>$EDITOR</code>
 241 will get run and you can compose your commit message there,
 242 just as with CVS. In addition, the list of files to be committed
 243 is shown and you can actually delete lines with the files you don't
 244 want to commit and they won't be. You can also adjust the authorship
 245 information in the editor.</p>
 246
 247 <p>And as a bonus, if you pass it the <code>-p</code> parameter
 248 it will show the whole patch being committed in the editor
 249 so that you can do a quick last-time review. And you can manually
 250 modify the patch and your changes will get propagated to the
 251 commit (and your working tree).</p>
 252
 253 <p>By the way, if you screwed up committing, there's not much you
 254 can do with CVS, except using some enigmatic <code>cvs admin</code>
 255 subcommands.  Git does better - you can amend your latest commit
 256 (re-edit the metadata as well as update the tree) using
 257 <code class="g">cg commit --amend</code>, or toss your latest
 258 commit away completely using <code class="g">cg admin-uncommit</code>.</p>
 259
 260 <p>Now that we have committed some stuff, you might want to review
 261 your history:</p>
 262
 263 <table class="ccmd"><tr><td class="g">cg log<br />cg seek <em>rev</em><br />git blame <em>file</em></td><td>cvs log<br />cvs checkout -r <em>tag</em><br />cvs annotate <em>file</em></td></tr></table>
 264
 265 <p>The log command works quite similar in CVS and Git; again,
 266 <code>cg log</code> is quite powerful, please look through
 267 its options to see some of the stuff it can do.</p>
 268
 269 <p>To move your tree to some older revision, use the seek command
 270 (and pass it no arguments to go back to your latest revision_.
 271 Note that this is only for "temporary excursions" - if you want to
 272 just reset your history and make a given commit your new head, think
 273 again and if you are sure, <code class="g">cg switch -f -r <em>newrev</em> master</code>
 274 (this will be perhaps made simpler in the future, we will review
 275 the switch command in more detail in the future).</p>
 276
 277 <p>Git now has an annotation command akin to CVS', but there are
 278 big chances that you probably want to do something different! Usually,
 279 when using annotate you are looking for the origin of some piece of
 280 code, and the so-called <em>pickaxe</em> of Git is much more comfortable
 281 tool for that job (<a href="http://www.kernel.org/pub/software/scm/git/docs/cvs-migration.html">detailed discussion</a>;
 282 you may want to use <code>cg log -S <em>string</em></code> instead
 283 of <code>git log -S<em>string</em></code>, tho').</p>
 284
 285
 286 <h2 id="branch">Tagging and branching</h2>
 287
 288 <p>CVS marks certain checkpoints in history with tags. Git
 289 obviously can do that to, but not only are Git tags <em>much</em>
 290 faster to make (and actually reliable), but quite more powerful.
 291 The Git tag can have an arbitrary description attached (the first
 292 line is special as in the commit case), some people actually store
 293 the whole release announcements in the tag descriptions. The identity
 294 of the person who tagged is stored (again following the same rules
 295 as identity of the committer). You usually tag commits but if you
 296 want, you can tag files (or trees, but that's a bit lowlevel) as well.
 297 And the tag can be cryptographically PGP signed to verify the identity
 298 (by Git's nature of working, that signature also confirms the validity
 299 of the associated revision, its ihstory and tree). So, let's do it:</p>
 300
 301 <table class="ccmd"><tr><td class="g">cg tag <em>name</em></td><td>cvs tag <em>name</em></td></tr></table>
 302
 303 <p>To list tags in CVS, you run <code>cvs log</code> on some random
 304 file; kinda weird if you think about it, isn't it? In Git, you can
 305 find out using <code class="g">cg tag-ls</code> and show details
 306 (author, description, PGP signature verification, ...) using
 307 <code class="g">cg tag-show</code>.</p>
 308
 309 <p>Like CVS, Git can do branches, but Git's branches are again
 310 much faster and cheaper; in fact, Git encourages you to branch often
 311 and use branches extensively during regular development (with so-called
 312 <em>topic branches</em> dedicated to development of a particular feature).
 313 In CVS, you create a branch tag; in Git, there is a special command for
 314 working with branches (although funnily enough, there is certain architectural
 315 similarity between branchs/tags relation in CVS and Git).</p>
 316
 317 <table class="ccmd"><tr><td class="g">cg switch -c <em>branch</em><br />cg switch <em>branch</em></td><td>cvs tag -b <em>branch</em><br />cvs checkout -r <em>branch</em>name</td></tr></table>
 318
 319 <p>The first command creates a branch, the second command switches
 320 your tree to a certain branch. You can pass an <code>-r</code>
 321 argument to switch to base your new branch on a different
 322 revision than the latest one.</p>
 323
 324 <p>You can list your branches conveniently using the aforementioned
 325 <code>cg-status</code> command - the cryptic listing at the top is just
 326 the listing of branches. The current one is denoted by an "arrow".</p>
 327
 328 <p>Git supports merging between branches much better than CVS - history
 329 of both branches is preserved over the merges and repeated merges
 330 of the same branches are supported out-of-the-box. Make sure you are on
 331 one of the to-be-merged branches and merge the other one now:</p>
 332
 333 <table class="ccmd"><tr><td class="g">cg merge <em>branch</em></td><td>cvs update -j <em>branch</em></td></tr></table>
 334
 335 <p>If changes were made on only one of the branches since the last merge,
 336 they are simply replayed on your other branch (so-called <em>fast-forward merge</em>).
 337 If changes were made on both branches, they are merged intelligently
 338 (so-called <em>three-way merge</em>): if any changes conflicted, <code>cg merge</code>
 339 will report them and let you resolve them, updating the rest of the tree
 340 already to the result state; you can <code>cg commit</code> when you resolve
 341 the conflicts. If no changes conflicted, <code>cg commit</code> is invoked
 342 automatically, letting you edit the commit message (or you can do
 343 <code class="g">cg merge -n <em>branch</em></code> to review the merge
 344 result and then do the commit yourself).</p>
 345
 346 <p>Sometimes, you <em>do</em> want to throw away the history of one of the
 347 branches, e.g. when you did a fine-tracked development of a topic and
 348 now want to squash it to a single conceptual change commit - just pass
 349 merge the <code class="g">--squash</code> switch. Also, sometimes you may want to
 350 join together two unrelated branches (coming from different projects;
 351 hold on, we'll get to that in a minute): <code class="g">-j</code> will take care
 352 of that.</p>
 353
 354 <p>Aside of merging, sometimes you want to just pick one commit from
 355 a different branch. We have already mentioned the command <code>cg patch</code>.
 356 It can apply patches, but also autocommit them and extract them from given
 357 commits. <code class="g">cg patch -C <em>rev</em></code> combines both
 358 functionality and will <em>cherry pick</em> a given commit to your branch.</p>
 359
 360
 361 <h2 id="remote">Going Remote</h2>
 362
 363 <p>So far, we have neglected that Git is a <em>distributed</em> version
 364 control system. It is time for us to set the record straight - let's grab
 365 some stuff from remote sites.</p>
 366
 367 <p>If you are working on someone else's project, you usually want to <em>clone</em>
 368 its repository instead of starting your own. We've already mentioned that at the top
 369 of this document:</p>
 370
 371 <table class="ccmd"><tr><td class="g">cg clone <em>url</em></td><td>cvs&nbsp;-d<em>root</em>&nbsp;checkout&nbsp;<em>module</em></td></tr></table>
 372
 373 <p>Now you have got your <code>master</code> branch as when initializing
 374 a new repository, but in addition you got an <code>origin</code> remote
 375 branch. <em>Remote branch</em>, you ask? Well, so far we have worked
 376 only with local branches. Remote branches are a mirror image of branches
 377 in remote repositories and you don't ever switch to them directly or write
 378 to them. Let me repeat - you never mess with remote branches. If you want
 379 to switch to a remote branch, you need to create a corresponding local
 380 branch which will "track" the remote branch. In clone's default setup,
 381 the master local branch tracks the origin remote branch, which represents
 382 the remote repository.</p>
 383
 384 <p>You can add more remote branches, to a cloned repository as well as just
 385 an initialized one, using <code class="g">cg branch-add <em>branch</em> <em>url</em></code>.
 386 <code class="g">cg branch-ls</code> lists all the branches.</p>
 387
 388 <p>Now, how to get any new changes from a remote repository to your
 389 local branch? You fetch them: <code class="g">cg fetch <em>branch</em></code>.
 390 At this point they are in your local branch and you can examine them using
 391 <code>cg log -r <em>branch</em></code> (<code>cg log -r HEAD..<em>branch</em></code>
 392 to see just the changes you don't have in your branch), diff them, and obviously, merge them - just do
 393 <code>cg merge <em>branch</em></code>. Note that if you don't specify a branch
 394 for fetch or merge, it will conveniently default to origin.</p>
 395
 396 <p>Since you frequently just fetch + merge, there is a command to automate that:</p>
 397
 398 <table class="ccmd"><tr><td class="g">cg update <em>branch</em></td><td>cvs update -dP</td></tr></table>
 399
 400 <p>Again, it will default to origin if no branch was specified. It is recommended
 401 to use update instead of fetch + merge since it does the first thing even if
 402 the remote branch' history got altered (which is also a reason why altering
 403 history is discouraged at the moment you publish it).</p>
 404
 405 <p>So we can get updates from the remote side (<em>pull</em> changes).
 406 Can we do the opposite as well? <em>Push</em> our changes? Yes!
 407 We do <code class="g">cg push <em>branch</em></code> which will push
 408 our current branch to the given remote branch - note that this works
 409 generally only over SSH (or HTTP but with special webserver setup).
 410 It is highly recommended to setup a SSH key and an SSH agent mechanism
 411 so that you don't have to type in a password all the time.</p>
 412
 413 <p>One important thing is that you should push only to remote branches
 414 that are not currently checked out on the other side (for the same
 415 reasons you never switch to a remote branch locally)! Otherwise the
 416 working copy at the remote branch will get out of date and confusion
 417 will ensue. The best way to avoid that is to push only to remote
 418 repositories with no working copy at all - so called <em>bare</em>
 419 repositories which are commonly used for public access or developers'
 420 meeting point - just for exchange of history where a checked out copy
 421 would be a waste of space anyway. You can create such a repository
 422 using <code class="g">cg admin-setuprepo <em>path</em></code> - you
 423 can add additional options to make it shared for a UNIX group of users.</p>
 424
 425 <p>Git can work with the same workflow as CVS, with a group of developers
 426 using a single repository for exchange of their work - the only change
 427 is that their changes aren't submitted automatically but they have
 428 to push (however, you can setup a post-commit hook that will push for you
 429 every time you commit; that loses the flexibility to fix up a screwed
 430 commit, though). The developers have to have either an entry in htaccess
 431 (for HTTP DAV) or a UNIX account (for SSH) - you can restrict their
 432 shell account only to Git pushing/fetching by using the
 433 <code class="g">git-shell</code> login shell.</p>
 434
 435 <p>You can also exchange patches by mail. Git has very good support
 436 for patches incoming by mail. You can apply them by feeding mailboxes
 437 with patch mails to <code class="g">cg patch -m</code>. If you
 438 want to <em>send</em> patches (or a third-party changes to an upstream
 439 repository with no commit access in general), it is best to use
 440 the <strong>StGIT</strong> tool - see
 441 the <a href="stgit.html">StGIT Crash Course</a>).</p>
 442
 443 <p>If you have any question or problem which is not obvious from
 444 the documentation, please contact us at the <strong>Git mailing list</strong>
 445 at <a href="mailto:git@vger.kernel.org">git@vger.kernel.org</a>.
 446 We hope you enjoy using Git and Cogito!</p>
 447
 448
 449
 450 <hr />
 451
 452 <div class="footer">
 453         <span class="menu">
 454                 This page is maintained by Petr Baudis. Please email me
 455                 at <a href="mailto:pasky@suse.cz">pasky@suse.cz</a>
 456                 with patches, suggestions and comments.
 457         </span>
 458 </div>
 459
 460 </body>
 461 </html>