--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
+ "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
+<head>\r
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />\r
+<meta name="generator" content="AsciiDoc 7.0.2" />\r
+<style type="text/css">\r
+/* Debug borders */\r
+p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {\r
+/*\r
+ border: 1px solid red;\r
+*/\r
+}\r
+\r
+body {\r
+ margin: 1em 5% 1em 5%;\r
+}\r
+\r
+a { color: blue; }\r
+a:visited { color: fuchsia; }\r
+\r
+em {\r
+ font-style: italic;\r
+}\r
+\r
+strong {\r
+ font-weight: bold;\r
+}\r
+\r
+tt {\r
+ color: navy;\r
+}\r
+\r
+h1, h2, h3, h4, h5, h6 {\r
+ color: #527bbd;\r
+ font-family: sans-serif;\r
+ margin-top: 1.2em;\r
+ margin-bottom: 0.5em;\r
+ line-height: 1.3;\r
+}\r
+\r
+h1 {\r
+ border-bottom: 2px solid silver;\r
+}\r
+h2 {\r
+ border-bottom: 2px solid silver;\r
+ padding-top: 0.5em;\r
+}\r
+\r
+div.sectionbody {\r
+ font-family: serif;\r
+ margin-left: 0;\r
+}\r
+\r
+hr {\r
+ border: 1px solid silver;\r
+}\r
+\r
+p {\r
+ margin-top: 0.5em;\r
+ margin-bottom: 0.5em;\r
+}\r
+\r
+pre {\r
+ padding: 0;\r
+ margin: 0;\r
+}\r
+\r
+span#author {\r
+ color: #527bbd;\r
+ font-family: sans-serif;\r
+ font-weight: bold;\r
+ font-size: 1.2em;\r
+}\r
+span#email {\r
+}\r
+span#revision {\r
+ font-family: sans-serif;\r
+}\r
+\r
+div#footer {\r
+ font-family: sans-serif;\r
+ font-size: small;\r
+ border-top: 2px solid silver;\r
+ padding-top: 0.5em;\r
+ margin-top: 4.0em;\r
+}\r
+div#footer-text {\r
+ float: left;\r
+ padding-bottom: 0.5em;\r
+}\r
+div#footer-badges {\r
+ float: right;\r
+ padding-bottom: 0.5em;\r
+}\r
+\r
+div#preamble,\r
+div.tableblock, div.imageblock, div.exampleblock, div.verseblock,\r
+div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,\r
+div.admonitionblock {\r
+ margin-right: 10%;\r
+ margin-top: 1.5em;\r
+ margin-bottom: 1.5em;\r
+}\r
+div.admonitionblock {\r
+ margin-top: 2.5em;\r
+ margin-bottom: 2.5em;\r
+}\r
+\r
+div.content { /* Block element content. */\r
+ padding: 0;\r
+}\r
+\r
+/* Block element titles. */\r
+div.title, caption.title {\r
+ font-family: sans-serif;\r
+ font-weight: bold;\r
+ text-align: left;\r
+ margin-top: 1.0em;\r
+ margin-bottom: 0.5em;\r
+}\r
+div.title + * {\r
+ margin-top: 0;\r
+}\r
+\r
+td div.title:first-child {\r
+ margin-top: 0.0em;\r
+}\r
+div.content div.title:first-child {\r
+ margin-top: 0.0em;\r
+}\r
+div.content + div.title {\r
+ margin-top: 0.0em;\r
+}\r
+\r
+div.sidebarblock > div.content {\r
+ background: #ffffee;\r
+ border: 1px solid silver;\r
+ padding: 0.5em;\r
+}\r
+\r
+div.listingblock > div.content {\r
+ border: 1px solid silver;\r
+ background: #f4f4f4;\r
+ padding: 0.5em;\r
+}\r
+\r
+div.quoteblock > div.content {\r
+ padding-left: 2.0em;\r
+}\r
+div.quoteblock .attribution {\r
+ text-align: right;\r
+}\r
+\r
+div.admonitionblock .icon {\r
+ vertical-align: top;\r
+ font-size: 1.1em;\r
+ font-weight: bold;\r
+ text-decoration: underline;\r
+ color: #527bbd;\r
+ padding-right: 0.5em;\r
+}\r
+div.admonitionblock td.content {\r
+ padding-left: 0.5em;\r
+ border-left: 2px solid silver;\r
+}\r
+\r
+div.exampleblock > div.content {\r
+ border-left: 2px solid silver;\r
+ padding: 0.5em;\r
+}\r
+\r
+div.verseblock div.content {\r
+ white-space: pre;\r
+}\r
+\r
+div.imageblock div.content { padding-left: 0; }\r
+div.imageblock img { border: 1px solid silver; }\r
+span.image img { border-style: none; }\r
+\r
+dl {\r
+ margin-top: 0.8em;\r
+ margin-bottom: 0.8em;\r
+}\r
+dt {\r
+ margin-top: 0.5em;\r
+ margin-bottom: 0;\r
+ font-style: italic;\r
+}\r
+dd > *:first-child {\r
+ margin-top: 0;\r
+}\r
+\r
+ul, ol {\r
+ list-style-position: outside;\r
+}\r
+ol.olist2 {\r
+ list-style-type: lower-alpha;\r
+}\r
+\r
+div.tableblock > table {\r
+ border-color: #527bbd;\r
+ border-width: 3px;\r
+}\r
+thead {\r
+ font-family: sans-serif;\r
+ font-weight: bold;\r
+}\r
+tfoot {\r
+ font-weight: bold;\r
+}\r
+\r
+div.hlist {\r
+ margin-top: 0.8em;\r
+ margin-bottom: 0.8em;\r
+}\r
+td.hlist1 {\r
+ vertical-align: top;\r
+ font-style: italic;\r
+ padding-right: 0.8em;\r
+}\r
+td.hlist2 {\r
+ vertical-align: top;\r
+}\r
+\r
+@media print {\r
+ div#footer-badges { display: none; }\r
+}\r
+/* Workarounds for IE6's broken and incomplete CSS2. */\r
+\r
+div.sidebar-content {\r
+ background: #ffffee;\r
+ border: 1px solid silver;\r
+ padding: 0.5em;\r
+}\r
+div.sidebar-title, div.image-title {\r
+ font-family: sans-serif;\r
+ font-weight: bold;\r
+ margin-top: 0.0em;\r
+ margin-bottom: 0.5em;\r
+}\r
+\r
+div.listingblock div.content {\r
+ border: 1px solid silver;\r
+ background: #f4f4f4;\r
+ padding: 0.5em;\r
+}\r
+\r
+div.quoteblock-content {\r
+ padding-left: 2.0em;\r
+}\r
+\r
+div.exampleblock-content {\r
+ border-left: 2px solid silver;\r
+ padding-left: 0.5em;\r
+}\r
+</style>\r
+<title>A tutorial introduction to git: part two</title>\r
+</head>\r
+<body>\r
+<div id="header">\r
+<h1>A tutorial introduction to git: part two</h1>\r
+</div>\r
+<div id="preamble">\r
+<div class="sectionbody">\r
+<p>You should work through <a href="tutorial.html">A tutorial introduction to\r
+git</a> before reading this tutorial.</p>\r
+<p>The goal of this tutorial is to introduce two fundamental pieces of\r
+git's architecture—the object database and the index file—and to\r
+provide the reader with everything necessary to understand the rest\r
+of the git documentation.</p>\r
+</div>\r
+</div>\r
+<h2>The git object database</h2>\r
+<div class="sectionbody">\r
+<p>Let's start a new project and create a small amount of history:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ mkdir test-project\r
+$ cd test-project\r
+$ git init-db\r
+defaulting to local storage area\r
+$ echo 'hello world' > file.txt\r
+$ git add .\r
+$ git commit -a -m "initial commit"\r
+Committing initial tree 92b8b694ffb1675e5975148e1121810081dbdffe\r
+$ echo 'hello world!' >file.txt\r
+$ git commit -a -m "add emphasis"</tt></pre>\r
+</div></div>\r
+<p>What are the 40 digits of hex that git responded to the first commit\r
+with?</p>\r
+<p>We saw in part one of the tutorial that commits have names like this.\r
+It turns out that every object in the git history is stored under\r
+such a 40-digit hex name. That name is the SHA1 hash of the object's\r
+contents; among other things, this ensures that git will never store\r
+the same data twice (since identical data is given an identical SHA1\r
+name), and that the contents of a git object will never change (since\r
+that would change the object's name as well).</p>\r
+<p>We can ask git about this particular object with the cat-file\r
+command—just cut-and-paste from the reply to the initial commit, to\r
+save yourself typing all 40 hex digits:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git cat-file -t 92b8b694ffb1675e5975148e1121810081dbdffe\r
+tree</tt></pre>\r
+</div></div>\r
+<p>A tree can refer to one or more "blob" objects, each corresponding to\r
+a file. In addition, a tree can also refer to other tree objects,\r
+thus creating a directory heirarchy. You can examine the contents of\r
+any tree using ls-tree (remember that a long enough initial portion\r
+of the SHA1 will also work):</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git ls-tree 92b8b694\r
+100644 blob 3b18e512dba79e4c8300dd08aeb37f8e728b8dad file.txt</tt></pre>\r
+</div></div>\r
+<p>Thus we see that this tree has one file in it. The SHA1 hash is a\r
+reference to that file's data:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git cat-file -t 3b18e512\r
+blob</tt></pre>\r
+</div></div>\r
+<p>A "blob" is just file data, which we can also examine with cat-file:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git cat-file blob 3b18e512\r
+hello world</tt></pre>\r
+</div></div>\r
+<p>Note that this is the old file data; so the object that git named in\r
+its response to the initial tree was a tree with a snapshot of the\r
+directory state that was recorded by the first commit.</p>\r
+<p>All of these objects are stored under their SHA1 names inside the git\r
+directory:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ find .git/objects/\r
+.git/objects/\r
+.git/objects/pack\r
+.git/objects/info\r
+.git/objects/3b\r
+.git/objects/3b/18e512dba79e4c8300dd08aeb37f8e728b8dad\r
+.git/objects/92\r
+.git/objects/92/b8b694ffb1675e5975148e1121810081dbdffe\r
+.git/objects/54\r
+.git/objects/54/196cc2703dc165cbd373a65a4dcf22d50ae7f7\r
+.git/objects/a0\r
+.git/objects/a0/423896973644771497bdc03eb99d5281615b51\r
+.git/objects/d0\r
+.git/objects/d0/492b368b66bdabf2ac1fd8c92b39d3db916e59\r
+.git/objects/c4\r
+.git/objects/c4/d59f390b9cfd4318117afde11d601c1085f241</tt></pre>\r
+</div></div>\r
+<p>and the contents of these files is just the compressed data plus a\r
+header identifying their length and their type. The type is either a\r
+blob, a tree, a commit, or a tag. We've seen a blob and a tree now,\r
+so next we should look at a commit.</p>\r
+<p>The simplest commit to find is the HEAD commit, which we can find\r
+from .git/HEAD:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ cat .git/HEAD\r
+ref: refs/heads/master</tt></pre>\r
+</div></div>\r
+<p>As you can see, this tells us which branch we're currently on, and it\r
+tells us this by naming a file under the .git directory, which itself\r
+contains a SHA1 name referring to a commit object, which we can\r
+examine with cat-file:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ cat .git/refs/heads/master\r
+c4d59f390b9cfd4318117afde11d601c1085f241\r
+$ git cat-file -t c4d59f39\r
+commit\r
+$ git cat-file commit c4d59f39\r
+tree d0492b368b66bdabf2ac1fd8c92b39d3db916e59\r
+parent 54196cc2703dc165cbd373a65a4dcf22d50ae7f7\r
+author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500\r
+committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500\r
+\r
+add emphasis</tt></pre>\r
+</div></div>\r
+<p>The "tree" object here refers to the new state of the tree:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git ls-tree d0492b36\r
+100644 blob a0423896973644771497bdc03eb99d5281615b51 file.txt\r
+$ git cat-file commit a0423896\r
+hello world!</tt></pre>\r
+</div></div>\r
+<p>and the "parent" object refers to the previous commit:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-cat-file commit 54196cc2\r
+tree 92b8b694ffb1675e5975148e1121810081dbdffe\r
+author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500\r
+committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500\r
+\r
+initial commit</tt></pre>\r
+</div></div>\r
+<p>The tree object is the tree we examined first, and this commit is\r
+unusual in that it lacks any parent.</p>\r
+<p>Most commits have only one parent, but it is also common for a commit\r
+to have multiple parents. In that case the commit represents a\r
+merge, with the parent references pointing to the heads of the merged\r
+branches.</p>\r
+<p>Besides blobs, trees, and commits, the only remaining type of object\r
+is a "tag", which we won't discuss here; refer to <a href="git-tag.html">git-tag(1)</a>\r
+for details.</p>\r
+<p>So now we know how git uses the object database to represent a\r
+project's history:</p>\r
+<ul>\r
+<li>\r
+<p>\r
+"commit" objects refer to "tree" objects representing the\r
+ snapshot of a directory tree at a particular point in the\r
+ history, and refer to "parent" commits to show how they're\r
+ connected into the project history.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+"tree" objects represent the state of a single directory,\r
+ associating directory names to "blob" objects containing file\r
+ data and "tree" objects containing subdirectory information.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+"blob" objects contain file data without any other structure.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+References to commit objects at the head of each branch are\r
+ stored in files under .git/refs/heads/.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+The name of the current branch is stored in .git/HEAD.\r
+</p>\r
+</li>\r
+</ul>\r
+<p>Note, by the way, that lots of commands take a tree as an argument.\r
+But as we can see above, a tree can be referred to in many different\r
+ways—by the SHA1 name for that tree, by the name of a commit that\r
+refers to the tree, by the name of a branch whose head refers to that\r
+tree, etc.—and most such commands can accept any of these names.</p>\r
+<p>In command synopses, the word "tree-ish" is sometimes used to\r
+designate such an argument.</p>\r
+</div>\r
+<h2>The index file</h2>\r
+<div class="sectionbody">\r
+<p>The primary tool we've been using to create commits is "git commit\r
+-a", which creates a commit including every change you've made to\r
+your working tree. But what if you want to commit changes only to\r
+certain files? Or only certain changes to certain files?</p>\r
+<p>If we look at the way commits are created under the cover, we'll see\r
+that there are more flexible ways creating commits.</p>\r
+<p>Continuing with our test-project, let's modify file.txt again:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ echo "hello world, again" >>file.txt</tt></pre>\r
+</div></div>\r
+<p>but this time instead of immediately making the commit, let's take an\r
+intermediate step, and ask for diffs along the way to keep track of\r
+what's happening:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git diff\r
+--- a/file.txt\r
++++ b/file.txt\r
+@@ -1 +1,2 @@\r
+ hello world!\r
++hello world, again\r
+$ git update-index file.txt\r
+$ git diff</tt></pre>\r
+</div></div>\r
+<p>The last diff is empty, but no new commits have been made, and the\r
+head still doesn't contain the new line:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git-diff HEAD\r
+diff --git a/file.txt b/file.txt\r
+index a042389..513feba 100644\r
+--- a/file.txt\r
++++ b/file.txt\r
+@@ -1 +1,2 @@\r
+ hello world!\r
++hello world, again</tt></pre>\r
+</div></div>\r
+<p>So "git diff" is comparing against something other than the head.\r
+The thing that it's comparing against is actually the index file,\r
+which is stored in .git/index in a binary format, but whose contents\r
+we can examine with ls-files:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git ls-files --stage\r
+100644 513feba2e53ebbd2532419ded848ba19de88ba00 0 file.txt\r
+$ git cat-file -t 513feba2\r
+blob\r
+$ git cat-file blob 513feba2\r
+hello world, again</tt></pre>\r
+</div></div>\r
+<p>So what our "git update-index" did was store a new blob and then put\r
+a reference to it in the index file. If we modify the file again,\r
+we'll see that the new modifications are reflected in the "git-diff"\r
+output:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ echo 'again?' >>file.txt\r
+$ git diff\r
+index 513feba..ba3da7b 100644\r
+--- a/file.txt\r
++++ b/file.txt\r
+@@ -1,2 +1,3 @@\r
+ hello world!\r
+ hello world, again\r
++again?</tt></pre>\r
+</div></div>\r
+<p>With the right arguments, git diff can also show us the difference\r
+between the working directory and the last commit, or between the\r
+index and the last commit:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git diff HEAD\r
+diff --git a/file.txt b/file.txt\r
+index a042389..ba3da7b 100644\r
+--- a/file.txt\r
++++ b/file.txt\r
+@@ -1 +1,3 @@\r
+ hello world!\r
++hello world, again\r
++again?\r
+$ git diff --cached\r
+diff --git a/file.txt b/file.txt\r
+index a042389..513feba 100644\r
+--- a/file.txt\r
++++ b/file.txt\r
+@@ -1 +1,2 @@\r
+ hello world!\r
++hello world, again</tt></pre>\r
+</div></div>\r
+<p>At any time, we can create a new commit using "git commit" (without\r
+the -a option), and verify that the state committed only includes the\r
+changes stored in the index file, not the additional change that is\r
+still only in our working tree:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git commit -m "repeat"\r
+$ git diff HEAD\r
+diff --git a/file.txt b/file.txt\r
+index 513feba..ba3da7b 100644\r
+--- a/file.txt\r
++++ b/file.txt\r
+@@ -1,2 +1,3 @@\r
+ hello world!\r
+ hello world, again\r
++again?</tt></pre>\r
+</div></div>\r
+<p>So by default "git commit" uses the index to create the commit, not\r
+the working tree; the -a option to commit tells it to first update\r
+the index with all changes in the working tree.</p>\r
+<p>Finally, it's worth looking at the effect of "git add" on the index\r
+file:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ echo "goodbye, world" >closing.txt\r
+$ git add closing.txt</tt></pre>\r
+</div></div>\r
+<p>The effect of the "git add" was to add one entry to the index file:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git ls-files --stage\r
+100644 8b9743b20d4b15be3955fc8d5cd2b09cd2336138 0 closing.txt\r
+100644 513feba2e53ebbd2532419ded848ba19de88ba00 0 file.txt</tt></pre>\r
+</div></div>\r
+<p>And, as you can see with cat-file, this new entry refers to the\r
+current contents of the file:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git cat-file blob a6b11f7a\r
+goodbye, word</tt></pre>\r
+</div></div>\r
+<p>The "status" command is a useful way to get a quick summary of the\r
+situation:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git status\r
+#\r
+# Updated but not checked in:\r
+# (will commit)\r
+#\r
+# new file: closing.txt\r
+#\r
+#\r
+# Changed but not updated:\r
+# (use git-update-index to mark for commit)\r
+#\r
+# modified: file.txt\r
+#</tt></pre>\r
+</div></div>\r
+<p>Since the current state of closing.txt is cached in the index file,\r
+it is listed as "updated but not checked in". Since file.txt has\r
+changes in the working directory that aren't reflected in the index,\r
+it is marked "changed but not updated". At this point, running "git\r
+commit" would create a commit that added closing.txt (with its new\r
+contents), but that didn't modify file.txt.</p>\r
+<p>Also, note that a bare "git diff" shows the changes to file.txt, but\r
+not the addition of closing.txt, because the version of closing.txt\r
+in the index file is identical to the one in the working directory.</p>\r
+<p>In addition to being the staging area for new commits, the index file\r
+is also populated from the object database when checking out a\r
+branch, and is used to hold the trees involved in a merge operation.\r
+See the <a href="core-tutorial.txt">core tutorial</a> and the relevant man\r
+pages for details.</p>\r
+</div>\r
+<h2>What next?</h2>\r
+<div class="sectionbody">\r
+<p>At this point you should know everything necessary to read the man\r
+pages for any of the git commands; one good place to start would be\r
+with the commands mentioned in <a href="everday.html">Everyday git</a>. You\r
+should be able to find any unknown jargon in the\r
+<a href="glossary.html">Glosssay</a>.</p>\r
+<p>The <a href="cvs-migration.html">CVS migration</a> document explains how to\r
+import a CVS repository into git, and shows how to use git in a\r
+CVS-like way.</p>\r
+<p>For some interesting examples of git use, see the\r
+<a href="howto-index.html">howtos</a>.</p>\r
+<p>For git developers, the <a href="core-tutorial.html">Core tutorial</a> goes\r
+into detail on the lower-level git mechanisms involved in, for\r
+example, creating a new commit.</p>\r
+</div>\r
+<div id="footer">\r
+<div id="footer-text">\r
+Last updated 22-May-2006 01:09:53 UTC\r
+</div>\r
+</div>\r
+</body>\r
+</html>\r
--- /dev/null
+A tutorial introduction to git: part two
+========================================
+
+You should work through link:tutorial.html[A tutorial introduction to
+git] before reading this tutorial.
+
+The goal of this tutorial is to introduce two fundamental pieces of
+git's architecture--the object database and the index file--and to
+provide the reader with everything necessary to understand the rest
+of the git documentation.
+
+The git object database
+-----------------------
+
+Let's start a new project and create a small amount of history:
+
+------------------------------------------------
+$ mkdir test-project
+$ cd test-project
+$ git init-db
+defaulting to local storage area
+$ echo 'hello world' > file.txt
+$ git add .
+$ git commit -a -m "initial commit"
+Committing initial tree 92b8b694ffb1675e5975148e1121810081dbdffe
+$ echo 'hello world!' >file.txt
+$ git commit -a -m "add emphasis"
+------------------------------------------------
+
+What are the 40 digits of hex that git responded to the first commit
+with?
+
+We saw in part one of the tutorial that commits have names like this.
+It turns out that every object in the git history is stored under
+such a 40-digit hex name. That name is the SHA1 hash of the object's
+contents; among other things, this ensures that git will never store
+the same data twice (since identical data is given an identical SHA1
+name), and that the contents of a git object will never change (since
+that would change the object's name as well).
+
+We can ask git about this particular object with the cat-file
+command--just cut-and-paste from the reply to the initial commit, to
+save yourself typing all 40 hex digits:
+
+------------------------------------------------
+$ git cat-file -t 92b8b694ffb1675e5975148e1121810081dbdffe
+tree
+------------------------------------------------
+
+A tree can refer to one or more "blob" objects, each corresponding to
+a file. In addition, a tree can also refer to other tree objects,
+thus creating a directory heirarchy. You can examine the contents of
+any tree using ls-tree (remember that a long enough initial portion
+of the SHA1 will also work):
+
+------------------------------------------------
+$ git ls-tree 92b8b694
+100644 blob 3b18e512dba79e4c8300dd08aeb37f8e728b8dad file.txt
+------------------------------------------------
+
+Thus we see that this tree has one file in it. The SHA1 hash is a
+reference to that file's data:
+
+------------------------------------------------
+$ git cat-file -t 3b18e512
+blob
+------------------------------------------------
+
+A "blob" is just file data, which we can also examine with cat-file:
+
+------------------------------------------------
+$ git cat-file blob 3b18e512
+hello world
+------------------------------------------------
+
+Note that this is the old file data; so the object that git named in
+its response to the initial tree was a tree with a snapshot of the
+directory state that was recorded by the first commit.
+
+All of these objects are stored under their SHA1 names inside the git
+directory:
+
+------------------------------------------------
+$ find .git/objects/
+.git/objects/
+.git/objects/pack
+.git/objects/info
+.git/objects/3b
+.git/objects/3b/18e512dba79e4c8300dd08aeb37f8e728b8dad
+.git/objects/92
+.git/objects/92/b8b694ffb1675e5975148e1121810081dbdffe
+.git/objects/54
+.git/objects/54/196cc2703dc165cbd373a65a4dcf22d50ae7f7
+.git/objects/a0
+.git/objects/a0/423896973644771497bdc03eb99d5281615b51
+.git/objects/d0
+.git/objects/d0/492b368b66bdabf2ac1fd8c92b39d3db916e59
+.git/objects/c4
+.git/objects/c4/d59f390b9cfd4318117afde11d601c1085f241
+------------------------------------------------
+
+and the contents of these files is just the compressed data plus a
+header identifying their length and their type. The type is either a
+blob, a tree, a commit, or a tag. We've seen a blob and a tree now,
+so next we should look at a commit.
+
+The simplest commit to find is the HEAD commit, which we can find
+from .git/HEAD:
+
+------------------------------------------------
+$ cat .git/HEAD
+ref: refs/heads/master
+------------------------------------------------
+
+As you can see, this tells us which branch we're currently on, and it
+tells us this by naming a file under the .git directory, which itself
+contains a SHA1 name referring to a commit object, which we can
+examine with cat-file:
+
+------------------------------------------------
+$ cat .git/refs/heads/master
+c4d59f390b9cfd4318117afde11d601c1085f241
+$ git cat-file -t c4d59f39
+commit
+$ git cat-file commit c4d59f39
+tree d0492b368b66bdabf2ac1fd8c92b39d3db916e59
+parent 54196cc2703dc165cbd373a65a4dcf22d50ae7f7
+author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500
+committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143418702 -0500
+
+add emphasis
+------------------------------------------------
+
+The "tree" object here refers to the new state of the tree:
+
+------------------------------------------------
+$ git ls-tree d0492b36
+100644 blob a0423896973644771497bdc03eb99d5281615b51 file.txt
+$ git cat-file commit a0423896
+hello world!
+------------------------------------------------
+
+and the "parent" object refers to the previous commit:
+
+------------------------------------------------
+$ git-cat-file commit 54196cc2
+tree 92b8b694ffb1675e5975148e1121810081dbdffe
+author J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
+committer J. Bruce Fields <bfields@puzzle.fieldses.org> 1143414668 -0500
+
+initial commit
+------------------------------------------------
+
+The tree object is the tree we examined first, and this commit is
+unusual in that it lacks any parent.
+
+Most commits have only one parent, but it is also common for a commit
+to have multiple parents. In that case the commit represents a
+merge, with the parent references pointing to the heads of the merged
+branches.
+
+Besides blobs, trees, and commits, the only remaining type of object
+is a "tag", which we won't discuss here; refer to gitlink:git-tag[1]
+for details.
+
+So now we know how git uses the object database to represent a
+project's history:
+
+ * "commit" objects refer to "tree" objects representing the
+ snapshot of a directory tree at a particular point in the
+ history, and refer to "parent" commits to show how they're
+ connected into the project history.
+ * "tree" objects represent the state of a single directory,
+ associating directory names to "blob" objects containing file
+ data and "tree" objects containing subdirectory information.
+ * "blob" objects contain file data without any other structure.
+ * References to commit objects at the head of each branch are
+ stored in files under .git/refs/heads/.
+ * The name of the current branch is stored in .git/HEAD.
+
+Note, by the way, that lots of commands take a tree as an argument.
+But as we can see above, a tree can be referred to in many different
+ways--by the SHA1 name for that tree, by the name of a commit that
+refers to the tree, by the name of a branch whose head refers to that
+tree, etc.--and most such commands can accept any of these names.
+
+In command synopses, the word "tree-ish" is sometimes used to
+designate such an argument.
+
+The index file
+--------------
+
+The primary tool we've been using to create commits is "git commit
+-a", which creates a commit including every change you've made to
+your working tree. But what if you want to commit changes only to
+certain files? Or only certain changes to certain files?
+
+If we look at the way commits are created under the cover, we'll see
+that there are more flexible ways creating commits.
+
+Continuing with our test-project, let's modify file.txt again:
+
+------------------------------------------------
+$ echo "hello world, again" >>file.txt
+------------------------------------------------
+
+but this time instead of immediately making the commit, let's take an
+intermediate step, and ask for diffs along the way to keep track of
+what's happening:
+
+------------------------------------------------
+$ git diff
+--- a/file.txt
++++ b/file.txt
+@@ -1 +1,2 @@
+ hello world!
++hello world, again
+$ git update-index file.txt
+$ git diff
+------------------------------------------------
+
+The last diff is empty, but no new commits have been made, and the
+head still doesn't contain the new line:
+
+------------------------------------------------
+$ git-diff HEAD
+diff --git a/file.txt b/file.txt
+index a042389..513feba 100644
+--- a/file.txt
++++ b/file.txt
+@@ -1 +1,2 @@
+ hello world!
++hello world, again
+------------------------------------------------
+
+So "git diff" is comparing against something other than the head.
+The thing that it's comparing against is actually the index file,
+which is stored in .git/index in a binary format, but whose contents
+we can examine with ls-files:
+
+------------------------------------------------
+$ git ls-files --stage
+100644 513feba2e53ebbd2532419ded848ba19de88ba00 0 file.txt
+$ git cat-file -t 513feba2
+blob
+$ git cat-file blob 513feba2
+hello world, again
+------------------------------------------------
+
+So what our "git update-index" did was store a new blob and then put
+a reference to it in the index file. If we modify the file again,
+we'll see that the new modifications are reflected in the "git-diff"
+output:
+
+------------------------------------------------
+$ echo 'again?' >>file.txt
+$ git diff
+index 513feba..ba3da7b 100644
+--- a/file.txt
++++ b/file.txt
+@@ -1,2 +1,3 @@
+ hello world!
+ hello world, again
++again?
+------------------------------------------------
+
+With the right arguments, git diff can also show us the difference
+between the working directory and the last commit, or between the
+index and the last commit:
+
+------------------------------------------------
+$ git diff HEAD
+diff --git a/file.txt b/file.txt
+index a042389..ba3da7b 100644
+--- a/file.txt
++++ b/file.txt
+@@ -1 +1,3 @@
+ hello world!
++hello world, again
++again?
+$ git diff --cached
+diff --git a/file.txt b/file.txt
+index a042389..513feba 100644
+--- a/file.txt
++++ b/file.txt
+@@ -1 +1,2 @@
+ hello world!
++hello world, again
+------------------------------------------------
+
+At any time, we can create a new commit using "git commit" (without
+the -a option), and verify that the state committed only includes the
+changes stored in the index file, not the additional change that is
+still only in our working tree:
+
+------------------------------------------------
+$ git commit -m "repeat"
+$ git diff HEAD
+diff --git a/file.txt b/file.txt
+index 513feba..ba3da7b 100644
+--- a/file.txt
++++ b/file.txt
+@@ -1,2 +1,3 @@
+ hello world!
+ hello world, again
++again?
+------------------------------------------------
+
+So by default "git commit" uses the index to create the commit, not
+the working tree; the -a option to commit tells it to first update
+the index with all changes in the working tree.
+
+Finally, it's worth looking at the effect of "git add" on the index
+file:
+
+------------------------------------------------
+$ echo "goodbye, world" >closing.txt
+$ git add closing.txt
+------------------------------------------------
+
+The effect of the "git add" was to add one entry to the index file:
+
+------------------------------------------------
+$ git ls-files --stage
+100644 8b9743b20d4b15be3955fc8d5cd2b09cd2336138 0 closing.txt
+100644 513feba2e53ebbd2532419ded848ba19de88ba00 0 file.txt
+------------------------------------------------
+
+And, as you can see with cat-file, this new entry refers to the
+current contents of the file:
+
+------------------------------------------------
+$ git cat-file blob a6b11f7a
+goodbye, word
+------------------------------------------------
+
+The "status" command is a useful way to get a quick summary of the
+situation:
+
+------------------------------------------------
+$ git status
+#
+# Updated but not checked in:
+# (will commit)
+#
+# new file: closing.txt
+#
+#
+# Changed but not updated:
+# (use git-update-index to mark for commit)
+#
+# modified: file.txt
+#
+------------------------------------------------
+
+Since the current state of closing.txt is cached in the index file,
+it is listed as "updated but not checked in". Since file.txt has
+changes in the working directory that aren't reflected in the index,
+it is marked "changed but not updated". At this point, running "git
+commit" would create a commit that added closing.txt (with its new
+contents), but that didn't modify file.txt.
+
+Also, note that a bare "git diff" shows the changes to file.txt, but
+not the addition of closing.txt, because the version of closing.txt
+in the index file is identical to the one in the working directory.
+
+In addition to being the staging area for new commits, the index file
+is also populated from the object database when checking out a
+branch, and is used to hold the trees involved in a merge operation.
+See the link:core-tutorial.txt[core tutorial] and the relevant man
+pages for details.
+
+What next?
+----------
+
+At this point you should know everything necessary to read the man
+pages for any of the git commands; one good place to start would be
+with the commands mentioned in link:everday.html[Everyday git]. You
+should be able to find any unknown jargon in the
+link:glossary.html[Glosssay].
+
+The link:cvs-migration.html[CVS migration] document explains how to
+import a CVS repository into git, and shows how to use git in a
+CVS-like way.
+
+For some interesting examples of git use, see the
+link:howto-index.html[howtos].
+
+For git developers, the link:core-tutorial.html[Core tutorial] goes
+into detail on the lower-level git mechanisms involved in, for
+example, creating a new commit.
<p>At any point you can view the history of your changes using</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git whatchanged</tt></pre>\r
+<pre><tt>$ git log</tt></pre>\r
</div></div>\r
<p>If you also want to see complete diffs at each step, use</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git whatchanged -p</tt></pre>\r
+<pre><tt>$ git log -p</tt></pre>\r
</div></div>\r
</div>\r
<h2>Managing branches</h2>\r
<p>This actually pulls changes from the branch in Bob's repository named\r
"master". Alice could request a different branch by adding the name\r
of the branch to the end of the git pull command line.</p>\r
-<p>This merges Bob's changes into her repository; "git whatchanged" will\r
+<p>This merges Bob's changes into her repository; "git log" will\r
now show the new commits. If Alice has made her own changes in the\r
meantime, then Bob's changes will be merged in, and she will need to\r
manually fix any conflicts.</p>\r
of Bob's line of development without doing any merging). Then</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git whatchanged -p master..bob-incoming</tt></pre>\r
+<pre><tt>$ git log -p master..bob-incoming</tt></pre>\r
</div></div>\r
<p>shows a list of all the changes that Bob made since he branched from\r
Alice's master branch.</p>\r
that various users push changes to; see <a href="git-push.html">git-push(1)</a> and\r
<a href="cvs-migration.html">git for CVS users</a>.</p>\r
</div>\r
-<h2>Keeping track of history</h2>\r
+<h2>Exploring history</h2>\r
<div class="sectionbody">\r
-<p>Git history is represented as a series of interrelated commits. The\r
-most recent commit in the currently checked-out branch can always be\r
-referred to as HEAD, and the "parent" of any commit can always be\r
-referred to by appending a caret, "^", to the end of the name of the\r
-commit. So, for example,</p>\r
+<p>Git history is represented as a series of interrelated commits. We\r
+have already seen that the git log command can list those commits.\r
+Note that first line of each git log entry also gives a name for the\r
+commit:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>git diff HEAD^ HEAD</tt></pre>\r
+<pre><tt>$ git log\r
+commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7\r
+Author: Junio C Hamano <junkio@cox.net>\r
+Date: Tue May 16 17:18:22 2006 -0700\r
+\r
+ merge-base: Clarify the comments on post processing.</tt></pre>\r
</div></div>\r
-<p>shows the difference between the most-recently checked-in state of\r
-the tree and the previous state, and</p>\r
+<p>We can give this name to git show to see the details about this\r
+commit.</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>git diff HEAD^^ HEAD^</tt></pre>\r
+<pre><tt>$ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7</tt></pre>\r
</div></div>\r
-<p>shows the difference between that previous state and the state two\r
-commits ago. Also, HEAD~5 can be used as a shorthand for HEAD^^^^^,\r
-and more generally HEAD~n can refer to the nth previous commit.\r
-Commits representing merges have more than one parent, and you can\r
-specify which parent to follow in that case; see\r
-<a href="git-rev-parse.html">git-rev-parse(1)</a>.</p>\r
-<p>The name of a branch can also be used to refer to the most recent\r
-commit on that branch; so you can also say things like</p>\r
+<p>But there other ways to refer to commits. You can use any initial\r
+part of the name that is long enough to uniquely identify the commit:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>git diff HEAD experimental</tt></pre>\r
+<pre><tt>$ git show c82a22c39c # the first few characters of the name are\r
+ # usually enough\r
+$ git show HEAD # the tip of the current branch\r
+$ git show experimental # the tip of the "experimental" branch</tt></pre>\r
</div></div>\r
-<p>to see the difference between the most-recently committed tree in\r
-the current branch and the most-recently committed tree in the\r
-experimental branch.</p>\r
-<p>But you may find it more useful to see the list of commits made in\r
-the experimental branch but not in the current branch, and</p>\r
+<p>Every commit has at least one "parent" commit, which points to the\r
+previous state of the project:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>git whatchanged HEAD..experimental</tt></pre>\r
+<pre><tt>$ git show HEAD^ # to see the parent of HEAD\r
+$ git show HEAD^^ # to see the grandparent of HEAD\r
+$ git show HEAD~4 # to see the great-great grandparent of HEAD</tt></pre>\r
</div></div>\r
-<p>will do that, just as</p>\r
+<p>Note that merge commits may have more than one parent:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>git whatchanged experimental..HEAD</tt></pre>\r
+<pre><tt>$ git show HEAD^1 # show the first parent of HEAD (same as HEAD^)\r
+$ git show HEAD^2 # show the second parent of HEAD</tt></pre>\r
</div></div>\r
-<p>will show the list of commits made on the HEAD but not included in\r
-experimental.</p>\r
-<p>You can also give commits convenient names of your own: after running</p>\r
+<p>You can also give commits names of your own; after running</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git-tag v2.5 HEAD^^</tt></pre>\r
+<pre><tt>$ git-tag v2.5 1b2e1d63ff</tt></pre>\r
</div></div>\r
-<p>you can refer to HEAD^^ by the name "v2.5". If you intend to share\r
-this name with other people (for example, to identify a release\r
+<p>you can refer to 1b2e1d63ff by the name "v2.5". If you intend to\r
+share this name with other people (for example, to identify a release\r
version), you should create a "tag" object, and perhaps sign it; see\r
<a href="git-tag.html">git-tag(1)</a> for details.</p>\r
-<p>You can revisit the old state of a tree, and make further\r
-modifications if you wish, using git branch: the command</p>\r
+<p>Any git command that needs to know a commit can take any of these\r
+names. For example:</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git branch stable-release v2.5</tt></pre>\r
+<pre><tt>$ git diff v2.5 HEAD # compare the current HEAD to v2.5\r
+$ git branch stable v2.5 # start a new branch named "stable" based\r
+ # at v2.5\r
+$ git reset --hard HEAD^ # reset your current branch and working\r
+ # directory its state at HEAD^</tt></pre>\r
</div></div>\r
-<p>will create a new branch named "stable-release" starting from the\r
-commit which you tagged with the name v2.5.</p>\r
-<p>You can reset the state of any branch to an earlier commit at any\r
-time with</p>\r
+<p>Be careful with that last command: in addition to losing any changes\r
+in the working directory, it will also remove all later commits from\r
+this branch. If this branch is the only branch containing those\r
+commits, they will be lost. (Also, don't use "git reset" on a\r
+publicly-visible branch that other developers pull from, as git will\r
+be confused by history that disappears in this way.)</p>\r
+<p>The git grep command can search for strings in any version of your\r
+project, so</p>\r
<div class="listingblock">\r
<div class="content">\r
-<pre><tt>$ git reset --hard v2.5</tt></pre>\r
+<pre><tt>$ git grep "hello" v2.5</tt></pre>\r
+</div></div>\r
+<p>searches for all occurences of "hello" in v2.5.</p>\r
+<p>If you leave out the commit name, git grep will search any of the\r
+files it manages in your current directory. So</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git grep "hello"</tt></pre>\r
+</div></div>\r
+<p>is a quick way to search just the files that are tracked by git.</p>\r
+<p>Many git commands also take sets of commits, which can be specified\r
+in a number of ways. Here are some examples with git log:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git log v2.5..v2.6 # commits between v2.5 and v2.6\r
+$ git log v2.5.. # commits since v2.5\r
+$ git log --since="2 weeks ago" # commits from the last 2 weeks\r
+$ git log v2.5.. Makefile # commits since v2.5 which modify\r
+ # Makefile</tt></pre>\r
+</div></div>\r
+<p>You can also give git log a "range" of commits where the first is not\r
+necessarily an ancestor of the second; for example, if the tips of\r
+the branches "stable-release" and "master" diverged from a common\r
+commit some time ago, then</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git log stable..experimental</tt></pre>\r
+</div></div>\r
+<p>will list commits made in the experimental branch but not in the\r
+stable branch, while</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git log experimental..stable</tt></pre>\r
+</div></div>\r
+<p>will show the list of commits made on the stable branch but not\r
+the experimental branch.</p>\r
+<p>The "git log" command has a weakness: it must present commits in a\r
+list. When the history has lines of development that diverged and\r
+then merged back together, the order in which "git log" presents\r
+those commits is meaningless.</p>\r
+<p>Most projects with multiple contributors (such as the linux kernel,\r
+or git itself) have frequent merges, and gitk does a better job of\r
+visualizing their history. For example,</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ gitk --since="2 weeks ago" drivers/</tt></pre>\r
+</div></div>\r
+<p>allows you to browse any commits from the last 2 weeks of commits\r
+that modified files under the "drivers" directory.</p>\r
+<p>Finally, most commands that take filenames will optionally allow you\r
+to precede any filename by a commit, to specify a particular version\r
+fo the file:</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git diff v2.5:Makefile HEAD:Makefile.in</tt></pre>\r
</div></div>\r
-<p>This will remove all later commits from this branch and reset the\r
-working tree to the state it had when the given commit was made. If\r
-this branch is the only branch containing the later commits, those\r
-later changes will be lost. Don't use "git reset" on a\r
-publicly-visible branch that other developers pull from, as git will\r
-be confused by history that disappears in this way.</p>\r
</div>\r
<h2>Next Steps</h2>\r
<div class="sectionbody">\r
-<p>Some good commands to explore next:</p>\r
+<p>This tutorial should be enough to perform basic distributed revision\r
+control for your projects. However, to fully understand the depth\r
+and power of git you need to understand two simple ideas on which it\r
+is based:</p>\r
<ul>\r
<li>\r
<p>\r
-<a href="git-diff.html">git-diff(1)</a>: This flexible command does much more than\r
- we've seen in the few examples above.\r
+The object database is the rather elegant system used to\r
+ store the history of your project—files, directories, and\r
+ commits.\r
</p>\r
</li>\r
<li>\r
<p>\r
+The index file is a cache of the state of a directory tree,\r
+ used to create commits, check out working directories, and\r
+ hold the various trees involved in a merge.\r
+</p>\r
+</li>\r
+</ul>\r
+<p><a href="tutorial-2.html">Part two of this tutorial</a> explains the object\r
+database, the index file, and a few other odds and ends that you'll\r
+need to make the most of git.</p>\r
+<p>If you don't want to consider with that right away, a few other\r
+digressions that may be interesting at this point are:</p>\r
+<ul>\r
+<li>\r
+<p>\r
<a href="git-format-patch.html">git-format-patch(1)</a>, <a href="git-am.html">git-am(1)</a>: These convert\r
series of git commits into emailed patches, and vice versa,\r
useful for projects such as the linux kernel which rely heavily\r
case of complex non-linear history with lots of merged branches.\r
</p>\r
</li>\r
+<li>\r
+<p>\r
+<a href="everyday.html">Everday GIT with 20 Commands Or So</a>\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<a href="cvs-migration.html">git for CVS users</a>.\r
+</p>\r
+</li>\r
</ul>\r
-<p>Other good starting points include <a href="everyday.html">Everday GIT\r
-with 20 Commands Or So</a> and <a href="cvs-migration.html">git for CVS\r
-users</a>. Also, <a href="core-tutorial.html">A short git tutorial</a> gives an\r
-introduction to lower-level git commands for advanced users and\r
-developers.</p>\r
</div>\r
<div id="footer">\r
<div id="footer-text">\r
-Last updated 05-Mar-2006 10:51:09 UTC\r
+Last updated 22-May-2006 01:09:52 UTC\r
</div>\r
</div>\r
</body>\r
At any point you can view the history of your changes using
------------------------------------------------
-$ git whatchanged
+$ git log
------------------------------------------------
If you also want to see complete diffs at each step, use
------------------------------------------------
-$ git whatchanged -p
+$ git log -p
------------------------------------------------
Managing branches
"master". Alice could request a different branch by adding the name
of the branch to the end of the git pull command line.
-This merges Bob's changes into her repository; "git whatchanged" will
+This merges Bob's changes into her repository; "git log" will
now show the new commits. If Alice has made her own changes in the
meantime, then Bob's changes will be merged in, and she will need to
manually fix any conflicts.
of Bob's line of development without doing any merging). Then
-------------------------------------
-$ git whatchanged -p master..bob-incoming
+$ git log -p master..bob-incoming
-------------------------------------
shows a list of all the changes that Bob made since he branched from
that various users push changes to; see gitlink:git-push[1] and
link:cvs-migration.html[git for CVS users].
-Keeping track of history
-------------------------
+Exploring history
+-----------------
-Git history is represented as a series of interrelated commits. The
-most recent commit in the currently checked-out branch can always be
-referred to as HEAD, and the "parent" of any commit can always be
-referred to by appending a caret, "^", to the end of the name of the
-commit. So, for example,
+Git history is represented as a series of interrelated commits. We
+have already seen that the git log command can list those commits.
+Note that first line of each git log entry also gives a name for the
+commit:
-------------------------------------
-git diff HEAD^ HEAD
+$ git log
+commit c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
+Author: Junio C Hamano <junkio@cox.net>
+Date: Tue May 16 17:18:22 2006 -0700
+
+ merge-base: Clarify the comments on post processing.
-------------------------------------
-shows the difference between the most-recently checked-in state of
-the tree and the previous state, and
+We can give this name to git show to see the details about this
+commit.
-------------------------------------
-git diff HEAD^^ HEAD^
+$ git show c82a22c39cbc32576f64f5c6b3f24b99ea8149c7
-------------------------------------
-shows the difference between that previous state and the state two
-commits ago. Also, HEAD~5 can be used as a shorthand for HEAD{caret}{caret}{caret}{caret}{caret},
-and more generally HEAD~n can refer to the nth previous commit.
-Commits representing merges have more than one parent, and you can
-specify which parent to follow in that case; see
-gitlink:git-rev-parse[1].
+But there other ways to refer to commits. You can use any initial
+part of the name that is long enough to uniquely identify the commit:
+
+-------------------------------------
+$ git show c82a22c39c # the first few characters of the name are
+ # usually enough
+$ git show HEAD # the tip of the current branch
+$ git show experimental # the tip of the "experimental" branch
+-------------------------------------
-The name of a branch can also be used to refer to the most recent
-commit on that branch; so you can also say things like
+Every commit has at least one "parent" commit, which points to the
+previous state of the project:
-------------------------------------
-git diff HEAD experimental
+$ git show HEAD^ # to see the parent of HEAD
+$ git show HEAD^^ # to see the grandparent of HEAD
+$ git show HEAD~4 # to see the great-great grandparent of HEAD
-------------------------------------
-to see the difference between the most-recently committed tree in
-the current branch and the most-recently committed tree in the
-experimental branch.
+Note that merge commits may have more than one parent:
-But you may find it more useful to see the list of commits made in
-the experimental branch but not in the current branch, and
+-------------------------------------
+$ git show HEAD^1 # show the first parent of HEAD (same as HEAD^)
+$ git show HEAD^2 # show the second parent of HEAD
+-------------------------------------
+
+You can also give commits names of your own; after running
-------------------------------------
-git whatchanged HEAD..experimental
+$ git-tag v2.5 1b2e1d63ff
-------------------------------------
-will do that, just as
+you can refer to 1b2e1d63ff by the name "v2.5". If you intend to
+share this name with other people (for example, to identify a release
+version), you should create a "tag" object, and perhaps sign it; see
+gitlink:git-tag[1] for details.
+
+Any git command that needs to know a commit can take any of these
+names. For example:
-------------------------------------
-git whatchanged experimental..HEAD
+$ git diff v2.5 HEAD # compare the current HEAD to v2.5
+$ git branch stable v2.5 # start a new branch named "stable" based
+ # at v2.5
+$ git reset --hard HEAD^ # reset your current branch and working
+ # directory its state at HEAD^
-------------------------------------
-will show the list of commits made on the HEAD but not included in
-experimental.
+Be careful with that last command: in addition to losing any changes
+in the working directory, it will also remove all later commits from
+this branch. If this branch is the only branch containing those
+commits, they will be lost. (Also, don't use "git reset" on a
+publicly-visible branch that other developers pull from, as git will
+be confused by history that disappears in this way.)
-You can also give commits convenient names of your own: after running
+The git grep command can search for strings in any version of your
+project, so
-------------------------------------
-$ git-tag v2.5 HEAD^^
+$ git grep "hello" v2.5
-------------------------------------
-you can refer to HEAD^^ by the name "v2.5". If you intend to share
-this name with other people (for example, to identify a release
-version), you should create a "tag" object, and perhaps sign it; see
-gitlink:git-tag[1] for details.
+searches for all occurences of "hello" in v2.5.
-You can revisit the old state of a tree, and make further
-modifications if you wish, using git branch: the command
+If you leave out the commit name, git grep will search any of the
+files it manages in your current directory. So
-------------------------------------
-$ git branch stable-release v2.5
+$ git grep "hello"
-------------------------------------
-will create a new branch named "stable-release" starting from the
-commit which you tagged with the name v2.5.
+is a quick way to search just the files that are tracked by git.
-You can reset the state of any branch to an earlier commit at any
-time with
+Many git commands also take sets of commits, which can be specified
+in a number of ways. Here are some examples with git log:
-------------------------------------
-$ git reset --hard v2.5
+$ git log v2.5..v2.6 # commits between v2.5 and v2.6
+$ git log v2.5.. # commits since v2.5
+$ git log --since="2 weeks ago" # commits from the last 2 weeks
+$ git log v2.5.. Makefile # commits since v2.5 which modify
+ # Makefile
-------------------------------------
-This will remove all later commits from this branch and reset the
-working tree to the state it had when the given commit was made. If
-this branch is the only branch containing the later commits, those
-later changes will be lost. Don't use "git reset" on a
-publicly-visible branch that other developers pull from, as git will
-be confused by history that disappears in this way.
+You can also give git log a "range" of commits where the first is not
+necessarily an ancestor of the second; for example, if the tips of
+the branches "stable-release" and "master" diverged from a common
+commit some time ago, then
+
+-------------------------------------
+$ git log stable..experimental
+-------------------------------------
+
+will list commits made in the experimental branch but not in the
+stable branch, while
+
+-------------------------------------
+$ git log experimental..stable
+-------------------------------------
+
+will show the list of commits made on the stable branch but not
+the experimental branch.
+
+The "git log" command has a weakness: it must present commits in a
+list. When the history has lines of development that diverged and
+then merged back together, the order in which "git log" presents
+those commits is meaningless.
+
+Most projects with multiple contributors (such as the linux kernel,
+or git itself) have frequent merges, and gitk does a better job of
+visualizing their history. For example,
+
+-------------------------------------
+$ gitk --since="2 weeks ago" drivers/
+-------------------------------------
+
+allows you to browse any commits from the last 2 weeks of commits
+that modified files under the "drivers" directory.
+
+Finally, most commands that take filenames will optionally allow you
+to precede any filename by a commit, to specify a particular version
+fo the file:
+
+-------------------------------------
+$ git diff v2.5:Makefile HEAD:Makefile.in
+-------------------------------------
Next Steps
----------
-Some good commands to explore next:
+This tutorial should be enough to perform basic distributed revision
+control for your projects. However, to fully understand the depth
+and power of git you need to understand two simple ideas on which it
+is based:
- * gitlink:git-diff[1]: This flexible command does much more than
- we've seen in the few examples above.
+ * The object database is the rather elegant system used to
+ store the history of your project--files, directories, and
+ commits.
+
+ * The index file is a cache of the state of a directory tree,
+ used to create commits, check out working directories, and
+ hold the various trees involved in a merge.
+
+link:tutorial-2.html[Part two of this tutorial] explains the object
+database, the index file, and a few other odds and ends that you'll
+need to make the most of git.
+
+If you don't want to consider with that right away, a few other
+digressions that may be interesting at this point are:
* gitlink:git-format-patch[1], gitlink:git-am[1]: These convert
series of git commits into emailed patches, and vice versa,
smart enough to perform a close-to-optimal search even in the
case of complex non-linear history with lots of merged branches.
-Other good starting points include link:everyday.html[Everday GIT
-with 20 Commands Or So] and link:cvs-migration.html[git for CVS
-users]. Also, link:core-tutorial.html[A short git tutorial] gives an
-introduction to lower-level git commands for advanced users and
-developers.
+ * link:everyday.html[Everday GIT with 20 Commands Or So]
+
+ * link:cvs-migration.html[git for CVS users].
projects / git.git / commitdiff