gittutorial.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   2     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
   6 <meta name="generator" content="AsciiDoc 8.2.5" />
   7 <style type="text/css">
   8 /* Debug borders */
   9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
  10 /*
  11   border: 1px solid red;
  12 */
  13 }
  14
  15 body {
  16   margin: 1em 5% 1em 5%;
  17 }
  18
  19 a {
  20   color: blue;
  21   text-decoration: underline;
  22 }
  23 a:visited {
  24   color: fuchsia;
  25 }
  26
  27 em {
  28   font-style: italic;
  29 }
  30
  31 strong {
  32   font-weight: bold;
  33 }
  34
  35 tt {
  36   color: navy;
  37 }
  38
  39 h1, h2, h3, h4, h5, h6 {
  40   color: #527bbd;
  41   font-family: sans-serif;
  42   margin-top: 1.2em;
  43   margin-bottom: 0.5em;
  44   line-height: 1.3;
  45 }
  46
  47 h1, h2, h3 {
  48   border-bottom: 2px solid silver;
  49 }
  50 h2 {
  51   padding-top: 0.5em;
  52 }
  53 h3 {
  54   float: left;
  55 }
  56 h3 + * {
  57   clear: left;
  58 }
  59
  60 div.sectionbody {
  61   font-family: serif;
  62   margin-left: 0;
  63 }
  64
  65 hr {
  66   border: 1px solid silver;
  67 }
  68
  69 p {
  70   margin-top: 0.5em;
  71   margin-bottom: 0.5em;
  72 }
  73
  74 pre {
  75   padding: 0;
  76   margin: 0;
  77 }
  78
  79 span#author {
  80   color: #527bbd;
  81   font-family: sans-serif;
  82   font-weight: bold;
  83   font-size: 1.1em;
  84 }
  85 span#email {
  86 }
  87 span#revision {
  88   font-family: sans-serif;
  89 }
  90
  91 div#footer {
  92   font-family: sans-serif;
  93   font-size: small;
  94   border-top: 2px solid silver;
  95   padding-top: 0.5em;
  96   margin-top: 4.0em;
  97 }
  98 div#footer-text {
  99   float: left;
 100   padding-bottom: 0.5em;
 101 }
 102 div#footer-badges {
 103   float: right;
 104   padding-bottom: 0.5em;
 105 }
 106
 107 div#preamble,
 108 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 109 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 110 div.admonitionblock {
 111   margin-right: 10%;
 112   margin-top: 1.5em;
 113   margin-bottom: 1.5em;
 114 }
 115 div.admonitionblock {
 116   margin-top: 2.5em;
 117   margin-bottom: 2.5em;
 118 }
 119
 120 div.content { /* Block element content. */
 121   padding: 0;
 122 }
 123
 124 /* Block element titles. */
 125 div.title, caption.title {
 126   font-family: sans-serif;
 127   font-weight: bold;
 128   text-align: left;
 129   margin-top: 1.0em;
 130   margin-bottom: 0.5em;
 131 }
 132 div.title + * {
 133   margin-top: 0;
 134 }
 135
 136 td div.title:first-child {
 137   margin-top: 0.0em;
 138 }
 139 div.content div.title:first-child {
 140   margin-top: 0.0em;
 141 }
 142 div.content + div.title {
 143   margin-top: 0.0em;
 144 }
 145
 146 div.sidebarblock > div.content {
 147   background: #ffffee;
 148   border: 1px solid silver;
 149   padding: 0.5em;
 150 }
 151
 152 div.listingblock {
 153   margin-right: 0%;
 154 }
 155 div.listingblock > div.content {
 156   border: 1px solid silver;
 157   background: #f4f4f4;
 158   padding: 0.5em;
 159 }
 160
 161 div.quoteblock > div.content {
 162   padding-left: 2.0em;
 163 }
 164
 165 div.attribution {
 166   text-align: right;
 167 }
 168 div.verseblock + div.attribution {
 169   text-align: left;
 170 }
 171
 172 div.admonitionblock .icon {
 173   vertical-align: top;
 174   font-size: 1.1em;
 175   font-weight: bold;
 176   text-decoration: underline;
 177   color: #527bbd;
 178   padding-right: 0.5em;
 179 }
 180 div.admonitionblock td.content {
 181   padding-left: 0.5em;
 182   border-left: 2px solid silver;
 183 }
 184
 185 div.exampleblock > div.content {
 186   border-left: 2px solid silver;
 187   padding: 0.5em;
 188 }
 189
 190 div.verseblock div.content {
 191   white-space: pre;
 192 }
 193
 194 div.imageblock div.content { padding-left: 0; }
 195 div.imageblock img { border: 1px solid silver; }
 196 span.image img { border-style: none; }
 197
 198 dl {
 199   margin-top: 0.8em;
 200   margin-bottom: 0.8em;
 201 }
 202 dt {
 203   margin-top: 0.5em;
 204   margin-bottom: 0;
 205   font-style: italic;
 206 }
 207 dd > *:first-child {
 208   margin-top: 0;
 209 }
 210
 211 ul, ol {
 212     list-style-position: outside;
 213 }
 214 div.olist2 ol {
 215   list-style-type: lower-alpha;
 216 }
 217
 218 div.tableblock > table {
 219   border: 3px solid #527bbd;
 220 }
 221 thead {
 222   font-family: sans-serif;
 223   font-weight: bold;
 224 }
 225 tfoot {
 226   font-weight: bold;
 227 }
 228
 229 div.hlist {
 230   margin-top: 0.8em;
 231   margin-bottom: 0.8em;
 232 }
 233 div.hlist td {
 234   padding-bottom: 5px;
 235 }
 236 td.hlist1 {
 237   vertical-align: top;
 238   font-style: italic;
 239   padding-right: 0.8em;
 240 }
 241 td.hlist2 {
 242   vertical-align: top;
 243 }
 244
 245 @media print {
 246   div#footer-badges { display: none; }
 247 }
 248
 249 div#toctitle {
 250   color: #527bbd;
 251   font-family: sans-serif;
 252   font-size: 1.1em;
 253   font-weight: bold;
 254   margin-top: 1.0em;
 255   margin-bottom: 0.1em;
 256 }
 257
 258 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 259   margin-top: 0;
 260   margin-bottom: 0;
 261 }
 262 div.toclevel2 {
 263   margin-left: 2em;
 264   font-size: 0.9em;
 265 }
 266 div.toclevel3 {
 267   margin-left: 4em;
 268   font-size: 0.9em;
 269 }
 270 div.toclevel4 {
 271   margin-left: 6em;
 272   font-size: 0.9em;
 273 }
 274 include1::./stylesheets/xhtml11-manpage.css[]
 275 /* Workarounds for IE6's broken and incomplete CSS2. */
 276
 277 div.sidebar-content {
 278   background: #ffffee;
 279   border: 1px solid silver;
 280   padding: 0.5em;
 281 }
 282 div.sidebar-title, div.image-title {
 283   font-family: sans-serif;
 284   font-weight: bold;
 285   margin-top: 0.0em;
 286   margin-bottom: 0.5em;
 287 }
 288
 289 div.listingblock div.content {
 290   border: 1px solid silver;
 291   background: #f4f4f4;
 292   padding: 0.5em;
 293 }
 294
 295 div.quoteblock-content {
 296   padding-left: 2.0em;
 297 }
 298
 299 div.exampleblock-content {
 300   border-left: 2px solid silver;
 301   padding-left: 0.5em;
 302 }
 303
 304 /* IE6 sets dynamically generated links as visited. */
 305 div#toc a:visited { color: blue; }
 306 </style>
 307 <title>gittutorial(7)</title>
 308 </head>
 309 <body>
 310 <div id="header">
 311 <h1>
 312 gittutorial(7) Manual Page
 313 </h1>
 314 <h2>NAME</h2>
 315 <div class="sectionbody">
 316 <p>gittutorial -
 317    A tutorial introduction to git (for version 1.5.1 or newer)
 318 </p>
 319 </div>
 320 </div>
 321 <h2>SYNOPSIS</h2>
 322 <div class="sectionbody">
 323 <div class="para"><p>git *</p></div>
 324 </div>
 325 <h2 id="_description">DESCRIPTION</h2>
 326 <div class="sectionbody">
 327 <div class="para"><p>This tutorial explains how to import a new project into git, make
 328 changes to it, and share changes with other developers.</p></div>
 329 <div class="para"><p>If you are instead primarily interested in using git to fetch a project,
 330 for example, to test the latest version, you may prefer to start with
 331 the first two chapters of <a href="user-manual.html">The Git User's Manual</a>.</p></div>
 332 <div class="para"><p>First, note that you can get documentation for a command such as
 333 <tt>git log --graph</tt> with:</p></div>
 334 <div class="listingblock">
 335 <div class="content">
 336 <pre><tt>$ man git-log</tt></pre>
 337 </div></div>
 338 <div class="para"><p>or:</p></div>
 339 <div class="listingblock">
 340 <div class="content">
 341 <pre><tt>$ git help log</tt></pre>
 342 </div></div>
 343 <div class="para"><p>With the latter, you can use the manual viewer of your choice; see
 344 <a href="git-help.html">git-help(1)</a> for more information.</p></div>
 345 <div class="para"><p>It is a good idea to introduce yourself to git with your name and
 346 public email address before doing any operation.  The easiest
 347 way to do so is:</p></div>
 348 <div class="listingblock">
 349 <div class="content">
 350 <pre><tt>$ git config --global user.name "Your Name Comes Here"
 351 $ git config --global user.email you@yourdomain.example.com</tt></pre>
 352 </div></div>
 353 </div>
 354 <h2 id="_importing_a_new_project">Importing a new project</h2>
 355 <div class="sectionbody">
 356 <div class="para"><p>Assume you have a tarball project.tar.gz with your initial work.  You
 357 can place it under git revision control as follows.</p></div>
 358 <div class="listingblock">
 359 <div class="content">
 360 <pre><tt>$ tar xzf project.tar.gz
 361 $ cd project
 362 $ git init</tt></pre>
 363 </div></div>
 364 <div class="para"><p>Git will reply</p></div>
 365 <div class="listingblock">
 366 <div class="content">
 367 <pre><tt>Initialized empty Git repository in .git/</tt></pre>
 368 </div></div>
 369 <div class="para"><p>You've now initialized the working directory--you may notice a new
 370 directory created, named ".git".</p></div>
 371 <div class="para"><p>Next, tell git to take a snapshot of the contents of all files under the
 372 current directory (note the <em>.</em>), with <em>git-add</em>:</p></div>
 373 <div class="listingblock">
 374 <div class="content">
 375 <pre><tt>$ git add .</tt></pre>
 376 </div></div>
 377 <div class="para"><p>This snapshot is now stored in a temporary staging area which git calls
 378 the "index".  You can permanently store the contents of the index in the
 379 repository with <em>git-commit</em>:</p></div>
 380 <div class="listingblock">
 381 <div class="content">
 382 <pre><tt>$ git commit</tt></pre>
 383 </div></div>
 384 <div class="para"><p>This will prompt you for a commit message.  You've now stored the first
 385 version of your project in git.</p></div>
 386 </div>
 387 <h2 id="_making_changes">Making changes</h2>
 388 <div class="sectionbody">
 389 <div class="para"><p>Modify some files, then add their updated contents to the index:</p></div>
 390 <div class="listingblock">
 391 <div class="content">
 392 <pre><tt>$ git add file1 file2 file3</tt></pre>
 393 </div></div>
 394 <div class="para"><p>You are now ready to commit.  You can see what is about to be committed
 395 using <em>git-diff</em> with the --cached option:</p></div>
 396 <div class="listingblock">
 397 <div class="content">
 398 <pre><tt>$ git diff --cached</tt></pre>
 399 </div></div>
 400 <div class="para"><p>(Without --cached, <em>git-diff</em> will show you any changes that
 401 you've made but not yet added to the index.)  You can also get a brief
 402 summary of the situation with <em>git-status</em>:</p></div>
 403 <div class="listingblock">
 404 <div class="content">
 405 <pre><tt>$ git status
 406 # On branch master
 407 # Changes to be committed:
 408 #   (use "git reset HEAD &lt;file&gt;..." to unstage)
 409 #
 410 #       modified:   file1
 411 #       modified:   file2
 412 #       modified:   file3
 413 #</tt></pre>
 414 </div></div>
 415 <div class="para"><p>If you need to make any further adjustments, do so now, and then add any
 416 newly modified content to the index.  Finally, commit your changes with:</p></div>
 417 <div class="listingblock">
 418 <div class="content">
 419 <pre><tt>$ git commit</tt></pre>
 420 </div></div>
 421 <div class="para"><p>This will again prompt you for a message describing the change, and then
 422 record a new version of the project.</p></div>
 423 <div class="para"><p>Alternatively, instead of running <em>git-add</em> beforehand, you can use</p></div>
 424 <div class="listingblock">
 425 <div class="content">
 426 <pre><tt>$ git commit -a</tt></pre>
 427 </div></div>
 428 <div class="para"><p>which will automatically notice any modified (but not new) files, add
 429 them to the index, and commit, all in one step.</p></div>
 430 <div class="para"><p>A note on commit messages: Though not required, it's a good idea to
 431 begin the commit message with a single short (less than 50 character)
 432 line summarizing the change, followed by a blank line and then a more
 433 thorough description.  Tools that turn commits into email, for
 434 example, use the first line on the Subject: line and the rest of the
 435 commit in the body.</p></div>
 436 </div>
 437 <h2 id="_git_tracks_content_not_files">Git tracks content not files</h2>
 438 <div class="sectionbody">
 439 <div class="para"><p>Many revision control systems provide an <tt>add</tt> command that tells the
 440 system to start tracking changes to a new file.  Git's <tt>add</tt> command
 441 does something simpler and more powerful: <em>git-add</em> is used both for new
 442 and newly modified files, and in both cases it takes a snapshot of the
 443 given files and stages that content in the index, ready for inclusion in
 444 the next commit.</p></div>
 445 </div>
 446 <h2 id="_viewing_project_history">Viewing project history</h2>
 447 <div class="sectionbody">
 448 <div class="para"><p>At any point you can view the history of your changes using</p></div>
 449 <div class="listingblock">
 450 <div class="content">
 451 <pre><tt>$ git log</tt></pre>
 452 </div></div>
 453 <div class="para"><p>If you also want to see complete diffs at each step, use</p></div>
 454 <div class="listingblock">
 455 <div class="content">
 456 <pre><tt>$ git log -p</tt></pre>
 457 </div></div>
 458 <div class="para"><p>Often the overview of the change is useful to get a feel of
 459 each step</p></div>
 460 <div class="listingblock">
 461 <div class="content">
 462 <pre><tt>$ git log --stat --summary</tt></pre>
 463 </div></div>
 464 </div>
 465 <h2 id="_managing_branches">Managing branches</h2>
 466 <div class="sectionbody">
 467 <div class="para"><p>A single git repository can maintain multiple branches of
 468 development.  To create a new branch named "experimental", use</p></div>
 469 <div class="listingblock">
 470 <div class="content">
 471 <pre><tt>$ git branch experimental</tt></pre>
 472 </div></div>
 473 <div class="para"><p>If you now run</p></div>
 474 <div class="listingblock">
 475 <div class="content">
 476 <pre><tt>$ git branch</tt></pre>
 477 </div></div>
 478 <div class="para"><p>you'll get a list of all existing branches:</p></div>
 479 <div class="listingblock">
 480 <div class="content">
 481 <pre><tt>  experimental
 482 * master</tt></pre>
 483 </div></div>
 484 <div class="para"><p>The "experimental" branch is the one you just created, and the
 485 "master" branch is a default branch that was created for you
 486 automatically.  The asterisk marks the branch you are currently on;
 487 type</p></div>
 488 <div class="listingblock">
 489 <div class="content">
 490 <pre><tt>$ git checkout experimental</tt></pre>
 491 </div></div>
 492 <div class="para"><p>to switch to the experimental branch.  Now edit a file, commit the
 493 change, and switch back to the master branch:</p></div>
 494 <div class="listingblock">
 495 <div class="content">
 496 <pre><tt>(edit file)
 497 $ git commit -a
 498 $ git checkout master</tt></pre>
 499 </div></div>
 500 <div class="para"><p>Check that the change you made is no longer visible, since it was
 501 made on the experimental branch and you're back on the master branch.</p></div>
 502 <div class="para"><p>You can make a different change on the master branch:</p></div>
 503 <div class="listingblock">
 504 <div class="content">
 505 <pre><tt>(edit file)
 506 $ git commit -a</tt></pre>
 507 </div></div>
 508 <div class="para"><p>at this point the two branches have diverged, with different changes
 509 made in each.  To merge the changes made in experimental into master, run</p></div>
 510 <div class="listingblock">
 511 <div class="content">
 512 <pre><tt>$ git merge experimental</tt></pre>
 513 </div></div>
 514 <div class="para"><p>If the changes don't conflict, you're done.  If there are conflicts,
 515 markers will be left in the problematic files showing the conflict;</p></div>
 516 <div class="listingblock">
 517 <div class="content">
 518 <pre><tt>$ git diff</tt></pre>
 519 </div></div>
 520 <div class="para"><p>will show this.  Once you've edited the files to resolve the
 521 conflicts,</p></div>
 522 <div class="listingblock">
 523 <div class="content">
 524 <pre><tt>$ git commit -a</tt></pre>
 525 </div></div>
 526 <div class="para"><p>will commit the result of the merge. Finally,</p></div>
 527 <div class="listingblock">
 528 <div class="content">
 529 <pre><tt>$ gitk</tt></pre>
 530 </div></div>
 531 <div class="para"><p>will show a nice graphical representation of the resulting history.</p></div>
 532 <div class="para"><p>At this point you could delete the experimental branch with</p></div>
 533 <div class="listingblock">
 534 <div class="content">
 535 <pre><tt>$ git branch -d experimental</tt></pre>
 536 </div></div>
 537 <div class="para"><p>This command ensures that the changes in the experimental branch are
 538 already in the current branch.</p></div>
 539 <div class="para"><p>If you develop on a branch crazy-idea, then regret it, you can always
 540 delete the branch with</p></div>
 541 <div class="listingblock">
 542 <div class="content">
 543 <pre><tt>$ git branch -D crazy-idea</tt></pre>
 544 </div></div>
 545 <div class="para"><p>Branches are cheap and easy, so this is a good way to try something
 546 out.</p></div>
 547 </div>
 548 <h2 id="_using_git_for_collaboration">Using git for collaboration</h2>
 549 <div class="sectionbody">
 550 <div class="para"><p>Suppose that Alice has started a new project with a git repository in
 551 /home/alice/project, and that Bob, who has a home directory on the
 552 same machine, wants to contribute.</p></div>
 553 <div class="para"><p>Bob begins with:</p></div>
 554 <div class="listingblock">
 555 <div class="content">
 556 <pre><tt>bob$ git clone /home/alice/project myrepo</tt></pre>
 557 </div></div>
 558 <div class="para"><p>This creates a new directory "myrepo" containing a clone of Alice's
 559 repository.  The clone is on an equal footing with the original
 560 project, possessing its own copy of the original project's history.</p></div>
 561 <div class="para"><p>Bob then makes some changes and commits them:</p></div>
 562 <div class="listingblock">
 563 <div class="content">
 564 <pre><tt>(edit files)
 565 bob$ git commit -a
 566 (repeat as necessary)</tt></pre>
 567 </div></div>
 568 <div class="para"><p>When he's ready, he tells Alice to pull changes from the repository
 569 at /home/bob/myrepo.  She does this with:</p></div>
 570 <div class="listingblock">
 571 <div class="content">
 572 <pre><tt>alice$ cd /home/alice/project
 573 alice$ git pull /home/bob/myrepo master</tt></pre>
 574 </div></div>
 575 <div class="para"><p>This merges the changes from Bob's "master" branch into Alice's
 576 current branch.  If Alice has made her own changes in the meantime,
 577 then she may need to manually fix any conflicts.</p></div>
 578 <div class="para"><p>The "pull" command thus performs two operations: it fetches changes
 579 from a remote branch, then merges them into the current branch.</p></div>
 580 <div class="para"><p>Note that in general, Alice would want her local changes committed before
 581 initiating this "pull".  If Bob's work conflicts with what Alice did since
 582 their histories forked, Alice will use her working tree and the index to
 583 resolve conflicts, and existing local changes will interfere with the
 584 conflict resolution process (git will still perform the fetch but will
 585 refuse to merge --- Alice will have to get rid of her local changes in
 586 some way and pull again when this happens).</p></div>
 587 <div class="para"><p>Alice can peek at what Bob did without merging first, using the "fetch"
 588 command; this allows Alice to inspect what Bob did, using a special
 589 symbol "FETCH_HEAD", in order to determine if he has anything worth
 590 pulling, like this:</p></div>
 591 <div class="listingblock">
 592 <div class="content">
 593 <pre><tt>alice$ git fetch /home/bob/myrepo master
 594 alice$ git log -p HEAD..FETCH_HEAD</tt></pre>
 595 </div></div>
 596 <div class="para"><p>This operation is safe even if Alice has uncommitted local changes.
 597 The range notation "HEAD..FETCH_HEAD" means "show everything that is reachable
 598 from the FETCH_HEAD but exclude anything that is reachable from HEAD".
 599 Alice already knows everything that leads to her current state (HEAD),
 600 and reviews what Bob has in his state (FETCH_HEAD) that she has not
 601 seen with this command.</p></div>
 602 <div class="para"><p>If Alice wants to visualize what Bob did since their histories forked
 603 she can issue the following command:</p></div>
 604 <div class="listingblock">
 605 <div class="content">
 606 <pre><tt>$ gitk HEAD..FETCH_HEAD</tt></pre>
 607 </div></div>
 608 <div class="para"><p>This uses the same two-dot range notation we saw earlier with <em>git log</em>.</p></div>
 609 <div class="para"><p>Alice may want to view what both of them did since they forked.
 610 She can use three-dot form instead of the two-dot form:</p></div>
 611 <div class="listingblock">
 612 <div class="content">
 613 <pre><tt>$ gitk HEAD...FETCH_HEAD</tt></pre>
 614 </div></div>
 615 <div class="para"><p>This means "show everything that is reachable from either one, but
 616 exclude anything that is reachable from both of them".</p></div>
 617 <div class="para"><p>Please note that these range notation can be used with both gitk
 618 and "git log".</p></div>
 619 <div class="para"><p>After inspecting what Bob did, if there is nothing urgent, Alice may
 620 decide to continue working without pulling from Bob.  If Bob's history
 621 does have something Alice would immediately need, Alice may choose to
 622 stash her work-in-progress first, do a "pull", and then finally unstash
 623 her work-in-progress on top of the resulting history.</p></div>
 624 <div class="para"><p>When you are working in a small closely knit group, it is not
 625 unusual to interact with the same repository over and over
 626 again.  By defining <em>remote</em> repository shorthand, you can make
 627 it easier:</p></div>
 628 <div class="listingblock">
 629 <div class="content">
 630 <pre><tt>alice$ git remote add bob /home/bob/myrepo</tt></pre>
 631 </div></div>
 632 <div class="para"><p>With this, Alice can perform the first part of the "pull" operation
 633 alone using the <em>git-fetch</em> command without merging them with her own
 634 branch, using:</p></div>
 635 <div class="listingblock">
 636 <div class="content">
 637 <pre><tt>alice$ git fetch bob</tt></pre>
 638 </div></div>
 639 <div class="para"><p>Unlike the longhand form, when Alice fetches from Bob using a
 640 remote repository shorthand set up with <em>git-remote</em>, what was
 641 fetched is stored in a remote tracking branch, in this case
 642 <tt>bob/master</tt>.  So after this:</p></div>
 643 <div class="listingblock">
 644 <div class="content">
 645 <pre><tt>alice$ git log -p master..bob/master</tt></pre>
 646 </div></div>
 647 <div class="para"><p>shows a list of all the changes that Bob made since he branched from
 648 Alice's master branch.</p></div>
 649 <div class="para"><p>After examining those changes, Alice
 650 could merge the changes into her master branch:</p></div>
 651 <div class="listingblock">
 652 <div class="content">
 653 <pre><tt>alice$ git merge bob/master</tt></pre>
 654 </div></div>
 655 <div class="para"><p>This <tt>merge</tt> can also be done by <em>pulling from her own remote
 656 tracking branch</em>, like this:</p></div>
 657 <div class="listingblock">
 658 <div class="content">
 659 <pre><tt>alice$ git pull . remotes/bob/master</tt></pre>
 660 </div></div>
 661 <div class="para"><p>Note that git pull always merges into the current branch,
 662 regardless of what else is given on the command line.</p></div>
 663 <div class="para"><p>Later, Bob can update his repo with Alice's latest changes using</p></div>
 664 <div class="listingblock">
 665 <div class="content">
 666 <pre><tt>bob$ git pull</tt></pre>
 667 </div></div>
 668 <div class="para"><p>Note that he doesn't need to give the path to Alice's repository;
 669 when Bob cloned Alice's repository, git stored the location of her
 670 repository in the repository configuration, and that location is
 671 used for pulls:</p></div>
 672 <div class="listingblock">
 673 <div class="content">
 674 <pre><tt>bob$ git config --get remote.origin.url
 675 /home/alice/project</tt></pre>
 676 </div></div>
 677 <div class="para"><p>(The complete configuration created by <em>git-clone</em> is visible using
 678 <tt>git config -l</tt>, and the <a href="git-config.html">git-config(1)</a> man page
 679 explains the meaning of each option.)</p></div>
 680 <div class="para"><p>Git also keeps a pristine copy of Alice's master branch under the
 681 name "origin/master":</p></div>
 682 <div class="listingblock">
 683 <div class="content">
 684 <pre><tt>bob$ git branch -r
 685   origin/master</tt></pre>
 686 </div></div>
 687 <div class="para"><p>If Bob later decides to work from a different host, he can still
 688 perform clones and pulls using the ssh protocol:</p></div>
 689 <div class="listingblock">
 690 <div class="content">
 691 <pre><tt>bob$ git clone alice.org:/home/alice/project myrepo</tt></pre>
 692 </div></div>
 693 <div class="para"><p>Alternatively, git has a native protocol, or can use rsync or http;
 694 see <a href="git-pull.html">git-pull(1)</a> for details.</p></div>
 695 <div class="para"><p>Git can also be used in a CVS-like mode, with a central repository
 696 that various users push changes to; see <a href="git-push.html">git-push(1)</a> and
 697 <a href="gitcvs-migration.html">gitcvs-migration(7)</a>.</p></div>
 698 </div>
 699 <h2 id="_exploring_history">Exploring history</h2>
 700 <div class="sectionbody">
 701 <div class="para"><p>Git history is represented as a series of interrelated commits.  We
 702 have already seen that the <em>git-log</em> command can list those commits.
 703 Note that first line of each git log entry also gives a name for the
 704 commit:</p></div>
 705 <div class="listingblock">
 706 <div class="content">
 707 <pre><tt>$ git log
 708 commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
 709 Author: Junio C Hamano &lt;junkio@cox.net&gt;
 710 Date:   Tue May 16 17:18:22 2006 -0700
 711
 712     merge-base: Clarify the comments on post processing.</tt></pre>
 713 </div></div>
 714 <div class="para"><p>We can give this name to <em>git-show</em> to see the details about this
 715 commit.</p></div>
 716 <div class="listingblock">
 717 <div class="content">
 718 <pre><tt>$ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7</tt></pre>
 719 </div></div>
 720 <div class="para"><p>But there are other ways to refer to commits.  You can use any initial
 721 part of the name that is long enough to uniquely identify the commit:</p></div>
 722 <div class="listingblock">
 723 <div class="content">
 724 <pre><tt>$ git show c82a22c39c   # the first few characters of the name are
 725                         # usually enough
 726 $ git show HEAD         # the tip of the current branch
 727 $ git show experimental # the tip of the "experimental" branch</tt></pre>
 728 </div></div>
 729 <div class="para"><p>Every commit usually has one "parent" commit
 730 which points to the previous state of the project:</p></div>
 731 <div class="listingblock">
 732 <div class="content">
 733 <pre><tt>$ git show HEAD^  # to see the parent of HEAD
 734 $ git show HEAD^^ # to see the grandparent of HEAD
 735 $ git show HEAD~4 # to see the great-great grandparent of HEAD</tt></pre>
 736 </div></div>
 737 <div class="para"><p>Note that merge commits may have more than one parent:</p></div>
 738 <div class="listingblock">
 739 <div class="content">
 740 <pre><tt>$ git show HEAD^1 # show the first parent of HEAD (same as HEAD^)
 741 $ git show HEAD^2 # show the second parent of HEAD</tt></pre>
 742 </div></div>
 743 <div class="para"><p>You can also give commits names of your own; after running</p></div>
 744 <div class="listingblock">
 745 <div class="content">
 746 <pre><tt>$ git tag v2.5 1b2e1d63ff</tt></pre>
 747 </div></div>
 748 <div class="para"><p>you can refer to 1b2e1d63ff by the name "v2.5".  If you intend to
 749 share this name with other people (for example, to identify a release
 750 version), you should create a "tag" object, and perhaps sign it; see
 751 <a href="git-tag.html">git-tag(1)</a> for details.</p></div>
 752 <div class="para"><p>Any git command that needs to know a commit can take any of these
 753 names.  For example:</p></div>
 754 <div class="listingblock">
 755 <div class="content">
 756 <pre><tt>$ git diff v2.5 HEAD     # compare the current HEAD to v2.5
 757 $ git branch stable v2.5 # start a new branch named "stable" based
 758                          # at v2.5
 759 $ git reset --hard HEAD^ # reset your current branch and working
 760                          # directory to its state at HEAD^</tt></pre>
 761 </div></div>
 762 <div class="para"><p>Be careful with that last command: in addition to losing any changes
 763 in the working directory, it will also remove all later commits from
 764 this branch.  If this branch is the only branch containing those
 765 commits, they will be lost.  Also, don't use <em>git-reset</em> on a
 766 publicly-visible branch that other developers pull from, as it will
 767 force needless merges on other developers to clean up the history.
 768 If you need to undo changes that you have pushed, use <em>git-revert</em>
 769 instead.</p></div>
 770 <div class="para"><p>The <em>git-grep</em> command can search for strings in any version of your
 771 project, so</p></div>
 772 <div class="listingblock">
 773 <div class="content">
 774 <pre><tt>$ git grep "hello" v2.5</tt></pre>
 775 </div></div>
 776 <div class="para"><p>searches for all occurrences of "hello" in v2.5.</p></div>
 777 <div class="para"><p>If you leave out the commit name, <em>git-grep</em> will search any of the
 778 files it manages in your current directory.  So</p></div>
 779 <div class="listingblock">
 780 <div class="content">
 781 <pre><tt>$ git grep "hello"</tt></pre>
 782 </div></div>
 783 <div class="para"><p>is a quick way to search just the files that are tracked by git.</p></div>
 784 <div class="para"><p>Many git commands also take sets of commits, which can be specified
 785 in a number of ways.  Here are some examples with <em>git-log</em>:</p></div>
 786 <div class="listingblock">
 787 <div class="content">
 788 <pre><tt>$ git log v2.5..v2.6            # commits between v2.5 and v2.6
 789 $ git log v2.5..                # commits since v2.5
 790 $ git log --since="2 weeks ago" # commits from the last 2 weeks
 791 $ git log v2.5.. Makefile       # commits since v2.5 which modify
 792                                 # Makefile</tt></pre>
 793 </div></div>
 794 <div class="para"><p>You can also give <em>git-log</em> a "range" of commits where the first is not
 795 necessarily an ancestor of the second; for example, if the tips of
 796 the branches "stable" and "master" diverged from a common
 797 commit some time ago, then</p></div>
 798 <div class="listingblock">
 799 <div class="content">
 800 <pre><tt>$ git log stable..master</tt></pre>
 801 </div></div>
 802 <div class="para"><p>will list commits made in the master branch but not in the
 803 stable branch, while</p></div>
 804 <div class="listingblock">
 805 <div class="content">
 806 <pre><tt>$ git log master..stable</tt></pre>
 807 </div></div>
 808 <div class="para"><p>will show the list of commits made on the stable branch but not
 809 the master branch.</p></div>
 810 <div class="para"><p>The <em>git-log</em> command has a weakness: it must present commits in a
 811 list.  When the history has lines of development that diverged and
 812 then merged back together, the order in which <em>git-log</em> presents
 813 those commits is meaningless.</p></div>
 814 <div class="para"><p>Most projects with multiple contributors (such as the Linux kernel,
 815 or git itself) have frequent merges, and <em>gitk</em> does a better job of
 816 visualizing their history.  For example,</p></div>
 817 <div class="listingblock">
 818 <div class="content">
 819 <pre><tt>$ gitk --since="2 weeks ago" drivers/</tt></pre>
 820 </div></div>
 821 <div class="para"><p>allows you to browse any commits from the last 2 weeks of commits
 822 that modified files under the "drivers" directory.  (Note: you can
 823 adjust gitk's fonts by holding down the control key while pressing
 824 "-" or "+".)</p></div>
 825 <div class="para"><p>Finally, most commands that take filenames will optionally allow you
 826 to precede any filename by a commit, to specify a particular version
 827 of the file:</p></div>
 828 <div class="listingblock">
 829 <div class="content">
 830 <pre><tt>$ git diff v2.5:Makefile HEAD:Makefile.in</tt></pre>
 831 </div></div>
 832 <div class="para"><p>You can also use <em>git-show</em> to see any such file:</p></div>
 833 <div class="listingblock">
 834 <div class="content">
 835 <pre><tt>$ git show v2.5:Makefile</tt></pre>
 836 </div></div>
 837 </div>
 838 <h2 id="_next_steps">Next Steps</h2>
 839 <div class="sectionbody">
 840 <div class="para"><p>This tutorial should be enough to perform basic distributed revision
 841 control for your projects.  However, to fully understand the depth
 842 and power of git you need to understand two simple ideas on which it
 843 is based:</p></div>
 844 <div class="ilist"><ul>
 845 <li>
 846 <p>
 847 The object database is the rather elegant system used to
 848     store the history of your project--files, directories, and
 849     commits.
 850 </p>
 851 </li>
 852 <li>
 853 <p>
 854 The index file is a cache of the state of a directory tree,
 855     used to create commits, check out working directories, and
 856     hold the various trees involved in a merge.
 857 </p>
 858 </li>
 859 </ul></div>
 860 <div class="para"><p>Part two of this tutorial explains the object
 861 database, the index file, and a few other odds and ends that you'll
 862 need to make the most of git. You can find it at <a href="gittutorial-2.html">gittutorial-2(7)</a>.</p></div>
 863 <div class="para"><p>If you don't want to continue with that right away, a few other
 864 digressions that may be interesting at this point are:</p></div>
 865 <div class="ilist"><ul>
 866 <li>
 867 <p>
 868 <a href="git-format-patch.html">git-format-patch(1)</a>, <a href="git-am.html">git-am(1)</a>: These convert
 869     series of git commits into emailed patches, and vice versa,
 870     useful for projects such as the Linux kernel which rely heavily
 871     on emailed patches.
 872 </p>
 873 </li>
 874 <li>
 875 <p>
 876 <a href="git-bisect.html">git-bisect(1)</a>: When there is a regression in your
 877     project, one way to track down the bug is by searching through
 878     the history to find the exact commit that's to blame.  Git bisect
 879     can help you perform a binary search for that commit.  It is
 880     smart enough to perform a close-to-optimal search even in the
 881     case of complex non-linear history with lots of merged branches.
 882 </p>
 883 </li>
 884 <li>
 885 <p>
 886 <a href="gitworkflows.html">gitworkflows(7)</a>: Gives an overview of recommended
 887     workflows.
 888 </p>
 889 </li>
 890 <li>
 891 <p>
 892 <a href="everyday.html">Everyday GIT with 20 Commands Or So</a>
 893 </p>
 894 </li>
 895 <li>
 896 <p>
 897 <a href="gitcvs-migration.html">gitcvs-migration(7)</a>: Git for CVS users.
 898 </p>
 899 </li>
 900 </ul></div>
 901 </div>
 902 <h2 id="_see_also">SEE ALSO</h2>
 903 <div class="sectionbody">
 904 <div class="para"><p><a href="gittutorial-2.html">gittutorial-2(7)</a>,
 905 <a href="gitcvs-migration.html">gitcvs-migration(7)</a>,
 906 <a href="gitcore-tutorial.html">gitcore-tutorial(7)</a>,
 907 <a href="gitglossary.html">gitglossary(7)</a>,
 908 <a href="git-help.html">git-help(1)</a>,
 909 <a href="gitworkflows.html">gitworkflows(7)</a>,
 910 <a href="everyday.html">Everyday git</a>,
 911 <a href="user-manual.html">The Git User's Manual</a></p></div>
 912 </div>
 913 <h2 id="_git">GIT</h2>
 914 <div class="sectionbody">
 915 <div class="para"><p>Part of the <a href="git.html">git(1)</a> suite.</p></div>
 916 </div>
 917 <div id="footer">
 918 <div id="footer-text">
 919 Last updated 2009-07-01 02:31:09 UTC
 920 </div>
 921 </div>
 922 </body>
 923 </html>