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