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