1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
\r
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
\r
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
\r
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
\r
6 <meta name="generator" content="AsciiDoc 7.0.2" />
\r
7 <style type="text/css">
\r
9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
\r
11 border: 1px solid red;
\r
16 margin: 1em 5% 1em 5%;
\r
20 a:visited { color: fuchsia; }
\r
34 h1, h2, h3, h4, h5, h6 {
\r
36 font-family: sans-serif;
\r
38 margin-bottom: 0.5em;
\r
43 border-bottom: 2px solid silver;
\r
46 border-bottom: 2px solid silver;
\r
56 border: 1px solid silver;
\r
61 margin-bottom: 0.5em;
\r
71 font-family: sans-serif;
\r
78 font-family: sans-serif;
\r
82 font-family: sans-serif;
\r
84 border-top: 2px solid silver;
\r
90 padding-bottom: 0.5em;
\r
94 padding-bottom: 0.5em;
\r
98 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
\r
99 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
\r
100 div.admonitionblock {
\r
103 margin-bottom: 1.5em;
\r
105 div.admonitionblock {
\r
107 margin-bottom: 2.5em;
\r
110 div.content { /* Block element content. */
\r
114 /* Block element titles. */
\r
115 div.title, caption.title {
\r
116 font-family: sans-serif;
\r
120 margin-bottom: 0.5em;
\r
126 td div.title:first-child {
\r
129 div.content div.title:first-child {
\r
132 div.content + div.title {
\r
136 div.sidebarblock > div.content {
\r
137 background: #ffffee;
\r
138 border: 1px solid silver;
\r
142 div.listingblock > div.content {
\r
143 border: 1px solid silver;
\r
144 background: #f4f4f4;
\r
148 div.quoteblock > div.content {
\r
149 padding-left: 2.0em;
\r
151 div.quoteblock .attribution {
\r
155 div.admonitionblock .icon {
\r
156 vertical-align: top;
\r
159 text-decoration: underline;
\r
161 padding-right: 0.5em;
\r
163 div.admonitionblock td.content {
\r
164 padding-left: 0.5em;
\r
165 border-left: 2px solid silver;
\r
168 div.exampleblock > div.content {
\r
169 border-left: 2px solid silver;
\r
173 div.verseblock div.content {
\r
177 div.imageblock div.content { padding-left: 0; }
\r
178 div.imageblock img { border: 1px solid silver; }
\r
179 span.image img { border-style: none; }
\r
183 margin-bottom: 0.8em;
\r
188 font-style: italic;
\r
190 dd > *:first-child {
\r
195 list-style-position: outside;
\r
198 list-style-type: lower-alpha;
\r
201 div.tableblock > table {
\r
202 border-color: #527bbd;
\r
206 font-family: sans-serif;
\r
215 margin-bottom: 0.8em;
\r
218 vertical-align: top;
\r
219 font-style: italic;
\r
220 padding-right: 0.8em;
\r
223 vertical-align: top;
\r
227 div#footer-badges { display: none; }
\r
229 /* Workarounds for IE6's broken and incomplete CSS2. */
\r
231 div.sidebar-content {
\r
232 background: #ffffee;
\r
233 border: 1px solid silver;
\r
236 div.sidebar-title, div.image-title {
\r
237 font-family: sans-serif;
\r
240 margin-bottom: 0.5em;
\r
243 div.listingblock div.content {
\r
244 border: 1px solid silver;
\r
245 background: #f4f4f4;
\r
249 div.quoteblock-content {
\r
250 padding-left: 2.0em;
\r
253 div.exampleblock-content {
\r
254 border-left: 2px solid silver;
\r
255 padding-left: 0.5em;
\r
258 <title>A tutorial introduction to git: part two</title>
\r
262 <h1>A tutorial introduction to git: part two</h1>
\r
264 <div id="preamble">
\r
265 <div class="sectionbody">
\r
266 <p>You should work through <a href="tutorial.html">A tutorial introduction to
\r
267 git</a> before reading this tutorial.</p>
\r
268 <p>The goal of this tutorial is to introduce two fundamental pieces of
\r
269 git's architecture—the object database and the index file—and to
\r
270 provide the reader with everything necessary to understand the rest
\r
271 of the git documentation.</p>
\r
274 <h2>The git object database</h2>
\r
275 <div class="sectionbody">
\r
276 <p>Let's start a new project and create a small amount of history:</p>
\r
277 <div class="listingblock">
\r
278 <div class="content">
\r
279 <pre><tt>$ mkdir test-project
\r
282 defaulting to local storage area
\r
283 $ echo 'hello world' > file.txt
\r
285 $ git commit -a -m "initial commit"
\r
286 Committing initial tree 92b8b694ffb1675e5975148e1121810081dbdffe
\r
287 $ echo 'hello world!' >file.txt
\r
288 $ git commit -a -m "add emphasis"</tt></pre>
\r
290 <p>What are the 40 digits of hex that git responded to the first commit
\r
292 <p>We saw in part one of the tutorial that commits have names like this.
\r
293 It turns out that every object in the git history is stored under
\r
294 such a 40-digit hex name. That name is the SHA1 hash of the object's
\r
295 contents; among other things, this ensures that git will never store
\r
296 the same data twice (since identical data is given an identical SHA1
\r
297 name), and that the contents of a git object will never change (since
\r
298 that would change the object's name as well).</p>
\r
299 <p>We can ask git about this particular object with the cat-file
\r
300 command—just cut-and-paste from the reply to the initial commit, to
\r
301 save yourself typing all 40 hex digits:</p>
\r
302 <div class="listingblock">
\r
303 <div class="content">
\r
304 <pre><tt>$ git cat-file -t 92b8b694ffb1675e5975148e1121810081dbdffe
\r
307 <p>A tree can refer to one or more "blob" objects, each corresponding to
\r
308 a file. In addition, a tree can also refer to other tree objects,
\r
309 thus creating a directory heirarchy. You can examine the contents of
\r
310 any tree using ls-tree (remember that a long enough initial portion
\r
311 of the SHA1 will also work):</p>
\r
312 <div class="listingblock">
\r
313 <div class="content">
\r
314 <pre><tt>$ git ls-tree 92b8b694
\r
315 100644 blob 3b18e512dba79e4c8300dd08aeb37f8e728b8dad file.txt</tt></pre>
\r
317 <p>Thus we see that this tree has one file in it. The SHA1 hash is a
\r
318 reference to that file's data:</p>
\r
319 <div class="listingblock">
\r
320 <div class="content">
\r
321 <pre><tt>$ git cat-file -t 3b18e512
\r
324 <p>A "blob" is just file data, which we can also examine with cat-file:</p>
\r
325 <div class="listingblock">
\r
326 <div class="content">
\r
327 <pre><tt>$ git cat-file blob 3b18e512
\r
328 hello world</tt></pre>
\r
330 <p>Note that this is the old file data; so the object that git named in
\r
331 its response to the initial tree was a tree with a snapshot of the
\r
332 directory state that was recorded by the first commit.</p>
\r
333 <p>All of these objects are stored under their SHA1 names inside the git
\r
335 <div class="listingblock">
\r
336 <div class="content">
\r
337 <pre><tt>$ find .git/objects/
\r
342 .git/objects/3b/18e512dba79e4c8300dd08aeb37f8e728b8dad
\r
344 .git/objects/92/b8b694ffb1675e5975148e1121810081dbdffe
\r
346 .git/objects/54/196cc2703dc165cbd373a65a4dcf22d50ae7f7
\r
348 .git/objects/a0/423896973644771497bdc03eb99d5281615b51
\r
350 .git/objects/d0/492b368b66bdabf2ac1fd8c92b39d3db916e59
\r
352 .git/objects/c4/d59f390b9cfd4318117afde11d601c1085f241</tt></pre>
\r
354 <p>and the contents of these files is just the compressed data plus a
\r
355 header identifying their length and their type. The type is either a
\r
356 blob, a tree, a commit, or a tag. We've seen a blob and a tree now,
\r
357 so next we should look at a commit.</p>
\r
358 <p>The simplest commit to find is the HEAD commit, which we can find
\r
359 from .git/HEAD:</p>
\r
360 <div class="listingblock">
\r
361 <div class="content">
\r
362 <pre><tt>$ cat .git/HEAD
\r
363 ref: refs/heads/master</tt></pre>
\r
365 <p>As you can see, this tells us which branch we're currently on, and it
\r
366 tells us this by naming a file under the .git directory, which itself
\r
367 contains a SHA1 name referring to a commit object, which we can
\r
368 examine with cat-file:</p>
\r
369 <div class="listingblock">
\r
370 <div class="content">
\r
371 <pre><tt>$ cat .git/refs/heads/master
\r
372 c4d59f390b9cfd4318117afde11d601c1085f241
\r
373 $ git cat-file -t c4d59f39
\r
375 $ git cat-file commit c4d59f39
\r
376 tree d0492b368b66bdabf2ac1fd8c92b39d3db916e59
\r
377 parent 54196cc2703dc165cbd373a65a4dcf22d50ae7f7
\r
378 author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500
\r
379 committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500
\r
381 add emphasis</tt></pre>
\r
383 <p>The "tree" object here refers to the new state of the tree:</p>
\r
384 <div class="listingblock">
\r
385 <div class="content">
\r
386 <pre><tt>$ git ls-tree d0492b36
\r
387 100644 blob a0423896973644771497bdc03eb99d5281615b51 file.txt
\r
388 $ git cat-file commit a0423896
\r
389 hello world!</tt></pre>
\r
391 <p>and the "parent" object refers to the previous commit:</p>
\r
392 <div class="listingblock">
\r
393 <div class="content">
\r
394 <pre><tt>$ git-cat-file commit 54196cc2
\r
395 tree 92b8b694ffb1675e5975148e1121810081dbdffe
\r
396 author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
\r
397 committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
\r
399 initial commit</tt></pre>
\r
401 <p>The tree object is the tree we examined first, and this commit is
\r
402 unusual in that it lacks any parent.</p>
\r
403 <p>Most commits have only one parent, but it is also common for a commit
\r
404 to have multiple parents. In that case the commit represents a
\r
405 merge, with the parent references pointing to the heads of the merged
\r
407 <p>Besides blobs, trees, and commits, the only remaining type of object
\r
408 is a "tag", which we won't discuss here; refer to <a href="git-tag.html">git-tag(1)</a>
\r
410 <p>So now we know how git uses the object database to represent a
\r
411 project's history:</p>
\r
415 "commit" objects refer to "tree" objects representing the
\r
416 snapshot of a directory tree at a particular point in the
\r
417 history, and refer to "parent" commits to show how they're
\r
418 connected into the project history.
\r
423 "tree" objects represent the state of a single directory,
\r
424 associating directory names to "blob" objects containing file
\r
425 data and "tree" objects containing subdirectory information.
\r
430 "blob" objects contain file data without any other structure.
\r
435 References to commit objects at the head of each branch are
\r
436 stored in files under .git/refs/heads/.
\r
441 The name of the current branch is stored in .git/HEAD.
\r
445 <p>Note, by the way, that lots of commands take a tree as an argument.
\r
446 But as we can see above, a tree can be referred to in many different
\r
447 ways—by the SHA1 name for that tree, by the name of a commit that
\r
448 refers to the tree, by the name of a branch whose head refers to that
\r
449 tree, etc.—and most such commands can accept any of these names.</p>
\r
450 <p>In command synopses, the word "tree-ish" is sometimes used to
\r
451 designate such an argument.</p>
\r
453 <h2>The index file</h2>
\r
454 <div class="sectionbody">
\r
455 <p>The primary tool we've been using to create commits is "git commit
\r
456 -a", which creates a commit including every change you've made to
\r
457 your working tree. But what if you want to commit changes only to
\r
458 certain files? Or only certain changes to certain files?</p>
\r
459 <p>If we look at the way commits are created under the cover, we'll see
\r
460 that there are more flexible ways creating commits.</p>
\r
461 <p>Continuing with our test-project, let's modify file.txt again:</p>
\r
462 <div class="listingblock">
\r
463 <div class="content">
\r
464 <pre><tt>$ echo "hello world, again" >>file.txt</tt></pre>
\r
466 <p>but this time instead of immediately making the commit, let's take an
\r
467 intermediate step, and ask for diffs along the way to keep track of
\r
468 what's happening:</p>
\r
469 <div class="listingblock">
\r
470 <div class="content">
\r
471 <pre><tt>$ git diff
\r
476 +hello world, again
\r
477 $ git update-index file.txt
\r
478 $ git diff</tt></pre>
\r
480 <p>The last diff is empty, but no new commits have been made, and the
\r
481 head still doesn't contain the new line:</p>
\r
482 <div class="listingblock">
\r
483 <div class="content">
\r
484 <pre><tt>$ git-diff HEAD
\r
485 diff --git a/file.txt b/file.txt
\r
486 index a042389..513feba 100644
\r
491 +hello world, again</tt></pre>
\r
493 <p>So "git diff" is comparing against something other than the head.
\r
494 The thing that it's comparing against is actually the index file,
\r
495 which is stored in .git/index in a binary format, but whose contents
\r
496 we can examine with ls-files:</p>
\r
497 <div class="listingblock">
\r
498 <div class="content">
\r
499 <pre><tt>$ git ls-files --stage
\r
500 100644 513feba2e53ebbd2532419ded848ba19de88ba00 0 file.txt
\r
501 $ git cat-file -t 513feba2
\r
503 $ git cat-file blob 513feba2
\r
504 hello world, again</tt></pre>
\r
506 <p>So what our "git update-index" did was store a new blob and then put
\r
507 a reference to it in the index file. If we modify the file again,
\r
508 we'll see that the new modifications are reflected in the "git-diff"
\r
510 <div class="listingblock">
\r
511 <div class="content">
\r
512 <pre><tt>$ echo 'again?' >>file.txt
\r
514 index 513feba..ba3da7b 100644
\r
522 <p>With the right arguments, git diff can also show us the difference
\r
523 between the working directory and the last commit, or between the
\r
524 index and the last commit:</p>
\r
525 <div class="listingblock">
\r
526 <div class="content">
\r
527 <pre><tt>$ git diff HEAD
\r
528 diff --git a/file.txt b/file.txt
\r
529 index a042389..ba3da7b 100644
\r
534 +hello world, again
\r
536 $ git diff --cached
\r
537 diff --git a/file.txt b/file.txt
\r
538 index a042389..513feba 100644
\r
543 +hello world, again</tt></pre>
\r
545 <p>At any time, we can create a new commit using "git commit" (without
\r
546 the -a option), and verify that the state committed only includes the
\r
547 changes stored in the index file, not the additional change that is
\r
548 still only in our working tree:</p>
\r
549 <div class="listingblock">
\r
550 <div class="content">
\r
551 <pre><tt>$ git commit -m "repeat"
\r
553 diff --git a/file.txt b/file.txt
\r
554 index 513feba..ba3da7b 100644
\r
562 <p>So by default "git commit" uses the index to create the commit, not
\r
563 the working tree; the -a option to commit tells it to first update
\r
564 the index with all changes in the working tree.</p>
\r
565 <p>Finally, it's worth looking at the effect of "git add" on the index
\r
567 <div class="listingblock">
\r
568 <div class="content">
\r
569 <pre><tt>$ echo "goodbye, world" >closing.txt
\r
570 $ git add closing.txt</tt></pre>
\r
572 <p>The effect of the "git add" was to add one entry to the index file:</p>
\r
573 <div class="listingblock">
\r
574 <div class="content">
\r
575 <pre><tt>$ git ls-files --stage
\r
576 100644 8b9743b20d4b15be3955fc8d5cd2b09cd2336138 0 closing.txt
\r
577 100644 513feba2e53ebbd2532419ded848ba19de88ba00 0 file.txt</tt></pre>
\r
579 <p>And, as you can see with cat-file, this new entry refers to the
\r
580 current contents of the file:</p>
\r
581 <div class="listingblock">
\r
582 <div class="content">
\r
583 <pre><tt>$ git cat-file blob a6b11f7a
\r
584 goodbye, word</tt></pre>
\r
586 <p>The "status" command is a useful way to get a quick summary of the
\r
588 <div class="listingblock">
\r
589 <div class="content">
\r
590 <pre><tt>$ git status
\r
592 # Updated but not checked in:
\r
595 # new file: closing.txt
\r
598 # Changed but not updated:
\r
599 # (use git-update-index to mark for commit)
\r
601 # modified: file.txt
\r
604 <p>Since the current state of closing.txt is cached in the index file,
\r
605 it is listed as "updated but not checked in". Since file.txt has
\r
606 changes in the working directory that aren't reflected in the index,
\r
607 it is marked "changed but not updated". At this point, running "git
\r
608 commit" would create a commit that added closing.txt (with its new
\r
609 contents), but that didn't modify file.txt.</p>
\r
610 <p>Also, note that a bare "git diff" shows the changes to file.txt, but
\r
611 not the addition of closing.txt, because the version of closing.txt
\r
612 in the index file is identical to the one in the working directory.</p>
\r
613 <p>In addition to being the staging area for new commits, the index file
\r
614 is also populated from the object database when checking out a
\r
615 branch, and is used to hold the trees involved in a merge operation.
\r
616 See the <a href="core-tutorial.txt">core tutorial</a> and the relevant man
\r
617 pages for details.</p>
\r
619 <h2>What next?</h2>
\r
620 <div class="sectionbody">
\r
621 <p>At this point you should know everything necessary to read the man
\r
622 pages for any of the git commands; one good place to start would be
\r
623 with the commands mentioned in <a href="everyday.html">Everyday git</a>. You
\r
624 should be able to find any unknown jargon in the
\r
625 <a href="glossary.html">Glossary</a>.</p>
\r
626 <p>The <a href="cvs-migration.html">CVS migration</a> document explains how to
\r
627 import a CVS repository into git, and shows how to use git in a
\r
629 <p>For some interesting examples of git use, see the
\r
630 <a href="howto-index.html">howtos</a>.</p>
\r
631 <p>For git developers, the <a href="core-tutorial.html">Core tutorial</a> goes
\r
632 into detail on the lower-level git mechanisms involved in, for
\r
633 example, creating a new commit.</p>
\r
636 <div id="footer-text">
\r
637 Last updated 30-May-2006 07:20:51 UTC
\r